Date

Share this post

How to set up Piano Analytics in Google Tag Manager with Aristide Riou

Table of contents

Introduction: Piano through the ages 

Do you know Piano Analytics? No? Really not? 

Perhaps you've heard of AT Internet, then? Or even Xiti, if you're feeling particularly nostalgic? 

Well, to put it simply, Piano Analytics is to AT Internet what Charizard is to Charmander. What the 205 GTI is to the plain old 205. Perhaps what GA4 should have been to Universal Analytics in a parallel universe, but that's another debate. 

This article was written without AI (well, almost). No em dashes were harmed in the writing of this article, and the dubious puns, repetitions and wildly overlong sentences were produced by my own chunky fingers on a device known as a Logitech keyboard. 
That said, I'm not a caveman either. I do use whichever LLM happens to be within reach (Codex at the moment) to: 

  • Corect teh speling misstakes 

  • Smooth out awkward phrasing 

  • Spot repetitions, something I'm rather fond of to begin with 

  • Generate article summaries / tables of contents 

  • Translate into English 

Piano Analytics is comprehensive, simple yet flexible, minimalist and effective. Piano does analytics and plenty of other things too. Use Piano and you'll instantly sparkle at dinner parties. 

Which works out rather well, because today we're NOT going to talk about that AT ALL (dinner parties). Rather than choosing the living room colour, we're going to talk about fitting the framework behind the plasterboard. We're going to talk about setting up Piano on the web with the one, the only, the mighty and indestructible, ladies and gentlemen, Google Tag Manager. 

Because yes, there is some documentation (in French) covering the subject, but it has two flaws: 

  • It assumes you know Piano and how its data model works, which isn't that complicated but does have quite a few subtleties. 

  • It is desperately short on JOKES. 

A quick stop at the disclaimer desk: this article is sponsored by Piano. Yes, here I am in another collaboration, this time to talk about tags, variables and consent. There are more glamorous influencer careers, but we all have our ambitions. As with Stape, it's a subject that interests me anyway: setting up Piano Analytics with GTM deserves a proper look under the bonnet, including the subtleties that make you want to shut your laptop and go off to breed wildebeest in Lozère. Anyway, thanks to Piano for supporting this article, and now let's set up some tags. 

Let's start with a simple premise: Piano has followed the approach used pretty much everywhere in the market, except Matomo and therefore Piwik Pro, with an event-based model where everything we collect is an event, including a page view, and consent logic that's actually not so far from Google's Consent Mode, which we so often love to hate (or hate to love, depending on the day). 

