Integrating With Google Analytics 4

Overview

Piano can send Composer experience events to GA4 when you configure GA4 within your Composer integration script. All Google Analytics scripts are loaded via the Piano JavaScript library and injected into your pages directly, making them compliant with the browser's Security Policies and ITP. GA4 configuration is done in the Composer integration code using tp.setGA4Config(...).

Prerequisites

• A GA4 property and Measurement ID (format: G-XXXXXXXXXX). You can find it in GA4 Admin → Data Streams → (your web stream).

• Access to Composer → Integrate → Edit source to update and publish your integration script.

Configure GA4 in the Composer Integration Script

1. From the Piano dashboard, go to the Composer section under the Products menu.

2. Open the integration script by clicking Integrate and then Edit source.

3. Add tp.setGA4Config(...) inside your tp.push(["init", function () { ... }]) block.

4. Click Publish.

tp.push(["init", function () {
    // ... integration code here
    tp.setGA4Config({
        measurementId: 'G-XXXXXXXXXXX',
        eventParameters: {
            // Recommended to avoid double-counting page views if GA4 is already tracking them
            send_page_view: false,

            // Optional examples (set these appropriately for your implementation)
            page_location: 'https://example.com/',
            page_title: 'some_title',
            user_id: 'some_user_id',
        }
    });
}]);

The snippet includes a config command that sends a pageview by default. You can include additional eventParameters to customize how GA4 is initialized. Any valid GA4 configuration parameters are accepted in the eventParameters object, including standard parameters like send_page_view, page_location, page_title, and user_id, as well as custom dimensions and other GA4 parameters.

You can check if the GA4 measurement ID is being set properly on your website using tp.ga4Service.getMeasurementId() in the browser console. It will return the measurement ID value (G-XXXXXXXXXXX) if the GA4 integration is properly configured.

Custom Dimensions

You can send custom dimensions to GA4 through the eventParameters object using the custom_map property. This allows you to map custom dimension slots to named parameters and send their values along with the GA4 configuration.

tp.setGA4Config({
    measurementId: 'G-XXXXXXXXXX',
    eventParameters: {
        'custom_map': {
            'dimension1': 'test-dim1',
            'dimension2': 'test-dim2',
            'dimension3': 'test-dim3',
        },
        'test-dim1': 'test 1',
        'test-dim2': 'test 2',
        'test-dim3': 'test 3',
    }
});

For more information on custom dimensions in GA4, refer to the official Google Analytics documentation.

Excluding Events from GA4

You can manage which events are sent to GA4 by adding the tp.setExcludedGAEvents() directive before tp.setGA4Config() in your init block. Parameters set to true will not be sent to GA4.

tp.push(["init", function () {
    // ... integration code here
    tp.setExcludedGAEvents({
        showOffer: true,
        promoInvalid: true,
        //... other parameters here
    });
    tp.setGA4Config({
        measurementId: 'G-XXXXXXXXXXX',
        //... parameters here
    });
}]);

Placement Notes

• tp.setGA4Config(...) must run during initialization (inside tp.push(["init", ...])).

• It can be placed above or below tp.experience.init() within the init function; the critical requirement is that it executes as part of integration initialization on your pages.

Google Analytics Events Captured

After integration, a number of events from the Piano checkout, Composer, login, and logout process will automatically be captured in GA4. The values sent as the event category are the ID(s) of the template(s) involved in the event.

Events Table

Verifying the Integration

GA4 Realtime Report

1. Trigger a Composer experience on your site (for example, show an offer, start checkout, or complete registration).

2. In GA4, open Realtime and look for incoming events.

Realtime is the fastest validation method. Standard GA4 reports can lag — often minutes to hours, and in some cases up to 24 hours.

Browser Developer Tools

Open browser dev tools → Network tab and look for GA4 collection requests to:

If those requests appear when Composer events fire, the integration is working.

Common Issues and Troubleshooting

Events Do Not Appear in GA4

Check the following:

• The Measurement ID is correct and includes the G- prefix.

• tp.setGA4Config(...) is present in the published Composer integration script.

• The init callback is executing on the pages where you expect events.

• Use GA4 Realtime first — if events appear there but not elsewhere, this is typically a GA4 reporting or configuration issue (see below).

Events Appear in Realtime but Not in Standard Reports

GA4 reporting and event inclusion in specific report surfaces (for example, Engagement) can require additional GA configuration and time. If events appear in Realtime but not in other reports after sufficient time, review your GA4 reporting configuration and consult Google Analytics support as needed.

Event Parameters Are Missing or Only Show for Some Events

GA4 may not surface all parameters for all events in the UI, especially for low-volume events. This does not necessarily mean parameters were not sent — validate via network requests first.

Double-Counted Page Views

If your site already sends GA4 page views (common with gtag.js or GTM), set eventParameters.send_page_view: false to reduce the risk of duplicate page_view tracking.

Conflicts When Multiple Systems Use the Same Measurement ID

Avoid configuring multiple collectors (for example, GTM + a separate gtag + Piano GA4) with the same measurementId unless you understand the implications. Duplicate or conflicting configurations can produce unpredictable outcomes, including inconsistent parameter naming.

If you must run multiple implementations, consider using distinct measurement IDs or streams to reduce collisions. Note that this can complicate session-level joining across data sources, although GA4 can report across multiple streams.

Removing the Piano GA Integration

If you remove tp.setGA4Config(...) from your Composer integration script (or remove the UA ID from Business settings), Piano will stop sending those events to Google Analytics. This does not affect reporting inside Piano products — Piano maintains its own data and reporting independently.

Last updated: June 22, 2026