Marketing campaigns

Link tagging

note

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.

attention

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: 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 Parameter	Description	Detail	Format / Example
at_medium (mandatory)	Campaign medium		at_medium=mymediumvalue
at_campaign (mandatory)	Name of the campaign		at_campaign=mycampaign
at_*	Customized properties of your campaign	Any 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:

Property	Type	Example
at_creation	string	at_creation=Main
at_variant	string	at_variant=Red
at_format	string	at_format=440x300
at_type	string	at_type=Direct
at_campaign_group	string	at_campaign_group=Carlo

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': 'level 1',
  'page_chapter2': 'level 2',
  'page_chapter3': 'level 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

note

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 :

UTM	Piano Analytics native properties	Need to be declared?
utm_source	-	✅ (src_source)
utm_medium	src_medium	❌
utm_campaign	src_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.

Mobile marketing campaigns

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

Example

Measure a marketing campaign source on a page.display.

Android

  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");
  }}));

Apple

  pa.sendEvent(Event("page.display", data: [
    "page": "Page name",
    "src_medium": "email",
    "src_campaign": "launching",
    "src_creation": "promotion",
    "src_myCustomProperty": "myCustomValue",
  ]))

note

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.