We're sensible people, so we're going to use the very good official Piano Analytics template for GTM, which actually splits into two, like Edward Norton and Brad Pitt in Fight Club: 

  • A tag template, called "Piano Analytics - Tagging". 

  • A variable template, which, to everyone's surprise, isn't called "Martine Goes to the Beach", but "Piano Analytics - Configuration" (astonishing, isn't it?). 

GTM template editor: overview of the Piano Analytics - Tagging template and tag preview.


GTM template editor: Piano Analytics - Configuration template and preview of the Collect domain, Site number and Queue variable name fields.

I'll deal straight away with the classic objection: "blah blah blah, I prefer custom HTML because I'm in control of everything I do". I hear your desire for control and for writing JavaScript as though Georges Pompidou were still president of France, but in practice, what you're mostly in control of is setting fire to your Core Web Vitals and bringing the site down at any moment because you forgot a semicolon around property 241 out of 654. Still, I'm not the GTM Police*, own it, be yourself, live your life. 

*Fortunately, too. I know a few people, AND I KNOW WHERE YOU LIVE, who would have been serving life sentences long ago. 

Another disclaimer while we're here: this article only covers Piano Analytics, not the other tools in the suite, even though the consent logic we'll discuss later is managed in much the same way. 

If you know Piano, this might interest you. But even if you don't use it, it can also give you a comparison with GA, since there are plenty of similarities but also some interesting differences, and I'll try to explain things where necessary. 

And because I'm a great lover of generosity, but also of risk, throughout this article I'll be implementing Piano Analytics live, yes, LIVE, on L'Atelier café, my demo e-commerce site that I abuse whenever I have tests to run, voted Website Of The Year Two Thousand And Twenty-Seven in the category "Sites vibe coded half-arsedly: coffee theme" (fierce competition). 

The "Piano Analytics - Configuration" variable 

If you haven't already, start by importing the variable template, which we'll need to fill in with love and care, and which looks like this: 

Piano Analytics - Configuration variable in GTM: collection domain, site number, SDK and consent settings.
  • If you're new to Piano, the "Collect domain" setting lives in the Data Collection Portal in the admin interface. This pa-cd will also be your reference point a little later when checking collection:

Piano Data Collection Portal: site number and collection domain.
  • The same goes for "Site number", roughly the equivalent of a GA Stream ID for anyone who's wandered this far without quite knowing what we're talking about. This is, of course, where I recommend, like any sensible person, setting up routing between the domain name and the Piano site ID, to avoid the embarrassing situation where your staging tests generate more traffic than the media agency managed with its brand awareness campaign: objective, number of awarenesses. 

  • The "PA SDK source URL" setting is interesting. You can load the SDK from https://tag.aticdn.net/piano-analytics.js, which is the default option and gives you the latest version, always up to date, but which naturally gets blasted out of the sky by the first ad blocker passing through. This is where you can instead host the library on your own CDN and reference its location (you'll find it here). Bear in mind, though, if you have the audacity and generosity to do this, you'll have to update the tag template (which we'll discuss below) so it can make the appropriate calls, which means losing updates to that template: 

Piano Analytics - Tagging template permissions in GTM: permission to inject scripts from https://cdn.myawesomewebsite.com/*.
  • With "Default consent mode", we get into the complex but interesting subject of Piano consent. I'll return to it in much more detail later, but for this article, I'm using "essential", provided the configuration meets the criteria for consent-exempt audience measurement. Unfortunately, ticking a box in GTM doesn't do all the work. Essential mode assumes the exemption applies; it doesn't create it. Source (in French): https://docs.piano.io/fr/analytics/consent-management 

  • "Queue variable name" sets the name used to namespace Piano, and can be useful if you're feeling adventurous and have Matomo (or another tool that's completely lost the plot, such as Plouf Analytics Quality) sharing that global variable name. Yes, as though no other THREE-LETTER combination existed in the Universe. ANYWAY, generally stick with "_paq", unless you have Matomo. 

  • Back to consent with "Consent items", and we've reached the point where I have to take a detour, because this is far from obvious. 

Grab your finest paracetamol, take a look at the documentation, and above all, look at this lovely diagram: 

Diagram of mandatory, essential and optional priorities and opt-out, essential and opt-in modes.

 You can print it, memorise it, or do what I did and get it tattooed across your chest, Michael Schofield style. What you need to understand here is that you must define the required consent level for your events and your properties (your native and custom dimensions). 

To keep things simple, there are two things to distinguish: the consent mode, which reflects the user's situation, and the priority of each event or property, which determines the modes in which it can be sent. Yes, Piano uses the word "essential" on both sides, just to check you're paying attention. 

On the user side, we have the three modes discussed here: 

  • opt-out: the main course only menu, with very restricted collection. 

  • essential: the starter / main course menu, with collection limited to what is necessary for consent-exempt audience measurement, provided the applicable requirements are met. 

  • opt-in: starter, main course, dessert, drinks, coffee. Consent lets us enrich collection for the purposes accepted. We can buy a round for the whole table, but we stay within the scope of what the user has agreed to (non-itemised receipt, please). 

On the event and property side, we assign the following priorities:

  • mandatory: allowed in all three modes, including opt-out. 

  • essential: allowed in essential and opt-in, but not opt-out. 

  • optional: allowed only in opt-in. 

Priority is therefore a technical setting: classifying a property as mandatory doesn't make it legally essential or give you a free pass to send it. 

Sources

  • https://developers.piano.io/analytics/data-collection/how-to-send-events/consent/ 

  • https://docs.piano.io/en/compliance/consent-management 

