Campaign attribution enrichment

This enrichment can be used to link events to marketing campaigns, using the query string parameters.

When using online marketing campaigns to drive traffic to a website, it's often possible to find information in the query string parameters to identify the particular campaign, medium, and more.

A link for an online advertisement that brings users back to the site might look like:

markup

https://www.acme.com/spring_offer_product?utm_source=influencer&utm_medium=blog&utm_campaign=spring_offer

The enrichment can extract values from the query string parameters, resulting in the following fields being added to the enriched event:

field	value
mkt_source	influencer
mkt_medium	blog
mkt_campaign	spring_offer

The configuration of the enrichment defines which parameters in the URL (e.g. utm_source) map to which fields in the event (e.g. mkt_source).

Configuration

The enrichment takes one parameter, fields, which maps event marketing fields to URL query string parameter names. It must contain these keys:

Key	Required	Populates	Description
mktMedium	✅	mkt_medium	Array of URL query string parameter names. Use [] if you don't need it.
mktSource	✅	mkt_source	As above.
mktTerm	✅	mkt_term	As above.
mktContent	✅	mkt_content	As above.
mktCampaign	✅	mkt_campaign	As above.
mktClickId	❌	mkt_clickid and mkt_network	Object mapping click parameter names to network names. See below.

All five required keys must be present, even if you only want to extract some of them. Provide an empty array for any you don't need.

Console

Configure the parameters in the Console enrichment editor. For example:

json

{
  "fields": {
    "mktMedium": ["utm_medium"],
    "mktSource": ["utm_source"],
    "mktTerm": ["utm_term"],
    "mktContent": ["utm_content"],
    "mktCampaign": ["utm_campaign"],
    "mktClickId": {
      "gbraid": "Google"
    }
  }
}

Self-Hosted

For Self-Hosted, provide a complete JSON. For example:

json

{
  "schema": "iglu:com.snowplowanalytics.snowplow/campaign_attribution/jsonschema/1-0-1",
  "data": {
    "name": "campaign_attribution",
    "vendor": "com.snowplowanalytics.snowplow",
    "enabled": true,
    "parameters": {
      "fields": {
        "mktMedium": ["utm_medium"],
        "mktSource": ["utm_source"],
        "mktTerm": ["utm_term"],
        "mktContent": ["utm_content"],
        "mktCampaign": ["utm_campaign"],
        "mktClickId": {
          "gbraid": "Google"
        }
      }
    }
  }
}

Here is what the above example does:

• take the value of utm_medium=... in the URL and place it into the mkt_medium field
• same for utm_source and mkt_source, and so on
• if gbraid=... is in the URL, take its value and place it into the mkt_clickid field, also setting mkt_network to Google

Testing with Micro

Unsure if your enrichment configuration is correct or works as expected? You can easily test it using Snowplow Micro, either through Console or on your machine.

Supporting multiple parameters

What if some of your links use utm_campaign=... and some use legacy_campaign=...? You can configure more than one parameter name in the array, like so:

json

    "parameters":{
      "fields":{
        "mktCampaign":[
          "utm_campaign",
          "legacy_campaign"
        ]
      }
    }

The same applies to the other configuration options mktMedium, mktSource, mktTerm and mktContent.

If the query string includes multiple acceptable parameters (e.g. both utm_campaign and legacy_campaign), the first one listed in the configuration will be used, not the first one present in the query string.

Results:

Query string	Value of mkt_campaign
utm_campaign=new	new
legacy_campaign=old	old
utm_campaign=new&legacy_campaign=old	new
legacy_campaign=old&utm_campaign=new	new

Click and network attribution

You can define which URL parameters are used to populate the mkt_clickid field. For each parameter, the same configuration setting also defines what network — the mkt_network field — it corresponds to.

The default mappings are gclid for Google, msclkid for Microsoft, and the legacy dclid for DoubleClick.

tip

You can configure any parameter names or network names, including your custom ones.

This example shows how to define your own click attribution settings, using mktClickId:

• Add support for wbraid and gbraid parameters, which will be mapped to Google as the corresponding mkt_network
• Override the msclkid parameter, so that it maps to NotMicrosoft as the marketing network instead of the default Microsoft
• Add a custom xyzid parameter that maps to the XYZ network
• The default mappings for gclid and dclid remain unaffected

json

    "parameters": {
      "fields": {
        ...
        "mktClickId": {
          "wbraid": "Google",
          "gbraid": "Google",
          "msclkid": "NotMicrosoft",
          "xyzid": "XYZ"
        }
        ...
      }
    }

Use only one click id parameter per URL. If you add multiple to the same URL, e.g. both wbraid and gbraid, one of them will be picked arbitrarily.

Results:

Query string	Value of mkt_clickid	Value of mkt_network
wbraid=abc	abc	Google
msclkid=abc	abc	NotMicrosoft
xyzid=abc	abc	XYZ
wbraid=abc&gbraid=def	abc or def ⚠️	Google

Output

This enrichment populates the marketing atomic event fields: mkt_medium, mkt_source, mkt_term, mkt_content, mkt_campaign, mkt_clickid, and mkt_network.

If you don't enable the enrichment, those fields will be empty.