Macros

Table of Contents

General Usage

Use double curly braces to indicate keywords

The keyword consists of two parts - prefix (which defines the scope) and actual field name.

Invalid keywords should evaluate to an empty string.

Values must be converted to be an URL safe string.

Any input should accept the macros (text, url, static input)

Examples

Platform

https://creative.url/?param1={{tag:asset_id}}&param2={{campaign:name}}

Studio

List of Macros

Supported
Not Supported
CategoryFieldKeywordNotesDashboardStudio
InteractionTime{{ interaction:time }}unix timestamp
InteractionTech{{ interaction:tech }}
{{ interaction:tech:value }}

Derived from URL
'b', 'e', 'g', 'n', 'p', 'q', 's', 'u', 'w', 'unknown'

InteractionTech{{ interaction:tech:name }}

Derived from URL, then mapped to a human readable name based on this table

InteractionVerified{{ interaction:verified }}"true", "false", "null"
InteractionTampered{{ interaction:tampered }}"true" (open), "false" (closed), "null"
InteractionRolling Code{{ interaction:rk }}
InteractionLat{{ interaction:lat }}
InteractionLon{{ interaction:lon }}
CampaignCampaign name{{ campaign:name }}
CampaignCampaign note{{ campaign:note }}
CreativeCreative name{{ creative:name }}
TagmTag ID (base 10){{ tag:mtag_id }}
TagmTag ID (base 36){{ tag:mtag_id36 }}
TagType{{ tag:type }}
TagAsset ID{{ tag:asset_id }}
TagAsset Type{{ tag:asset_type_name }}
TagVenue Name{{ tag:venue_name }}
TagVenue Type{{ tag:venue_type_name }}
TagTech - QR{{ tag:tech_qr }}(1 or 0)
TagTech - NFC{{ tag:tech_nfc }}(1 or 0)
TagTech - WiFi{{ tag:tech_wifi }}(1 or 0)
TagTech - RFID{{ tag:tech_rfid }}(1 or 0)
TagTech - URL{{ tag:tech_url }}(1 or 0)
TagTech - Eddystone{{ tag:tech_eddystone }}(1 or 0)
TagTech - iBeacon{{ tag:tech_ibeacon }}(1 or 0)
TagExperience Name{{ tag:experience_name }}
TagExperience Name{{ tag:studio_name }}
TagAddress - Street{{ tag:address_street }}
TagAddress - City{{ tag:address_city }}
TagAddress - State{{ tag:address_state }}
TagAddress - ZIP{{ tag:address_zip }}
TagAddress - Country{{ tag:address_country }}
TagAddress - Lat{{ tag:address_lat }}
TagAddress - Lon{{ tag:address_lon }}
TagAddress - DMA Code{{ tag:address_dma_code }}
TagAddress - DMA Name{{ tag:address_dma_name }}
TagAddress - Note{{ tag:note }}
TagStatus{{ tag:status }}
Tag Data<Custom Keys>

{{ tag:data:<key> }}

Supported:
{{ tag-data:<key> }}
{{ tag_data<key> }}

Notable tag_data key prefixes:

  • private.key (never show)
  • exclusive.key (show only if verified = true)

Tag Variables <Custom Keys>{{ tag:variable:<key> }}Formerly: Tag User Data
Local Variables<Custom Keys>

{{ local:<key> }}


PageURL Parameter{{ page:url:param:<key> }}Access query string parameters
PageURL

{{ page:url }}

{{ page:url:value }}

Full URL of page
PageUnix Timestamp of Studio Page Load {{ page:load_unixtimestamp }}
Form<Form Keys>{{ form:entry:<key> }}


Form<Form Keys>{{ form:response:<key> }}


LocationUser's Location on Page Load{{ Location:get( "geo_slow", {} ) || "" }}
{{ Location:get( "geo_fast", {} ) || "" }}

Returns Location Object

LocationUser's Continuous Location{{ Location:watch( "geo_slow",<time in seconds>, {} ) || "" }}
{{ Location:watch( "geo_fast",<time in seconds>, {} ) || "" }}

LocationUsed as Reference in Distance Function{{ Location:new( <Latitude>,<Longitude>, {} ) || "" }}
LocationUser's Distance from Location_1 to Location_2{{ Location:distance( <Location_1>,<Location_2> ) || "" }}
Location

User's Timestamp on Page Load

User's Latitude on Page Load

User's Longitude on Page Load

{{ Location:current_location:timestamp }}
{{ Location:current_location:coords:latitude }}
{{ Location:current_location:coords:longitude }}

