Mautic Audiences

What it does

Mautic Audiences turns the segments and tags a visitor has in Mautic into a first-class Drupal primitive: a single resolver service that every audience-aware feature on the site can consult, without anyone re-implementing the wiring.

The resolver reads from local stores (user.data for authenticated users, keyvalue.expirable for anonymous visitors keyed by the mtc_id cookie). The Mautic API is only touched on webhook receipt, cron reconciliation, or a manual Drush sync, never on the render path. Two visitors in the same audience share the same cache entries because cache contexts key on the resolved audience, not on the cookie.

What you can build

• Block visibility (no code): place any block, add a Mautic segment or Mautic tag condition, list the aliases one per line, pick any / all, optionally negate.
• Layout Builder block visibility: blocks placed inside Layout Builder sections expose the same visibility form as classic block placement, so the Mautic segment / Mautic tag conditions are available out of the box. The conditions are plain ConditionInterface plugins with no required context, so Paragraphs visibility, page-manager variants, and any future section-visibility module pick them up too. For per-content visibility that travels across every placement, pair with Block Content Visibility.
• Global Views filter Visitor Mautic audience matches: hide every result of a view unless the current visitor's audience matches.
• Twig functions: is_in_segment(name|names, mode), has_tag(name|names, mode), current_audiences().
• Tokens: [mautic-audience:in-segment-X], [mautic-audience:has-tag-Y], plus allowlisted joined-string tokens for metatag patterns.
• JavaScript API: Drupal.mauticAudiences.hasSegment(name) / .hasTag(name), backed by a small /mautic-audiences/me endpoint with Cache-Control: private so the page shell stays edge-cacheable.
• Preview-as-audience: editors with the right permission can append ?ma_preview_segments=vip,newsletter&ma_preview_tags=lead to any URL.
• Editorial debug page at /admin/reports/mautic-audiences: snapshot of what the resolver sees for the current viewer, arbitrary lookup by user / email / Mautic contact id, force-refresh, operational counters, live Twig preview.

Why this module

• Render-path personalisation, zero API calls. Mautic is the source of truth; this module is the cache + dispatch layer.
• Audience-shaped cache. Custom cache contexts hash on segments + tags, so cache fragments by audience, not by cookie. No cookies:mtc_id blowup.
• Privacy by default. Boolean checks need no allowlist; enumeration always does. Joined-string tokens and the /me endpoint emit only allowlisted segment names. Coupon codes and risk-scoring tags stay server-side unless explicitly opted in.
• Edge-friendly. Recipes for Cloudflare / Varnish; BigPipe by default, AJAX-fill as alternative.
• GDPR-aware. A consent_callback hook lets you gate the resolver on the visitor's consent state. Optional sub-module mautic_audiences_klaro ships a ready-made wiring for the Klaro consent manager.

Requirements

• Drupal ^10.3 || ^11
• PHP ^8.2
• Advanced Mautic Integration ^1.0, provides the API client and tracking script.

Installation

composer require drupal/mautic_audiences
drush pm:install mautic_audiences

Then visit /admin/config/services/mautic-audiences to set the webhook secret (or put it in $settings['mautic_audiences.webhook_secret']), pick an identity strategy, and configure the client-side exposure allowlist.

Related modules

Mautic Audiences is the render-time consumer of audience data. Pair it with one or more of the following depending on what your site does:

• Commerce Mautic Connect, Drupal Commerce ↔ Mautic glue: abandoned-cart recovery, magic-link checkout, customer metrics (RFM), coupon-tag attribution. The segments and tags it pushes to Mautic become the audiences this module resolves at render time.
• Block Content Visibility, surfaces Drupal core's Condition Plugin UI on block_content add/edit forms, so a Mautic segment / Mautic tag visibility set on a reusable block applies across every placement (multi-region, Layout Builder inline blocks, translations, moderation revisions). Especially useful for personalised promo banners.
• Klaro, consent manager. Pair with the bundled mautic_audiences_klaro sub-module to gate audience reads on visitor consent.

Documentation

Bundled with the module under docs/:

• PRD, full Product Requirements Document.
• Security, threat model, exposure surfaces, allowlist semantics, secret rotation, GDPR + consent recipe.
• Webhook setup, Mautic-side configuration, payload anatomy, HMAC validation, idempotency, flood control.
• JavaScript, Drupal.mauticAudiences API, batching, caching, recipes.
• Twig and tokens, Twig functions, tokens, cache-context responsibilities.
• Layout Builder, section visibility, cache implications, recommended companion module.
• CDN, Cloudflare and Varnish recipes, BigPipe vs AJAX-fill, headers reference.

Maintainers

Maintained by introfini (José Fernandes) at Bloomidea. Patches and issues welcome at the project issue queue.