This documentation is for our legacy platform hosted at mtag.io. If you are using the Object Manager and Studio hosted at bluebite.com, see our Updated Documentation.
List of Macros
Overview
Blue Bite Macros are used in the Studio to create rich experiences by referencing dynamic data points or transforming existing data points and/or user input. This page outlines all the References, Functions, and Objects that are available to use in the Blue Bite platform and groups them by Type.
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.
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.
"{{ "Exa mple" }}" → "Exa mple"
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.
"{{ ("Exa mple") }}" → "Exa mple"
Accessor Operator
Most useful macro variables are nested inside of objects. Objects represent a collection of macro variables most often strings.
I 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
Math operators
The following infix math operators are available
* / + - Operates on two numbers and produces a number. Note that division by 0 will result in a value of Infinity
== != Operates on two values that could each be a string, number, null, or boolean and produces a boolean value
<= >= < > Operates on two numbers and produces a boolean value
AND OR Operates on two boolean values and produces a boolean value
Array Literals
You can create Arrays in the macro language with the familiar [ ] brackets.
"{{[tag:data:color, tag:data:size][tag:data:choice + 0]}}" -> "red" | when tag:data:color is "red" and tag:data:choice is "0"
expressions in Array elements are not run until they are accessed (A.K.A. Lazy Evaluation). For this reason these statements only have to be valid if when accessed. For example
{{["Duck noise {{tag:data:quack}}", "Dog noise {{tag:data:ruff}}"][tag:data:animal_type + 0]}}
This would work when animal_type is “0” and value for tag:data:quack is provided or when animal type is “1” and tag:data:ruff is provided. Individual fallbacks are not required for each animal type for the others to work properly.
Interactions
Interaction Macros are generated in real-time when a user interacts with an Object. These Macros reference interaction attributes.
Interaction Macros
Interaction Macro Details
interaction:tech
These Macros will return the interaction method. {{ interaction:tech:value }} returns the letter value and {{ interaction:tech:name }} returns the name. Technologies and their associated codes are listed below:
interaction:verification
Will return the NFC verification state when applicable.
{{ interaction:verification:supported }} will return true or false
When true, {{ interaction:verification:result }} will return true or false
When false, {{ interaction:verification:result }} will be null
interaction:tamper
Will return the NFC tamper state when applicable.
{{ interaction:tampersupported }} will return true or false
When true, {{ interaction:tamper:result }} will return true (closed) or false (open)
When false, {{ interaction:tamper:result }} will be null
interaction:rk
Returns the interaction rolling code, which is a unique string for each interaction. This is useful in conjunction with the Rolling Key API.
Example Experience Files
Studio File with corresponding object. Note that previewing from the studio will not work for interactions, this must be done from the dashboard.
Tag
Tag Macros are available in real-time and reference the object attributes that a user is interacting with.
Tag Macros
Tag Macro Details
tag:address, tag:location, and tag:dma
See Location section below.
tag:data and tag:variable
To access any Custom Tag Data, or Tag Variables, replace [NAME] with the attribute name used in the Dashboard. This field is case sensitive.
Note: Avoid using spaces, capital letters or punctuation in custom attribute key names.
Device
Device Macros are available in real-time and reference the device with which a user interacts with.
Device Macros
Device Macro Details
device:id
A unique ID given for each device. This ID will persist on the device until a user clears his/her cookies. This ID is null if no cookie consent.
device:language
Language Macros are a subset of device Macros and they reference the language set by web browser of the user's device. Language Macros also have a defined Object structure:
device:language Example Object
{
"_type":"Language",
"code": "en-US",
"value":"en",
"region":"US"
}
Page
Page Macros reference the Studio page and the experience URL.
Page Macros
Object but by default renders as {{ pageu:url:value }} which is a String
Page Macro Details
page:url:param:<NAME>
Use this Macro to access any URL parameters. Replace <NAME> with the URL parameter name and this Macro will return the URL Parameter value. This field is case sensitive.
Local Variables
Local variables are attributes stored locally on a user's device. They will persist until that user clears his/her local storage.
Local variables are scoped to the Studio file assigned to an object. Different Studio files cannot read the other's local variables unless one Studio experience links to a second or third experience. In that case, all local variables will be scoped to the first Studio experience.
Local Variable Macros
Local Variable Macro Details
local:<NAME>
Use this Macro access any local variables. Replace <NAME> with the local variable name and this Macro will return the URL Parameter value. This field is case sensitive.
Form
Unlike tag, device, interaction, and page Macros, form Macros are not available at page load. These Macros respond to how user's engage with a form component if one is used in the Studio file.
Form Macros
Form Macro Details
form: vs Form:get("<ID>"):
When used outside a form wrapper, {{ form: }} Macros refer to any form on the page, but when they are used inside a form wrapper they will only refer to the current form.
{{ Form:get("<ID>"): }} Macros reference a specific form and can be used anywhere with no ambiguity. You must first replace <ID> with the component ID.
form:entry:<NAME>
Use these Macros {{ form:entry:<NAME> }} or {{ Form:get("<ID>"):entry:<NAME> }} to refer to user input in a form. These Macros will initialize as an empty string and update in real-time as users add inputs. <NAME> must exactly match the name configured in the form input settings.
form:response:body:<NAME>
Use these Macros {{ form:response:body:<NAME> }} or {{ Form:get("<ID>"):response:body:<NAME> }} to access a form's JSON response body, if applicable. These Macros will initialize after a form is submitted and can be used to relay the API response to users on the front end. These are typically either validation messages or success messages. <NAME> must exactly match the name in the JSON response. It is also possible to index into nested JSON objects.
Example form response: 400 Bad Request
{
"status":"error",
"message":"The request is not valid",
"errors":[
{
"message":"Required field 'email' is missing",
"errorType":"REQUIRED_FIELD"
}
]
}
{{ Form:get("<ID>"):response:body:errors[0]:message }} → Required field 'email' is missing.
Location
Location Macros and objects can reference a number of different location-based data points such as:
• An Object's given location
• The user's IP-based location at the time of interaction
• The user's GPS location if consent is given
• A distance measurement to/from a point on a map
• Convert between a latitude/longitude coordinate and it's given address or Designated Market Area (DMA)
Location Macros
Location Example Object
{
"_type": "Location",
"coords": {
"_type":"Coordinates",
"latitude":52.526821,
"longitude":13.368511
},
"timestamp":1544555347000,
"source":"ip"
}
Location Macro Details
Referencing Location Attributes
Combine functions and references in one Macro to access the location attributes.
Example: {{ Location:get("ip",{}):coords:latitude }} → 52.526821
location:get()
Use this Macro to get the user's location. There are three different location sources available: ip, geo_fast, and geo_slow. If geo_slow or geo_fast are used, the user will be prompted to share his/her location.
location:watch()
Similar to {{ Location:get() }} , this Macro will poll the user's location based on the interval specified (in seconds). This Macro only accepts geo_fast and geo_slow arguments.
location:current_location
This Macro references the most recent location object. It is typically employed in conjunction with {{ Location:watch() }} to reference the user's current location.
location:new()
This Macro allows the Studio editor to create a custom location object.
location:distance()
This Macro calculates the distance in meters between two location objects. A typical use-case is to compare the user's current location to a point-radius.
Example configuration for location based content:
Snippet
{{ Location:watch("geo_fast", 3, {}) }}
Action
Set Local Variable distance = {{ Location:distance( Location:current_location , Location:new(40.740604, -73.985309, {})) || 101 }}
Event
When Local Variable distance <= 100 , Show location-based content
Address & DMA Function Macros
Address Example Object
{
"_type":"Address",
"street":"121 E 24TH",
"city":"New York",
"postal_code":"10010",
"state: {
"_type":"State",
"code":"NY"
},
"country": {
"_type":"Country",
"name":"United States",
"code":"US"
}
}
DMA Example Object
{
"_type":"DMA",
"name":"New York, NY",
"code":"501"
}
Address & DMA Macro Details
Referencing Address & DMA Attributes
Combine address of DMA functions with references to access the Address or DMA attributes.
Example: {{ Address:from_location(Location:get("ip",{})):state:code }} → NY
Example: {{ DMA:from_location(Location:get("ip",{})):name }} → New York, NY
Address:from_location and DMA from_location
These functions convert an location object into an Address or DMA object.
Warning: Currently, these functions only support conversion of location objects with source of ip.
Other Macros
Cookie Consent
Cookie Consent macros work in conjunction with the Cookie Consent Component.
{{ CookieConsent:enabled }} will render true when the component is selected.
{{ CookieConsent:acknowledged }} will render true when the component is selected and the user either accepts or declines the cookie policy.
{{ CookieConsent:gave_consent }} will render true when the user accepts the cookie policy.
Note: If {{ CookieConsent:enabled }} is true , all Google Analytics tracking as well as the {{ device:id }} macro will be suppressed until the user accepts the cookie policy.
Functions
*Note: Regular Expressions (RegEx) are accepted in String functions.
Function Details
Array:find()
Use this function to search through a JSON array of objects. The first argument specifies the search key, the second argument specifies the value to match against, and the third argument isthe JSON array you are searching through.
Example:
The JSON array below can be parsed with Macro:
{{ Array:find("color","red",<PRODUCTS>):size }} → XL
"products": [
{
"color": "red",
"size": "XL"
},
{
"color": "blue",
"size": "S"
}
]
Date:to_locale_string(), Date:to_locale_date_string(), and Date:to_locale_time_string()
Convert Unix Timestamps into human-readable dates. The date-time will be shifted to the user's local timezone. It can be combined with {{ page:load_unixtimestamp }} to display the current time.
Examples:
{{ Date:to_locale_string({}, page:load_unixtimestamp) }} → 4/1/2020, 5:00pm
{{ Date:to_locale_date_string({}, page:load_unixtimestamp) }} → 4/1/2020
{{ Date:to_locale_time_string({}, page:load_unixtimestamp) }} → 5:00pm
Master Data
Master data are studio assets not exposed to the public.
