UTMs, DataPoints and Recipes

UTMs are made of Datapoints which are filled by Recipes. Now ain’t that easy?

UTMs help us describe which data points we would like to record (eg. local, product, campaign date)  and how we wish to pass them in our UTM fields (utm_source,utm_medium etc.). At first we can decide some basic settings.

UTM standard

UTM-builders Basic Profile comes with the Google Analytics (GA) standard UTM conversion of utm_source, utm_medium, utm_campaign, utm_term and utm_content. These parameters are automatically picked up by GA and can easily be used to analyse traffic in the Google Analytics User Interface. Other services such as Snowplow Analytics offer out of the box support for these parameters. As a result of common usage these five are great placeholders into which to put our desired data points.

With the Enterprise Profile you have full freedom over what url parameters to use. This is useful if you are using other analytics providers such as Adobe Analytics, Piwik or your own In-house solution. For example we could choose to have a parameter for each data point (eg example.com?utm_locale=de&utm_product=shoes…) or we could condense everything into one parameter (eg. example.com?utm_tracking=de_shoes_2017-01-01)


A link UUID is our way of letting you perfectly track your links. Every time a link is built a unique id for that link is made, and this is saved to our database. You can choose to pass this UUID along with the other parameters of your link.

Eg . example.com?utm_source=fb&medium=sp&…&_li=12345566789

This id lets you cleanly pull the data points from our api, and to see additional data like

  • Who created the link
  • When was it created
  • What profile it belongs to

There are two ways in which to add this UUID (include link uuid methods).

  • Appending it to the url
  • Overwriting the other UTMs

Appending simple adds one more element to the url. Overwriting however gives the opportunity to have fully opaque utms. This means that the end user will not see the marketing data points that you wish to measure. Instead only the uuid is visible

Eg. example.com?_li=12356kdjh. The other marketing data can then be retrieved using the utm-builder api.

As a feature of an Enterprise Profile you can also choose the name of the links UUID. For example _li can be changed to cid or even gclid if this enabled your current analytics set up to better consume the link id data.

UTMs and Datapoints

UTM params such as utm_source, and utm_medium are placeholders into which to fill data. In the UTMs section we can choose what datapoint in what order to fill into which of these placeholders. In an Enterprise Profile we can even choose what to name these UTMs and how many to have.

Working with UTMs Conventions (Premium)

  1. NB. Ensure that the UTM convention “Custom UTMs” is enabled if you want to use UTMs other than just GA standard. Other wise other UTMs will be filtered and hidden.


Adding : Above and below the main UTM panel are two plus buttons. Clicking here lets us add new params.

Removing : Underneath each utm params name is a little trash can. A simple click and its gone.

Renaming : The little edit symbol underneath each UTM name will allow you to rename it.

Working with UTMs Conventions

Datapoints are what we call the unique pieces of data that you would like to keep track of and compare in your analysis. For example,

  • Locale of your marketing efforts e.g. ( com, de, fr)
  • The Product you are promoting e.g. (shoes, dresses)

Think long and hard about which datapoints you would like to use.

Good datapoints:

  • Are well defined and named
  • Help answer your business questions
  • Make sense across different marketing efforts (mail, adwords, organic posts)
  • Are prepared to deal with “corner cases” – eg (a ‘city’ datapoint used for adwords might be ‘na’ for organic social posts)
  • Are prepared for scaling
  • Are Not cramped

Notes on Datapoint Format

  • Each datapoint is there in every UTM even if it does not apply for that source or medium or marketing action. This ensures consistency when looking at your data later.
  • Each datapoint is separated from the next by an underscore ( “_” ) for this reason underscore is a forbidden character elsewhere in the UTM builder.
  • “na” is a better option than an empty string ( “” ) if we do not need a datapoint in a certain circumstance. It is easier to see, use and parse later on.

Working with UTMs DataPoints

  • Adding a DataPoint : click the plus to the right side of the UTM panel
  • Moving : Datapoints can be reordered and moved by drag and drop
  • Editing : click the edit Icon
  • Deleting
    • Removing a single datapoint: can be done by dragging it to the left and into the Trash Icon (where the Plus icon normally resides)
    • Removing All of a certain datapoint: can be done by clicking “Remove” while inside the edit window


When editing a dataPoint we must consider three elements

  • ID : this gives a name to the datapoint which can later be found when querying the UTM-Builder API (alpha). Be careful not to change it too often.
  • Default Value: a Datapoint must be filled with data. This describes the most basic data to be filled into the datapoint.
  • Recipes : These describe circumstances when to fill the Datapoint with data other than the default.

Default Value

The default value can be filled either from a Field value, or from a user defined Expression

In the sample shown the default value will come from the a Field called “audience”.

This is an example of the most simple mapping.

Whatever value is selected in the Field “audience” will go directly to its output in the UTMs according to where the Datapoint is positioned. For example here the button “selected” is selected and so the text “selected” will fill our datapoint.


