This documentation is for our current platform, hosted at bluebite.com. If you are still using the mtag.io Object Manager or Studio to manage your Blue Bite account, please see our Legacy Documentation.

Macro Glossary

Syntax 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.

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

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 resolved in real-time, and are populated by the scan details catured when a consumer interacts with an Object. These Macros reference interaction attributes.

Interaction Macros

Macro
Description
Type
{{ interaction:tech }}
Derived from URL
String
{{ interaction:tech:value }}
Derived from URL
String
{{ interaction:tech:name }}
Derived from URL
String
{{ interaction:verified }}
Verification state
Boolean
{{ interaction:verification:supported }}
Verification supported
Boolean
{{ interaction:verification:result }}
Verification state
Boolean
{{ interaction:tampered }}
Tamper state
Boolean
{{ interaction:tamper:supported }}
Tamper supported
Boolean
{{ interaction:tamper:result }}
Tamper state
Boolean
{{ interaction:rk }}
Rolling Code
String
{{ interaction:token }}
Token
String
{{ interaction:touchpoint:slug }}
String
String
{{ interaction:touchpoint:technology:name }}
Technology Name
String
{{ interaction:touchpoint:technology:value }}
Technology Value
String
{{ interaction:touchpoint:identifiers:<NAME> }}
Identifiers accessed by <NAME>. This field is case sensitive.
String
{{ interaction:touchpoint:url }}
Full URL of Touchpoint
Object but by default renders as {{ pageu:url:value }} which is a String
{{ interaction:touchpoint:url:<URL_PROPERTY> }}
URL Parameter. This field is case sensitive.
A property on a URL such as hash, host,  origin, etc. String or Object for searchParams
{{ interaction:touchpoint:url:searchParams:<NAME> }}
searchParams parameter on URL parameter.
String
{{ interaction:touchpoint:verification:supported }}
Touchpoint Verification Supported
String
{{ interaction:touchpoint:verification:result }}
Touchpoint Verification State
String
{{ interaction:touchpoint:tamper:supported }}
Touchpoint Tamper Supported
String
{{ interaction:touchpoint:tamper:result }}
Touchpoint Temper State
String

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:

Value
Name
n
NFC
q
QR
unknown
Unknown (GS1 will resolve to this)
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.

Object

Object Macros are available in real-time and reference the object attributes that a user is interacting with.

Object Macros

Macro
Description
Type
{{ object:uuid }}
UUID
String
{{ object:data:[NAME] }}
Custom user-defined properties (case-sensitive)
String
{{ object:variable:[NAME] }}
Custom user-defined properties (case-sensitive)
String

To access any Custom Object Data, or Object 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.

Project

To access Project name or Project attributes, use the following macros.

Macro
Description
Type
{{ project:name}}
Project Name
String
{{ project:data:[NAME]}}
Custom user-defined properties (case-sensitive)
String

Device

Device Macros are available in real-time and reference the device with which a user interacts with.

Device Macros

Macro
Description
Type
{{ device:id }}
Device ID
String
{{ device:ip }}
Device IP address
String
{{ device:user_agent }}
User Agent
String
{{ device:browser }}
Browser name
String
{{ device:os }}
Operating system
Object
{{ device:os:value }}
Operating system/value (same as name)
String
{{ device:os:name }}
Operating system/name
String
{{ device:manufacturer }}
Device Manufacturer
String
{{ device:carrier }}
Carrier
String
{{ device:language }}
Language
Object
{{ device:language:code }}
Four-letter language code (en-US)
String
{{ device:language:value }}
Two-letter language code (en)
String
{{ device:language:region }}
Two-letter region code (US)
String
{{ device:language:script }}
String

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

Macro
Description
Type
{{ page:url:param:<NAME> }}
URL Parameter
String
{{ page:url }}
Full URL of Page

Object but by default renders as {{ pageu:url:value }} which is a String
{{ page:url:value }}
Full URL of Page
String
{{ page:load_unixtimestamp }}
Unix Timestamp of Studio Page Load (milliseconds)
Number

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

Macro
Description
Type
{{ local:<NAME> }}
Custom attributes
String

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

