Skip to main content

Marketing campaigns

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.

attention

The legacy "xtor" format is not recognized by Piano Analytics SDKs. Please use three-years-old, 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: https://www.site.com/?at_medium=email&at_campaign=new_offer...

If the link points to a file with no variable transmitted: https://www.site.com/index.php?at_medium=email&at_campaign=new_offer...

If the link leads to a file with a transmitted variable: https://www.site.com/index.php?other_variable=2&at_medium=email&at_campaign=new_offer...

note

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:​

https://www.site.com/?at_medium=mymedium&at_campaign=mycampaign&at_myproperty=myvalue&at_myotherproperty=myothervalue

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:

PropertyTypeExample
at_creationstringat_creation=Main
at_variantstringat_variant=Blue
at_formatstringat_format=440x300
at_typestringat_type=Direct

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

Example:

// 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': 'chapter 1',
'page_chapter2': 'chapter 2',
'page_chapter3': 'chapter 3',
'src_medium': 'email',
'src_campaign': 'launching',
'src_force': true
}
);
note

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​

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 exemple, 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_mediumsrc_medium❌
utm_campaignsrc_campaign❌
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.