Studio Macro Language

Inside most options parameters you can inject dynamic data via macros. Macros are parsed inside double curly braces ex: "My Shoe Is {{ tag_data:shoe_color }}!" → "My Shoe Is Red!". You can escape these brackets by prepending the opening mustache with a '\' character if you want to use double curly braces without rendering a macro. If a macro fails to evaluate to a string the macro will be blank in the resulting string. If the syntax of the macro is malformed the entire option may instead appear blank. Errors inside macros are logged to the browsers Javascript console.

Notation

In these examples I will give on the left an option in quotes and a result on right separated by → In some cases I also note additional conditions after the result and a "|" character.

String Literals

In macros you can create strings. In this trivial example they may seem unuseful but we will later see how these strings can be used in powerful ways.

"{{ "Foo Bar" }}" → "Foo Bar"

Parenthesis

In macros you can use parenthesis to ensure part of a macro evaluates before another. This trivial example may seem unuseful but we will later see how parenthesis can be used in powerful ways.

"{{ ("Foo Bar") }}" → "Foo Bar"

Accessor Operator

Most useful macro variables are nested inside of objects. Objects represent a collection of macro variables most often strings.


In this example you can see that the tag object contains the mtag_id string representing the current tags id inside the mtag platform.

"{{ tag:mtag_id }}" → "123456"


In some rare cases keys may have characters not supported in the macro language via this syntax. For example keys which begin with a number. This example shows how we can use string literals along with the accessor operator to access these keys.

"{{ tag:data:"1_strange_key" }}" → "Some Value"


You can even choose dynamic data as a key. In this example we use another piece of tag data. Note because of operator precedence we need to use parenthesis.

"{{  tag:data:(tag:data:key_to_use) }}" → "Some Value"

Fallback Operator

In some cases you may want to choose a fallback if the key you are looking for is not available. In this example we choose a default to use when tag_data is not available.

"{{  tag:data:shoe_color || "white" }}" → "white" | when shoe_color is blank
"{{  tag:data:shoe_color || "white" }}" → "red" | when shoe_color is "red"

NOTE: If you set a key value is set to a blank string it will not fallback as some value (albeit an easily overlooked one) was still provided.

Fallback can also be used for expressions that produce errors. In this example a blank value is being interpolated into a string, this produces an error instead of a string. We can provide an alternative string for that case.
"{{ "Hello {{ tag:data:owners_name }}" || "Sorry I don't know your name" }}" → "Sorry I don't know your name" | when tag data owners_name is empty

String Interpolation

You can not only use macro on the options body text but also inside a macros string literals. This simple example would otherwise be impossible.

"{{ "Hello {{ tag:data:owners_name }}" || "Sorry I don't know your name" }}" → "Hello Josh" | when tag data owners_name is set to "Josh"
"{{ "Hello {{ tag:data:owners_name }}" || "Sorry I don't know your name" }}" → "Sorry I don't know your name" | when tag data owners_name is empty

Functions

Functions take input variables and output another value in this example we hash together a string literal with dynamic text stored in tag data. Note this function currently is evaluated in the browser at runtime.

"{{ Location:distance( <Location_1>,<Location_2> ) || "" }}"

"{{ Location:distance( {{ Location:get( "geo_slow", {} ) || "" }},{{ Location:new( 52.520007,13.404954 ) || "" }} ) || "" }}" → Returns the User's distance from their current location to Berlin in meters.

Other Information

Types of Macro Values

String, Function, Objects, Null, Error, Numbers, Boolean Operators

interaction:tech:name Mapping Table

interaction URLinteraction:tech:valueinteraction:tech:name
https://mtag.io/b <mtag_36> …..biBeacon
https://mtag.io/e <mtag_36> …..eEddystone
https://mtag.io/g <mtag_36> …..gGeofence
https://mtag.io/n <mtag_36> …..nNFC
https://mtag.io/p <mtag_36> …..pPreview
https://mtag.io/q <mtag_36> …..qQR
https://mtag.io/s <mtag_36> …..sSMS
https://mtag.io/u <mtag_36> …..uURL
https://mtag.io/w <mtag_36> …..wWiFi
elseunknownUnknown

Location Object

Format
Location = {
  "coords": {
    "latitude":<latitude>,
    "longitude":<longitude>
  },
  "timestamp":<13-digit unix timestamp (milliseconds)>
 }
Example
Location = {
  "coords": {
    "latitude":52.526821,
    "longitude":13.368511
  },
  "timestamp":1544555347000
 }