mautic_personalisation

Integrates with Mautic tracking script to capture segment data and provides conditions based on Mautic segments.

IMPORTANT: Requires the "Segments tracking" Mautic plugin to be enabled on your Mautic installation.

Prerequisites

Mautic Plugin Installation

This module requires the segment-tracking plugin to be installed on your Mautic instance. This plugin is responsible for firing the mauticPageEventDelivered event that the Drupal module listens for to capture segment data.

Mautic Tracking Script

The Mautic tracking script (mtc.js) must be loaded on your Drupal site. The placement of the script tag should be before the closing

</code> tag in order for it to work correctly.</p>
<h2 id="user-content-cors-configuration">CORS Configuration<a href="#cors-configuration" aria-label="Link to heading 'CORS Configuration'" data-heading-content="CORS Configuration" class="anchor"></a>
</h2>
<p><strong>Note</strong>: CORS (Cross-Origin Resource Sharing) may need to be configured on the <strong>Mautic side</strong> if your Mautic instance is on a different domain than your Drupal site. This is required for the Mautic tracking script (<code>mtc.js

) to function properly, not specifically for this module's functionality.

Tracking Script Verification

Verify Mautic Tracking Script is Loaded

1. Browser Console Check:

   • Open browser developer tools.
   • Go to the Console tab
   • Type MauticJS or window.MauticJS and press Enter
   • You should see the Mautic tracking object with properties like:
     • contactIdUrl: The URL of your Mautic instance's tracking endpoint
     • CORSRequestsAllowed: Boolean indicating CORS configuration
     • Various tracking functions (deliverPageEvent, dispatchEvent, etc.)
   • Alternatively, you can check window.mt or mt for the Mautic tracking function object

2. HTML Source Check:

   • View page source.
   • Search for mtc.js in the HTML
   • Verify the script tag is present before
     

     </code>
     </li>
     <li>The script should load from your Mautic instance URL</li>
     </ul>
     </li>
     <li>
     <p><strong>Network Tab Check</strong>:</p>
     <ul>
     <li>Open browser developer tools → Network tab</li>
     <li>Reload the page</li>
     <li>Look for requests to <code>/mtc.js

     and /mtc/event endpoints

   • Verify these requests are successful (status 200)

How It Works

1. Event Listener: The module listens for the mauticPageEventDelivered custom event fired by Mautic's segment-tracking plugin when tracking responses are received.
2. Cookie Storage: Segment aliases are extracted from the event data and stored in a configurable cookie (default: MAUTIC_SEGMENT) for server-side access. The cookie name can be customized via the module's settings form.
3. Condition Usage: Content can be configured to show/hide based on specific Mautic segment aliases using the Mautic Segment condition plugin.

Technical Implementation

The module uses a class-based JavaScript implementation (MauticSegmentCookie) that:

• Listens for the mauticPageEventDelivered event from Mautic's segment-tracking plugin
• Normalizes segment data (handles arrays, objects, or null values)
• Sets a cookie with the segment aliases for server-side condition evaluation
• Uses the cookie name from Drupal settings (configured via the settings form and passed via drupalSettings)

The cookie name is managed through the module's configuration system (mautic_personalisation.settings) and can be accessed server-side via the MauticCookieManager service.

Configuration

Cookie Name Settings

The cookie name used for storing Mautic segment data can be configured through the module's settings form:

1. Navigate to Configuration > Web services > Mautic Personalisation (/admin/config/services/mautic-personalisation)
2. Enter your desired cookie name in the "Cookie name" field
3. Click "Save configuration"

Note: If the cookie name field is left empty, the module will use the default value MAUTIC_SEGMENT. The cookie name can be up to 255 characters long.

Alternatively, you can access the settings form directly from the module's page on the Extend page (/admin/modules) by clicking the "Configure" link next to the module name.

Usage

Using the Condition

1. Edit a block and go to the "Visibility" section.
2. Select "Mautic Segment" condition.
3. Enter segment aliases (one per line) for which the block should be visible.
4. Leave empty to show for everyone, or use _unknown to show only until a segment is determined.

Cookie Behavior

• Cookie name: Configurable via the settings form (default: MAUTIC_SEGMENT)
• Value format: Comma-separated segment aliases (e.g., segment1, segment2)
• Default value: _unknown (when no segments are detected or segments are removed)
• Expiration: 1 year