Macro
Description
Type
{{ form:status }}
SETUP, INITIAL, SUBMISSION, DONE, FAILED, or REDIRECT
String
{{ form:entry:<name> }}
Form Input Value
String
{{ form:response:status }}
Form Response API Status Code
Number
{{ form:response:body:<NAME> }}
Form Response Body
JSON Object
{{ Form:get("<ID>"):status }}
SETUP, INITIAL, SUBMISSION, DONE, FAILED, or REDIRECT
String
{{ Form:get("<ID>"):entry:<NAME> }}
Returns Input Name
String
{{ Form:get("<ID>"):response:status }}
Form Response Status
Number
{{ Form:get("<ID>"):response:body:<NAME> }}
Form Response Body
JSON Object
{{ Form:any_form_has_errors }}
true or false
Boolean
{{ Form:any_form_submitted }}
true or false
Boolean

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

Location Macros

Macro
Description
Type
{{ Location:get("ip",{}) }}
IP Location
Location Object
{{ Location:get("geo_fast",{}) }}
GPS Location
Location Object
{{ Location:get("geo_slow",{}) }}
GPS Location
Location Object
{{ Location:current_location }}
Current Location
Location Object
{{ Location:new( <LAT> , <LON> , {} ) }}
New Location
Location Object
{{ Location:distance( <LOC_1> , <LOC_2> ) }}
Distance between locations
Location Object
{{ Location:watch("geo_fast", <SECONDS>,{} ) }}
Continuously checks location from GPS
Location Object
{{ Location:watch("geo_slow", <SECONDS> , {} ) }}
Continuously checks location from GPS
Location Object
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 Macros

Macro
Description
Type
{{ Address:from_location(<LOCATION>) }}
Convert location object to address
Address Object
{{ Address:from_location(<LOCATION>):<KEY> }}
Get value from <KEY>  from Address
String
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"
  }
}

Address Macro Details

Referencing Address Attributes

Combine aAddress functions with references to access the Address's attributes.
Example: {{ Address:from_location(Location:get("ip",{})):state:code }} → NY
Example: {{ Address:from_location(Location:get("ip",{})):city → New York

Here is a list of country codes you can expect from the Address Macros.

Address:from_location

Converts a location object into an Address object.

Warning: Currently, these functions only support conversion of location objects with source of ip.

Other Macros

Macro
Description
Type
{{ CookieConsent:enabled }}
true or false
Boolean
{{ CookieConsent:acknowledged }}
true or false
Boolean
{{ CookieConsent:gave_consent }}
true or false
Boolean

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

Macro
Description
Type
{{ Array:find(<FIND_KEY>,<WITH_VALUE>,<ARRAY>) }}
Searches array and returns object
JSON Object
{{ String:to_upper_case(<STRING>) }}
Converts string to all upper case
String
{{ String:to_lower_case(<STRING>) }}
Converts string to all lower case
String
{{ Date:to_locale_string({},<UNIXTIME>) }}
Converts Unix Timestamp (milliseconds) into Date Time
String
{{ Date:to_locale_date_string({},<UNIXTIME>) }}
Converts Unix Timestamp (milliseconds) into Date
String
{{ Date:to_locale_time_string({},<UNIXTIME>) }}
Converts Unix Timestamp (milliseconds) into Time
String
{{ String:index_of("<searchValue>", <fromIndex>, "<text>") }}
Allows search of strings for the first occurrence of a search value (e.g. a substring), starting from the <fromIndex> character.
String
{{ String:replace(<FROM>, <TO>, <TEXT>) }}
Replace first instance of <FROM> within <TEXT>
String
{{ String:replace_all(<FROM>, <TO>, <TEXT>) }}
Replace all instances of <FROM> within <TEXT>
String
{{ String:slice(<BEGIN_INDEX>, <END_INDEX>, "<TEXT>") }}
Extracts a section of a string and returns it as a new string, without modifying the original string. See here.
String
{{ String:split("<SEPARATOR>", "<TEXT>")[<INDEX>] }}
{{ String:split("<SEPARATOR>", "<TEXT>")[<INDEX>] }}
{{ String:split("<SEPARATOR>", "<TEXT>")[<INDEX>] }}
{{ Number:to_fixed(<NUMBER>, <DIGITS>) }}
Returns a number rounded to a fixed number of digits.
String
{{ URL:new({}, <URL>) }}
Returns a URL object with properties hash, host, hostname, href, origin, password (legacy, do not use), pathname, port, protocol, search, searchParams (also an object), username (legacy, do not use)
Object

*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