Implement Piano Analytics With Google Tag Manager Server-Side

The new Piano Analytics data collection SDK and the server-side component of Google Tag Manager are a fantastic duo. Sort of like Stockton and Malone.

Why? Combining the flexibility and the beautifully designed data schema of the PA SDKs with the brilliant usability and power of GTM, you can run the perfect pick and roll, i.e. configure a robust server-side tagging solution for your Piano Analytics implementation in little time. This article will guide you through all the steps and resources you need to move from a standard client-to-vendor implementation of PA to a client-to-server-to-vendor implementation with GTM server-side in the middle. The long list of things to be gained from an implementation like this include increased control over the data stream, data accuracy, first party server-side cookies, as well as the possibility to repurpose and send data collected by the PA SDKs to other endpoints.

Content
Step 1: Sending data via Piano Analytics SDK
Step 2: Receiving data server-side via Custom Event Parser template
Step 3: Sending data via Piano Analytics GTMSS Tag template
Additional tips

Step 1: Sending data

Your standard SDK-based client-side PA implementation can stay in place — full code for an event example below. The only thing that needs to be changed is the collection domain on line 9 of the configuration. This should point to your GTM server-side container. Side note: You can also use the onBeforeBuild or onBeforeSend methods to change the configuration for a single event only. This will allow you to manage multiple collection endpoints on one page, in case you want to test server-side tag management alongside your current implementation and run them in parallel.

Step 2: Receiving the data in GTM server-side

A GTMSS client claims the request and returns a response. It also handles and structures the incoming event data before passing it on to the GTMSS container.

Instead of writing your own code, you can use my official Custom Event Parser template, which is available on Github. It handles any GET or POST request, extracts information from query string, headers, IP, body, and cookies, and returns the data to the server container as an event object. Since it is vendor-agnostic, it works well with the hits sent from the PA SDKs.

Once you have configured the Custom Event Parser to claim and handle the request (the default request path is /event but can be customized using the pa.setConfigurations method), it will return a neatly structured event object to your GTM server-side container:

Event object returned to the GTMSS container by the Custom Event Parser client

Step 3: Sending the data from GTM server-side to Piano Analytics

First, configure a custom trigger that fires whenever the Custom Event Parser client has claimed a request. Then, you can use that trigger to run a GTMSS tag, which will use the event data and eventually send it to the PA collection endpoint.

For quick plug and play, I have written this tag template , which you can import to your server-side container.

However, it likely makes sense for you to design and write your custom code for the tag. That is because during this step, you can make use of the additional control you gain by employing server-side tagging. You have full control over the data that eventually gets sent to Piano Analytics. You can pick apart and modify the event object, request parameters, and headers according to your preferences.

Start from the template code below and flesh it out from there:

Et voilà: Your event is now rerouted via server-side tag management and will be available as a fully processed data point in all Piano Analytics interfaces and APIs within 2 minutes.

Additional tips

Debugging

The client-to-server-to-vendor configuration adds an extra layer to the data journey, so debugging becomes a tad more important. You can use a combination of browser dev tools, GTM preview modes, and PA data quality tools to monitor and debug the whole data journey:

1. Browser dev tools or PA Tag Inspector for seeing outgoing requests in the browser
2. GTMSS preview mode for making sure that client, trigger, and tag are well constructed server-side
3. PA Stream Inspector to monitor all incoming raw requests across platforms
4. PA Data Management Rules to modify each parameter of the data stream during pre-processing and map the request content to your data model properties (optional)
5. See the fully processed event in all reports, interfaces, and APIs within <2 minutes

Viewing the raw incoming request from GTMSS in Piano Analytics Stream Inspector

Visitor identification and cookie handling

When it comes to visitor identification and cookie handling, you have multiple options:

1. Default
The PA SDK drops and manages the client-side first party cookie pa_vid . Its value is sent in the idclient query string parameter. In the end-to-end example above, this value is persisted and eventually forwarded on to PA.

2. Default + server-side cookie rewrite
If your GTM server-side container is configured in a first party context, you have the option of picking up the value of pa_vid and rewriting this cookie as a server-side first party cookie in the response. Simo Ahava released a neat template for this. This allows you to customize cookie attributes, use HttpOnly, and yield longer lifetime in some browser environments.

3. Custom
If you prefer to handle visitor identification independent of the PA SDK, you can either override the idclient paramater client-side via pa.setVisitorId('97c7db4e-4514-4b8e-b693-bd6b57043cc1'); — or you can override the idclient parameter server-side in the GTMSS tag by dissecting the fullQueryString variable and replacing the value of the idclient parameter with an identifier of your choice. The POST request URL in the GTMSS tag is structured like this and you have full control over the idclient value you would like to use:

https://collectDomain.com/event?s=123456&idclient=78c85c7e-d345-41e1-882f-ff4b908113e7

You could even use a custom first party cookie. For such a case, you can instruct the Custom Event Parser client to parse a cookie that is sent in the cookie header of the GET request if the GTMSS container is configured in a first party context. That way, the cookie value will be available in the event object and can be used in the GTMSS tag to override the default idclient .

Custom Event Parser: Parsing a custom cookie from the request to the event data object

— If you have questions, clever suggestions, or if you’re simply up for talking analytics: Feel free to reach out. —