Expressions can be used instead of simply mapping to a field. They add extra power and flexibility to your hands. There are 3 possible elements to use in your expressions

  1. Plain text – this is as simple as it sounds. What you type is what turns up in your data point.
  2. Field values – This maps the selected value for a given field into its place. To take the current value in the field audience (as above) we would type. ${audience} . ${audience} would then be replaced with whatever value is selected in the “Field” “audience”. In the case above – “selected”
  3. Formulas – There are a list of formulas that help create dynamic and interest values. Formulas are always UPPERCASE, and followed by enclosing bracket. They then take a number of arguments, which are seperated by commas. Eg FORMULA(argument1,argument2)

All three can be combined.


  • ${audience}-ware in the above example would result in select-ware as an output
  • DATE(${dateField}) might result in “2017-01-01”, if today is 2017-01-01 and the selected value in dateField is 0


We have at present a short list of formulas, but we are always open to suggestions. So if you need one just let us know.

  • DATE(numberOrDate)
    • DATE turns a number into Todays date plus that number of days. If it is passed a date as its argument it will return that date.
    • Arguments :
      • 1) a number or date
    • Returns : a formatted date YYYY-MM-DD
    • EG: when today is the 1st of March 2017 then
      • DATE(0) -> ‘2017-03-01’
      • DATE(1) -> ‘2017-03-02’
      • DATE(2017-01-01) -> ‘2017-01-01’
  •  HASH(value)
    • HASH return an MD5 of whatever string is place into it as a value. This can be useful if you wish to compact information into a utm param and use it as an id later. The result is always 32 characters
    • Arguments
      • 1) a set of letters
    • Returns: an MD5 hash of the string
    • EG: MD5(lemon-pie) -> ‘262364E3F7621048B079485EE7B1B217’
    • This inserts a placeholder for google adwords keyword. {keyword}
    • Arguments : none
    • Returns : {keyword}
  •  CURLYVAR(word)
    • This allows you to place a value between curly bracket. This can then be interpreted by advertising services like Adwords and bing. These services then populate the curly bracket with certain info when passing the url to clients
    • Arguments
      • 1) word to put in curly brackets
    • Returns : the word in curly brackets
    • EG
      • CURLYVAR(matchtype) -> {matchtype}
  •  SPLITPART(value, delimiter, part)
    • This breaks apart a string according to a delimiter and then return one of the parts. This can be useful when trying to compress multiple pieces of info into one button or field.
    • Arguments
      • 1) a string to split
      • 2) a character or set of characters to use as breaking points
      • 3) a number from 0 up that points to one of the split pieces
    • EG
      • SPLITPART(fb-ads, -, 1) -> ads
      • SPLITPART(0break1break2, break, 2) -> 2
      • SPLITPART(google-adwords, -, 0) -> google



After you have set the default value of a datapoint it is possible to set up recipes. Recipes are rules which are triggered based on the current state of the fields. They help dynamically fill datapoints, and are especially useful in case where we have a large profile. For example we might have a profile where there are sources “facebook” and “email” and mediums “paid social”, “organic social” , “newsletter”. We might notice that every time we are on source email the only possible medium is newsletter. We might then decide that we should always set this value, to avoid mistakes.


The rule in our head is simple.

When the source equals “email” the datapoint medium should equal newsletter.

Turning it into a recipe is just as easy.

  1. In our “medium” datapoint we click the plus button underneath Recipes.
  2. Then click the edit icon on the right toolbar of the added recipe.
  3. Next we set the value type to “Expression”
  4. Set the value to newsletter (as we want this to output)
  5. We add a rule / condition by using the plus icon in the “If …” bar.
  6. We set the new rule. source (The Field) does equal “email”

Now whenever the source is equal to email the default value will be overwritten, instead the value “newsletter” will be filled into the medium datapoint. This means that the end user can never make the wrong combo. In fact when the source Field value is set to “email” the user doesn’t even need to see the medium Field, this is something we will learn about in “Tests” and “Actions”, which change the visual elements and help us build a clean UI for the end tagger!

Notes on recipes

  • The last passing recipe will be the final datapoint value. If the rules of a recipe fires it will set the datapoint value and then continue checking the remaining recipes. If another recipe fires the second will overwrite the value in the datapoint. For this reason we should start with the least specific rules and move to the most specific.
    • Eg. If the source contains the letters “book” we might want to set the medium to “offline” (rule 1). But if the source contains “facebook” we want to set the medium to “social” (rule 2). Rule 1 must come before rule 2 otherwise “book” will be found inside facebook and overwrite the value

  • Recipe Rules have no OR feature. All of the rules must be true in order to fire the recipe. However it is easy to create OR behaviour, by using 2 recipes with the same expression or field value.
    • Eg. If the source equals facebook OR pinterest then we want the medium to be social.
  • Recipe Rules behave exactly like “Test” rules. They:
    • Evaluate the current value of a Field
    • All the rules for a recipe must be true for the recipe to be triggered (they behave like logical ANDs)
    • They can be equal or use Regular Expressions

They can be positive or negative. That is to say that they can be inverted. Eg. Medium datapoint equals “paid social” if the source Field is not equal to “mail”.