GTM Bridge & GA4 Event Bridge

Unifying quantitative Google Analytics 4 telemetry with qualitative MousePlayer session replays through bidirectional dataLayer synchronization and GA4-compatible APIs.

1. Architectural Overview & Capabilities

Modern web analytics often suffers from a fundamental data silo: quantitative platforms (such as Google Analytics 4) report what happened on a website, while qualitative session replay tools explain why it happened. The MousePlayer GTM & GA4 Bridge eliminates this gap by establishing a two-way synchronization channel inside the browser's JavaScript runtime.

When activated, the tracking script initializes two dedicated core modules:

  • Session Replay Exporter (initGa4SessionBridge): Automatically pushes the active recording session identifier (mp_session_id) and a direct playback URL (mp_session_url) into the website's data layer as soon as the session is established.
  • GA4 Event Ingestor (initDataLayerBridge): Attaches a non-destructive listener to the data layer array. Any custom e-commerce or behavioral event pushed for GA4 is immediately mirrored into the MousePlayer analytics database as a custom event (ce), including all numerical and string parameters.

Custom dataLayer Object Support: If a web application uses a customized JavaScript array name instead of the standard dataLayer (for example, xyzDataLayer), the engine dynamically adapts to the configured gtm_datalayer_name parameter without requiring manual code modifications.

2. Strategic Business Value

Integrating session replay links directly into enterprise analytics pipelines provides several high-impact operational advantages:

Business Capability Operational Impact
Conversion Rate Optimization (CRO) Allows digital analysts to identify friction points in GA4 conversion funnels and immediately launch recordings of users who abandoned shopping carts at specific checkout steps.
Revenue Attribution & Auditing High-value e-commerce transactions can be audited by reviewing the exact cursor trajectories, clicks, and viewport states that led to a purchase.
Accelerated Technical Debugging QA engineering teams can correlate GA4 JavaScript exception events or API error logs directly with visual screen recordings, eliminating the need to reproduce bugs manually.
Customer Support Resolution Support tickets containing user session IDs allow support agents to review the customer's exact session replay, drastically reducing resolution times.

3. Google Tag Manager Configuration Guide

To capture the replay URL inside Google Tag Manager and route it to Google Analytics 4, three distinct GTM assets must be configured:

Step 1: Create Data Layer Variables

In the GTM workspace, navigate to Variables → User-Defined Variables and create two variables of type Data Layer Variable:

  • Variable Name: dlv - mp_session_id • Data Layer Variable Name: mp_session_id
  • Variable Name: dlv - mp_session_url • Data Layer Variable Name: mp_session_url

Step 2: Create the Activation Trigger

Navigate to Triggers → New and select the trigger type Custom Event. Configure the following parameters:

  • Event Name: mp_session_ready
  • This trigger fires on: All Custom Events

Step 3: Configure the GA4 Event Tag

Create a new tag of type Google Analytics: GA4 Event to transmit the session link to the GA4 property:

# GA4 Event Tag Configuration Tag Type: Google Analytics: GA4 Event Configuration Tag: [Select standard GA4 Configuration Tag] Event Name: mp_recording_ready # Event Parameters: | Parameter Name | Value | |-----------------|---------------------------| | mp_session_id | {{dlv - mp_session_id}} | | mp_session_url | {{dlv - mp_session_url}} | Triggering: Fire on Custom Event -> mp_session_ready

4. Configuring Explorations (Custom Reports) in GA4

Once the GTM tag is deployed, GA4 begins receiving the playback URL as an event parameter. To analyze this data in custom exploration reports, the parameter must first be registered as a Custom Dimension.

Registering Custom Dimensions in GA4 Admin

In the Google Analytics 4 interface, navigate to Admin → Data display → Custom definitions and click Create custom dimension:

  • Dimension name: MousePlayer Session URL
  • Scope: Event (or Session if attached to session-scoped parameters)
  • Event parameter: mp_session_url

Building a Session Inspection Exploration

In the Explore section of GA4, create a new Free form exploration to inspect individual user journeys:

  • Rows: Add Event name, Transaction ID (for e-commerce), or Landing page.
  • Columns / Dimensions: Include the newly created custom dimension MousePlayer Session URL.
  • Values: Add Event count or Total users.

The generated report table displays direct clickable URLs alongside GA4 metrics, allowing instant transitions from statistical outliers to visual replays.

5. Integrating Replay URLs into GA4 Default Reports

In addition to Explorations, custom dimensions can be integrated into standard GA4 default reports (such as Traffic acquisition, Pages and screens, or E-commerce purchases) using the GA4 Report Library.

Modifying Standard Report Tables

  1. In GA4, open any default detailed report (e.g., Reports → Engagement → Pages and screens).
  2. Click the Customize report pencil icon in the upper right corner (administrative access required).
  3. In the right-hand panel under Report Data, click Dimensions.
  4. Add MousePlayer Session URL to the primary or secondary dimension list and set it as visible.
  5. Click Save → Save changes to current report.

Once saved, any analyst reviewing standard acquisition or conversion tables can add MousePlayer Session URL as a secondary dimension, enabling immediate visual inspection of visitor behaviors across standard traffic segments.

6. JavaScript API & GA4 / GTM Compatibility Reference

MousePlayer provides an intuitive, GA4-compatible JavaScript API (using standard gtag()-style commands) and a public global object (window.MousePlayer). This allows developers to query session URLs in the console, attach B2B customer IDs, and inject replay links into third-party helpdesks or error trackers.

1. Direct Replay URL Injection (Intercom / Zendesk / Custom Bridges)

You can retrieve the full playback URL of the active visitor session directly from the browser console or any custom script using window.MousePlayer.getSessionUrl():

// Example: Retrieve the active session URL and attach it to Intercom chat metadata if (window.MousePlayer && window.MousePlayer.getSessionUrl) { var replayUrl = window.MousePlayer.getSessionUrl(); console.log('Active Replay:', replayUrl); // Attach to Intercom Messenger metadata if (window.Intercom) { Intercom('update', { 'mouseplayer_replay_url': replayUrl }); } }

2. Setting Custom B2B Customer IDs (user_id)

To identify logged-in SaaS or B2B customers, you can pass a custom user_id (such as a database ID, email, or UUID) either during initial script configuration or dynamically at runtime using GA4 syntax:

// Method A: Set user_id dynamically at login (GA4 / gtag style) mp('set', 'user_id', 'USR-987654'); // Method B: Set via config object mp('config', 'YOUR_CHANNEL_ID', { user_id: 'USR-987654' }); // Method C: Direct SDK invocation window.MousePlayer.setUserId('USR-987654');

3. Asynchronous Data Retrieval Methods

You can use standard GA4 callback syntax to retrieve session metadata asynchronously inside custom tag management scripts:

// Retrieve active session URL mp('get', 'session_url', function(url) { console.log('Session URL:', url); }); // Retrieve visitor ID (Client ID equivalent) mp('get', 'client_id', function(clientId) { console.log('Visitor ID:', clientId); });

All trademarks named here belong to their respective owners. MousePlayer has no business relationship with these providers.