If your site uses the Piano Analytics SDK, please refer to the documentation below: UTM Management.
The SDK allows you to take UTMs into account by declaring campaign prefixes and creating custom properties without adding processing rules.
Property scopes
Definition:
The scope of a property stands for the definition of the value of the property on events of a visit.
There are 2 types of property scopes : event scope and visit scope.
Event scope:
Definition:
The value of the property is only associated to the event that collected the property.
We collect the value of the property for the event that had it in the hit, and associate it to the event in the data.
Example:
The Event URL property (event_url) is fed by the URL that triggered the event.
If during his visit, the visitor changed URL, then the visit will have different values for this property.
Visit Scope:
Definition:
The value of the property is associated to all events listed in the visit.
The value is stored on the first page.display of the visit.
Example:
The Source property (src) is fed by the value associated to a first page load, all following events in the visit will be associated to this first value.
Properties dedicated to UTMs
Setup:
You can use event scope properties to measure all campaigns encountered during the visit.
To do so, please go to Data Management > Properties, check if the visibility filter includes hidden properties, then check the event scope properties' pages listed below to untick the "Hide property" case, and finally click on Save and Deploy.
List of available properties:
- utm_campaign
- utm_content
- utm_medium
- utm_source
- utm_term
Properties' processing:
Each property is fed by the following rule:
- Verification if a value is collected from the utm_xxx tag parameter
- If YES then the property is fed by the value collected
- If NO then we check the content of a utm_xxx in the Query String of the event URL
- If YES the property is fed by the value of the Query String
- If NO the property is empty
Source properties
Use:
You can choose to include your UTMs in source properties that have a visit scope.
Example:
In the case of a visit that has a UTM campaign as its source, by using a source property, you apply the source information to every event in the visit. So if the visit sends a first event with the campaign, followed by a second event without the campaign, a campaign source will be obtained for the second event just like the first.
Setup:
We recommend that you rely on the following properties with their respective property keys:
| Tag parameter | Property | Actions |
| utm_campaign | src_campaign | Edit the property rule |
| utm_content | src_utm_content | Create the property and edit its rule |
| utm_medium | src_medium | Edit the property rule |
| utm_source | src_campaign_group | Edit the property rule |
| utm_term | src_utm_term | Create the property and edit its rule |
For each property you will have to define the rule following this principle ↓
Example for the "src_medium" property in which we want to integrate the utm_medium:
Condition block 1 / Check the native tag parameter
IF src_medium (tag parameter) is not empty
THEN takes value of src_medium (tag parameter)
Condition block 2 / Check the utm tag parameter
ELSE IF utm_medium (tag parameter) is not empty
THEN takes value of utm_medium (tag parameter)
Condition block 3 / Check the Query String of the Event URL
ELSE IF utm_medium (Event_URL > QueryString) is not empty
THEN takes value of utm_medium (Event_URL > QueryString)
Condition block 4 / Default case
ELSE EMPTY