Generally speaking, Piano's SDK is configured out of the box to send or withhold native properties depending on the consent level (keep the documentation handy), but you can absolutely customise this.

In practice, if you decide a "user_segment" property has "essential" priority, it will only be sent if you have at least "main course and drink" consent. Well, essential.

So here, in our variable, we're defining the default behaviour, which we can later adjust as the user's consent changes. I take a fairly liberal approach here and set all my events and properties to "Mandatory", meaning all properties and all events are sent in every case:


Consent items: all properties and events configured with Mandatory priority.

Careful, that doesn't mean I send everything without consent. It means I manage the rule myself, deliberately obfuscating certain values when I don't have consent, as we'll see a little later. Of course, this needs handling case by case: it only works if most of your properties don't require the opt-in level. 

For example, without opt-in, my GTM variable builds the properties without user_id, and the 'Set a user' tag doesn't fire. And instead of a URL such as /mon-compte?customer_id=12345, I send a generic page name, "My account", while also preventing the raw URL from being sent in other properties. With consent, I can add the user ID defined in my tracking plan.

As a third layer, you can also flag a property as "Contains personal data" ("Contient de la donnée à caractère personnel") in the admin interface, to clean up properties according to the consent mode after collection (it's explained very well here):

Contains personal data option enabled in the French Piano interface.

I'll quote the documentation here, which sums it up quite well: 

"Priority level refers to the consent level required for the data to be sent/stored. You can imagine it as follow: Any item with a higher priority will also be sent with lower priority modes. For example, an item with a "mandatory" priority will be included de facto in "essential" and "opt-in" modes." 

Does that seem cryptic? That's normal. We'll come back to setting consent a little further down. You'll see the light in fewer than 40 lines, I promise. 

Let's finish this section on the configuration variable with "Other configurations", which thoroughly deserves your attention (the official documentation is here). Generally, the default settings will probably do the job, but you might want to change a few: 

  • campaignPrefix: if you use GA-style utm_xxxx rather than at_xxx, that's absolutely fine, but you need to specify it by returning this: 

function(){   return ['at_', 'utm_'] }  

  • addEventURL: set this to "true" if you want to collect raw URLs (always useful, but potentially sensitive if personal data such as a user ID can appear in URLs). 

  • The variable also includes a "Consent Products" section, where you choose WHICH Piano products the change applies to. If we're only talking about Piano Analytics, you can leave it empty. Otherwise, add a row for each product in the Piano suite. 

The more tags, the merrier 

We're done with the variable, now it's time for tags. Yes, tags, plural, because the Piano tag has several "Actions". Let me reassure you straight away: we haven't gone back to 2011, with separate page view tags, event tags, goal number 24, and variable flushing when atmospheric pressure exceeds 1,200 hectopascals. Well, a little bit. We'll look at this in detail, from simplest to most complicated. But first, I'd like you to do a little introspection: breathe, and think about what each of these items might do.

Choose action menu in the Piano Analytics tag in GTM: sending events, user, consent, eCommerce bridge, properties and visitor ID.

 Done? Had a think? Right, let me explain: 

Send an event 

This is basically the simplest one, and even if you don't use Piano, you already know it inside out. An event name, keys, values. Like GA. Like Amplitude. Obviously, you're seasoned professionals, so you know perfectly well that you need to declare your events beforehand (unlike GA) and your properties (like GA, but only in the interface), especially for custom events / properties, and you also know that this data model needs to be absolutely clear so Piano's AI tools have what they need to get on with their work in peace. 

Send an event action: click.navigation event and click_label property populated by the DLV - itemName variable.

An extremely important aside: by default, if you don't explicitly set the "page" property in your page.display tag, the page name shown in your reports will be that page's <title>: 

Piano report: Accueil and Nos Produits page names from L’Atelier Café, with one visitor for each page.

So remember to set this parameter explicitly (whether you want the URL with or without the domain, with or without parameters… that's down to your use case). 

Send multiple events 

The logic is much the same here, I won't draw you a picture. We'll batch several events into one send to spare the browser some work. There's one subtlety, though: you can't have a set of properties shared by both events, you need a dedicated variable. 

Either go old school with custom JS that returns a big, hearty helping of JSON, or use a "Google tag: Event Settings" variable, whose job is essentially to do this. Yes, I know using a Google tag in Piano might seem a bit bold, but once you've accepted that, ultimately, this variable just returns JSON (personally, that took me 17 psychoanalysis sessions, none covered by my outrageously expensive health insurance), it's a good no-code alternative. And although I haven't dug into it, there are also various templates out there on the World Wide Web that do this sort of thing, if you'd rather not depend on a native template that's inherently a bit of a black box (which I entirely respect). 

eCommerce bridge 

Let's be clear, precise and factual: use this tag if and only if you have a GA-style e-commerce data layer. In that case, this tag will make the coffee for you (and not just on my demo site, even if you sell panini presses or speed-reading courses), using Piano's mapping for both events and properties. I think a screenshot is worth a thousand words. 

eCommerce bridge action: event name from the Event variable and mappings between Google and Piano eCommerce events.

Piano now takes a fairly similar approach to GA for product lists, with a lovely product.display event that itself contains an items_list key.


Chrome DevTools: payload batching ten product.display events in a single Piano request.

That doesn't always do the job, and you may well have:

  • A "non-GA" data layer. 

  • Or, conversely, a mapping you want to customise more specifically, using other Piano events. 

In that case, nothing stops you doing your own thing and mapping it in a more personalised way, with a completely ordinary event tag. In Piano, e-commerce events unlock certain dedicated reports, but aren't as restrictive as GA's ultra-strict event list and item formatting that won't tolerate the slightest typo. So using a "standard" event tag wouldn't really be a handicap with Piano.

You can also do a bit of semi-customisation in this eCommerce bridge, since you can:

  • Change event mapping: if you want add_payment_info to become payment.add rather than the default cart.payment, you can. 

  • Do the same for properties: change Google's item.xxxx to whatever you like. 

Set properties 

This is where we reach a very interesting, but slightly treacherous, subtlety of this template. When you're used to GA, you expect to use a "Gtag event settings" variable, quietly read whenever needed by all the variables that call it, letting you calmly distinguish shared properties from those specific to a single event. 

Except no, that would be too easy, because here you need a tag. That may seem counterintuitive, but there's a reason: in Piano's web SDK, sending properties with an event is distinct from setting persistent properties (in the French original, I struggled to translate the documentation's rather elegant "Add properties to subsequent events"). 

Our "Set Properties" action arrives just in time: it sets properties, lots of properties, or a few properties, that you want to reuse on other events. 

Set properties action: property fields, Persistent option and event scope.

So, unless you have a reason that would seem rather obscure to me, remember to tick "Persistent" (otherwise, I honestly don't really see the point of this action). You get the idea: everything sent afterwards inherits those properties. 

And this is where our story gets complicated, because you're probably wondering when to fire this. Well, I'll tell you, painful as it is: use tag sequencing, before each event tag, for a belt-and-braces approach. Yes, you don't like sequencing (unless you have very odd tastes). Sequencing is complex to debug, hard to maintain, and generally runs counter to GTM's beautifully clear trigger logic. But here, you'll have to live with it. 

One last point about "Set properties": notice the typing logic in the right-hand column. I could talk about this at length, because Piano's typing is relatively flexible, which can produce some sneaky side effects. So, pragmatically, my recommendation is to use strong typing: if a property is a string in your data model, send a string and set the type to "Auto". Full stop. 

Set a user 

The logic here is broadly similar to what we've just seen: this isn't an event as such, but specific properties: 

Set a user action: User ID and User category fields, with Store user data ticked.
  • User ID populates the 'user_id' property ("ID Utilisateur" in the French interface). 

  • User category populates the "Utilisateur - Catégorie" property (user category). 

  • Don't overlook Store user data: it sets a pa_user cookie, reused on subsequent pages. 

Typically, then, we'll also tend to fire this tag before other tags using sequencing. Depending on your site / app logic, there are two ways to do this:

  • If you have a separate login event, sequence this "Set a user" before an event such as identity.login. 

  • If you're loading a page view for a logged-in user, it goes before the page tag, again using sequencing. 

And obviously, only fire this with the appropriate consent (as usual, you know how to read Didomi, Axeptio and friends).

Those of you who spend your evenings poring over Légifrance, France's legal database, and the CNIL's Viadeo feed probably jumped out of your seats (or sent me a registered letter out of muscle memory), thinking that we also need to handle consent withdrawal, which ranks very highly on the 2026 tier list of hot DPOs in your area. 

Unfortunately, there's no action for this in the template. You'll need a brave little pa.deleteUser() in custom HTML. 

And now you might be thinking: aren't we already using sequencing for the properties? Well, yes, in this case you may end up sequencing your sequencing. Sorry about that, but it's largely inherent to how Piano works. 

Consent logic 

[Previously on Might & Metrics]

You'll see, I'll come back to consent a little later, and then everything will become clear. 

Heeey, I'm back! 

If you've gone off for a coffee or any other hot beverage of your choice, feel free to revisit the section about default consent in the variable, because this is where our wonderful consent management adventure continues. 

This "Set Consent mode" tag handles a consent change that differs from the default value set in the variable. In practice, there's a good chance you'll hook up a trigger such as, just picking at random, didomi-consent-changed or axeptio_update. And this is precisely where, under "Consent Mode", you'll create a lovely variable that returns "opt-in", "essential" or "opt-out", depending on what you get from your CMP (via the data layer or a cookie). 

In practice: opt-in when consent has been granted for the relevant purpose; essential for audience measurement whose configuration meets the exemption conditions; opt-out to opt out of tracking according to the choice expressed and the applicable requirements. 

An aside: always remember to map a dedicated event to consent changes (this applies to GA and others too), for example consent.answer, which is in Piano's native data model. It's the sort of event that will save you when something slightly bonkers happens in your CMP configuration, and it can help explain drops in conversion rates. 

Testing means doubting. Except here, it really doesn't. 

I won't go into too much detail here. Broadly, if you want to debug Piano hits, you have two options: 

  • If you're hardcore, use the Network tab in Chrome DevTools and look for anything going to pa-cd.com. The payload is perfectly readable, nothing particularly surprising.  

Chrome DevTools: payload of a product.page_display event sent to the Piano collection domain.
  • Or, if you want the same thing with a pretty interface (although what beats Chrome DevTools for looks? Not much, in my opinion, but for some reason people love Chrome extensions, who am I to judge), the Piano Tag Inspector extension is there for you. 

Piano Tag Inspector: collected properties for a page.display event.

Of course, don't forget the very handy Stream Inspector, available directly in Piano's interface, where you can see hits in real time with the appropriate filters: 

Piano Stream Inspector: list of events received for the L’atelier café site.

And just in case you didn't know, the data is even available directly in reports after barely two minutes. So, sorry not sorry, but you really have no excuse left for sending rubbish data. 

Appendices and assorted thoughts relating to this article 

Here are a few side topics, still somewhat related. But overall, still very much side topics. 

Perhaps you've heard of A/V Insights, Piano's niche but very handy module for collecting data on videos, podcasts and other widgets. It gives you access to dedicated reports in the cleverly named "AV Insights" section of the standard reports: 

Piano AV Insights report: overview of content plays and consumption time.

I'll keep this short. There's no getting around it here: we're going old school with custom HTML, because you need to work with a "myMedia" object that basically does, let's say… things (the documentation is here).

You may also be shocked and disappointed that this article only covers client-side implementation, when, like any good tracking expert, you've already got everything neatly tucked away at Stape or AddingWell. I may devote an article to that in the near or distant future, but essentially: 

  • Yes, it's absolutely possible to send Piano hits S2S. 

  • No, it's not that simple without the Piano SDK on the front end, which does quite a lot of things that take some work to reproduce if you want everything server-side. 

Stay tuned, as they say. We'll talk about all that again very soon. 

Date

Tags

Share this post

Date

Tags

Share this post

関連コンテンツ