Tracking actions and connecting them with mailings

A mailer, member database, and so much more, for digital activism.

Tracking actions and connecting them with mailings

Quick Guide - Settings

These settings may change over time, but currently, to get UTM tracking and linked to mailings consistently, you probably want to start with these:

UTM Parameters

In general, UTM parameters are the most common tactic for identity users tracking actions and where action takers came from. For this guide, we’ll be focused on mailings as a source, but the principles apply equally well to other sources (such as blog posts, social media etc.). UTM parameters generally refer to a set of 5 URL parameters: utm_source, utm_medium, utm_campaign, utm_term and utm_content. The precise meanings of each parameter varies - they originate within marketing applications, but for identity we mostly use just utm_source, utm_medium and utm_campaign like so:

Language

Actions are taken in the context of a language (to be explicit, this means a human-to-human language). The language in which an action took place is recorded along with action name, type, etc. Languages in Identity are defined by and restricted to those that are assigned a 2-letter ISO 639-1 language code. These codes are contained within a static file in /lib/assets obtained from this website.

Languages are also stored in Campaign records, as a string array of ISO codes. When an action is recorded, Identity will attempt to update the associated Campaign record with the language included with the action. If the language code already exists in the Campaign object, the Campaign languages array remains unchanged.

Linking things together in identity

(Currently) In it’s default configuration, Identity will append these three utm parameters with default values to all links in mailings you send. If a link already has a UTM parameter set, that will be used. So, for example, a link to http://the-open.net/ might become http://the-open.net/?utm_source=the-open&utm_medium=email&utm_campaig=blast2020-03-25.

Later, if an action is taken (petition signature, donation etc.), and that app (e.g., CSL or speakout) both records UTM params, and passes them on to identity, you will have a member action record linked to a “source” record with attributes source, medium and campaign.

Separately, when a mailing sends, it will save a source linked to that mailing, with the default UTM params for that mailing. Action rates for mailings are calculated based on the number of actions linked to a source linked to that mailing.

Donation rates are calculated based on the number (and summed amount) of (one-off) donations linked to actions linked to sources linked to that mailing. It’s the same for regular donations.

Mailing Variations

Since our default set of UTM params does not currently include any information about mailing variations, we use a different tactic for tracking actions connected with specific variations. Essentially, for actions connected with a mailing, we count them as connecting with a given variation based on the member having received that variation. This gives rise to some data being potentially ignored - it is possible (indeed, fairly common in fact) for actions to come in with the UTM params of a given mailing, but attach to members who never recieved that mailing - these cannot be connected with any variation.

In identity, we display a count of these actions labelled “Activity from members who did not receive this mailing”. This can be explained a variety of ways:

My action rates look wrong

First, have you checked your settings? A little tweak might improve things. Next, it’s time to track your data, there may be a problem at any of the steps along the way. You can just start browsing through a rails or database console, or you can make a few test actions so you know exactly what results should appear.

  1. When you send a mailing with a link to an action, does the link include utm_source, utm_medium and utm_campaign? Do they look as you expect?
    1. You might find utm_campaign has the format "blast#{mailing.updated_at.strftime('%Y-%m-%d')}", this can introduce clashes with other mailings sent on the same day. It’s recommended you set TAG_MAILING_LINKS_BY_MAILING_ID to true.
  2. When you send a mailing, can you find a source record with your mailing’s ID? Do the attributes (source,medium and campaign) match what you found in the previous step?
  3. In your application collecting actions (e.g., speakout or CSL), can you see the source information accurately recorded?
    1. Note for CSL - although CSL records both UTM params and source and bucket, identity only stores source and bucket (converted backward to source and campaign) on events received from CSL. You may need to enable INCLUDE_CSL_TRACKING_PARAMS
  4. Examining member actions saved in identity - do they have sources attached?
    • If not, try to find out how/why data is being lost between your app and identity
    • If sources are saved, but they don’t match the one set by your mailing - have your campaigners been setting their own UTM params? Did these actions definitely come from the mailing?

My donation rates look wrong

First, have you followed the steps for debugging action rates? Donations are linked to mailings via actions, so you need that to be working, and it’s easier to debug for example signatures. OK, now let’s focus on why your donations might not be linked to actions.