Piano Analytics tag

The Piano Analytics tag for GTM server-side allows you to send events from your server container directly to Piano Analytics. This tag supports Piano Analytics and GA4 schemas, automatically mapping event names and formatting parameters. Works best in tandem with the Piano Analytics Client by Stape.

Benefits of using the Piano Analytics tag

• More accurate data: by moving tracking server-side, you avoid disruptions from ad blockers and browser limitations. This ensures more complete event collection and clearer insights into user activity.
• Faster site speeds: removing tracking scripts from the client side lightens the browser workload, reduces load times, and smoothes the user experience.
• Stronger privacy compliance: with data sent directly from server to Piano Analytics, you gain better control over what information is captured and how it’s handled. This approach supports compliance with privacy laws like GDPR and HIPAA.

Requirements for setting up the Piano Analytics tag

Please ensure that you already have events flowing from the web/app environments to the server and a server container in GTM, as well as a configured server container and custom domain in Stape. 

The Piano Analytics for GTM server-side tag supports events from:

• Piano SDKs (iOS and Android.)
• Piano Analytics web events implemented without using Google Tag Manager web (i.e., using the Javascript SDK directly.)
• Piano Analytics web events implemented using Google Tag Manager web.
• GA4 web/app events.
• Events that adhere to the Common Event Data schema.

Please follow these guides if you don’t have any of those:

• How to implement Piano Analytics SDKs on web and app (recommended if using Piano Analytics events to send data to the server).
• How to create a web container in Google Tag Manager (optional, if not using Piano Analytics).
• How to create a server container in Google Tag Manager
• How to create a server container in Stape
• How to add a custom domain in Stape

How to set up the Piano Analytics tag

1. Configure sending data to the server GTM container. The two most popular options for sending data to sGTM are Google Analytics 4 and Data Tag/Data Client. Here is a step-by-step guide on sending data to sGTM.

Alternatively, you can leverage your existing Piano Analytics implementation (web or app) to send events to the server GTM container. This is the most powerful option to unlock the full capabilities of Piano Analytics. To do this, set the collectDomain field to the GTM Server Container URL within your tracker configurations. For more information, refer to: Piano Analytics JavaScript SDK, Piano Analytics Android SDK, Piano Analytics iOS SDK.

2. Add the Piano Analytics tag template in the server GTM container by importing it from the Template gallery:

• Search for the Piano Analytics tag by Stape in the Google Tag Manager Tag Template gallery.
• Click Add to workspace.

3. Create the Piano Analytics tag:

• Go to the Tags menu → click New.

• Click Tag Configuration → select Piano Analytics.

4. Configure the Piano Analytics tag:

• You have two options for configuring the Event Name Setup Method in the Piano Analytics tag: 
  • Override - this is the preferred way, even though it’s more complex. It lets you configure events manually, granting you full control over the events’ payload.
  • Inherit from client - in this case, the tag will attempt to match your GA4/Data event’s payload to Piano Analytics standard events automatically. If the tag can’t match the GA event to the standard Piano event, it will be sent as a custom event. Here is the supported event name mapping.

• Collection Domain - set the Collection Domain (e.g., xxxx.pa-cd.com). To find it, navigate to the Piano Analytics Dashboard and select Tagging → Collection Domains. See the Piano Analytics official guide to learn more.
• Site ID (optional) - go to the Piano Analytics Dashboard and use the number in the ID column for the desired website. Will be inherited from the Event Data parameter x-pa-site-id if not set (only when using Piano Analytics events as the incoming events to the server).
• Visitor ID (optional) - enter a unique identifier of the visitor (must be a 16-character string or a UUID). If not set, it will be inherited from the Event Data parameters client_id or x-pa-idclient.
• Redact Visitor IP Address (optional) - removes the visitor's IP address from the event data. Use with caution, enabling this may negatively impact reporting accuracy and data quality.
• Use Optimistic Scenario (optional) - the tag will call gtmOnSuccess() without waiting for a response from the API. This will speed up sGTM response time, but your tag will always return the fired successfully status even if it’s not.

• Event Parameters - you can add, edit, or exclude event parameters. By default, the tag does not retrieve any value for the cart_id property, which is required for most Piano Analytics ecommerce events. It is strongly recommended to configure mapping for this property. If not set explicitly, the tag will fall back to transaction_id, which is not recommended.
• Logs Settings - choose whether you wish to log all events to the browser console during preview/debug or always.
• BigQuery Logs Settings - choose if you want to log event payloads, request details, and responses to a specified BigQuery table.
• Advanced Settings (Additional Tag Metadata) - specify additional tag metadata to be included in the event data when a tag is fired.

5. Add the Trigger for the tag, give it a descriptive name, and click Save.

How to test and troubleshoot the Piano Analytics tag setup

You can test the configurations in Google Tag Manager. Click on Preview, trigger the event, and check whether the tag has fired.

Find out more about debugging and monitoring server-side tracking configuration in our guide.