Skip to main content

Marketing campaigns


Automatic campaign links tracking only works with JS SDK.

If you need to track marketing campaign on mobile, you will need to push yourself dedicated properties (beginning with src_). (see mobile marketing campaigns section).

The content of the campaign parameters must be communicated in the destination URL according to the format at_medium=email&at_campaign=new_offer where at_medium is the source label and at_campaign is the campaign label. These parameters are both mandatory for the campaign to be taken into account in your analyses.


The legacy "xtor" format is not recognized by Piano Analytics SDKs. Please use flexible and powerful at_ instead.

Add campaign parameters to the links pointing to your site:

If the link points to the root of the site or a directory:

If the link points to a file with no variable transmitted:

If the link leads to a file with a transmitted variable:


The character ? (or &, depending on the position of the variable) can be replaced by the character #.

Campaign format

URL ParameterDescriptionDetailFormat / Example
at_medium (mandatory)Campaign mediumat_medium=mymediumvalue
at_campaign (mandatory)Name of the campaignat_campaign=mycampaign
at_*Customized properties of your campaignAny querystring parameter starting with at_ will be considered a campaign parameter, and will be translated into a src_ property. You may need to create this src_* in your data model.at_creation=myvalue

Full example

This will result in the following properties:

  • src_medium : mymedium
  • src_campaign : mycampaign
  • src_myproperty : myvalue
  • src_myotherproperty : myothervalue

You can also associate standard data model properties to your campaigns:


Email opening measurement

In order to track email opening with Piano Analytics tagging, it is mandatory to build raw event, embedded in emails inside an <img> tag.

Event name: email.display.offsite


// Raw event
https://<collection-domain>/event?s=<site-id>&events=[{"name":"email.display.offsite","data":{"src_medium":"email","src_campaign":"email campaign"}}]

// Embedded
<img src="https://<collection-domain>/event?s=<site-id>&events=%5B%7B%22name%22%3A%22email.display.offsite%22%2C%22data%22%3A%7B%22src_medium%22%3A%22email%22%2C%22src_campaign%22%3A%22email%20campaign%22%7D%7D%5D">

Force visit marketing source

It is possible to force the marketing source of a visit even if we’ve already retrieved another one on past events. For this, you have to set the src_force property (boolean) to true:

pa.sendEvent('page.display', {
'page': 'page name',
'page_chapter1': 'level 1',
'page_chapter2': 'level 2',
'page_chapter3': 'level 3',
'src_medium': 'email',
'src_campaign': 'launching',
'src_force': true

If several sources are forced during a visit, the last one filled in will be the one kept.

The forced source is taken into account from the next day. The real-time functionalities (Data Query granular exports, or Data Flow) are still based on the classic source detection.

UTM management


Automatic UTM links tracking only works with JS SDK.

If you already use Google UTMs and you want to collect them into Piano Analytics, we offer you two options:

Collect UTM as properties

You can collect UTM parameters as Piano analytics properties.

To do so, please use the enableUTMTracking configuration (true by default).

Collect UTM as sources

You can collect UTM parameters as marketing campaigns (sources).

To do so, please setup the campaignPrefix configuration.

For example, if you want to collect both at_ and utm_, giving the priority to the first one, you can use:

pa.setConfiguration('campaignPrefix', ['at_', 'utm_']);

In that case, if no at_ parameters are present, we will process the utm_ ones.

If you want to use UTM, some properties need to be declared. They are not part of the native Piano Analytics data model :

UTMPiano Analytics native propertiesNeed to be declared?
utm_source-✅ (src_source)
utm_term-✅ (src_term)
utm_content-✅ (src_content)
utm_custom (example)-✅ (src_custom)

To do so, you can consult the dedicated documentation or directly create properties in your data management interface.

Mobile marketing campaigns

On mobile, the marketing campaign properties need to be pushed in the tag.


Measure a marketing campaign source on a page.display.

  pa.sendEvent(new Event("page.display", new HashMap<String, Object>() {{
put("page", "Page name");
put("src_medium", "email");
put("src_campaign", "launching");
put("src_creation", "promotion");
put("src_myCustomProperty", "myCustomValue");

For XTOR migration please use the xtor to at_ translation available in the AS2 documentation. You can then use the translated campaign and change the at_ parameters to src_ as showcased above.