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.

Interaction

Interaction Macros are generated in real-time when a user interacts with an Object. These Macros reference interaction attributes.

Interaction Macros

Macro
Description
Type
Support
{{ interaction:time }}
Unix timestamp
Number
{{ 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 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
b
iBeacon
e
Eddystone
g
Geofence
n
NFC
p
Preview
q
QR-Code
s
SMS
u
URL
w
WiFi
unknown
Unknown
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.

Tag

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

Tag Macros

Macro
Description
Type
Support
{{ tag:mtag_id }}
mTag ID (base 10)
String
✔️
{{ tag:mtag_id36 }}
mTag ID (base 36)
String
✔️
{{ tag:type }}
Type
String
{{ tag:asset_id }}
Asset ID
String
✔️
{{ tag:asset_type_name }}
Asset Type
String
✔️
{{ tag:venue_name }}
Venue Name
String
✔️
{{ tag:venue_type_name }}
Venue Type
String
✔️
{{ tag:experience_name }}
Experience Name
String
{{ tag:studio_id }}
Studio ID
String
{{ tag:studio_name }}
Studio Name
String
{{ tag:address }}
Tag Address
Object
✔️
{{ tag:address:street }}
Address/Street
String
✔️
{{ tag:address:city }}
Address/City
String
✔️
{{ tag:address:state }}
Address/State Object
Object
✔️
{{ tag:address:state:name }}
Address/State/Name
String
✔️
{{ tag:address:state:code }}
Address/State/Code
String
✔️
{{ tag:address:postal_code }}
Address/Postal Code
String
✔️
{{ tag:address:country }}
Address/Country Object
Object
✔️
{{ tag:address:country:name }}
Address/Country/Name
String
✔️
{{ tag:address:country:code }}
Address/Country/Code
String
✔️
{{ tag:dma }}
DMA Object
Object
✔️
{{ tag:dma:code }}
DMA/Code
Number
✔️
{{ tag:dma:name }}
DMA/Name
String
✔️
{{ tag:note }}
Note
String
{{ tag:status }}
Status
String
✔️
{{ tag:location }}
Location Object
Object
✔️
{{ tag:location:coords:latitude }}
Latitude
Number
✔️
{{ tag:location:coords:longitude }}
Longitude
Number
✔️
{{ tag:organization_id }}
Organization ID
String
{{ tag:experience_id }}
Experience ID
String
{{ tag:tag_verifier_id }}
Verifier
Number
{{ tag:tag_verifier_slug }}
Verifier Slug
String
{{ tag:tag_verifier_name }}
Verifier Name
String
{{ tag:tag_verifier_enabled }}
Verifier Enabled
Boolean
{{ tag:tamper_detection_enabled }}
Tamper Detection Enabled
Boolean
{{ tag:uses_uid }}
Uses UID
Boolean
{{ tag:uid }}
UID
String
✔️
{{ tag:data:[NAME] }}
Custom user-defined properties
String
✔️
{{ tag:variable:[NAME] }}
Custom user-defined properties
String
✔️

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

Macro
Description
Type
Support
{{ device:id }}
Device ID
String
✔️
{{ device:ip }}
Device IP address
String
✔️
{{ device:user_agent }}
User Agent
String
✔️
{{ device:user_type }}
New vs Returning
String
{{ device:type }}
Device type
String
{{ device:model }}
Device model
String
{{ device:category }}
Mobile, tablet, desktop, other
String
{{ device:browser }}
Browser name
String
✔️
{{ device:browser_version }}
Browser version
String
{{ device:os }}
Operating system
String
✔️
{{ device:os_version }}
Operating system version
String
{{ device:manufacturer }}
Device Manufacturer
String
✔️
{{ device:carrier }}
Carrier
String
✔️
{{ device:language:value }}
Four-letter language code (en-US)
String
✔️
{{ device:language:code }}
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.

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",
  "value": "en-US",
  "code":"en",
  "region":"US"
}

Page

Page Macros reference the Studio page and the experience URL.

Page Macros

Macro
Description
Type
Support
{{ page:url:param:<NAME> }}
URL Parameter
String
✔️
{{ page:url }}
Full URL of Page
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
Support
{{ 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
Support
{{ 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
{{ Form:any_form_has_errors }}
String
✔️
{{ Form:get("<ID>"):response:status }}
Form Response Status
Number
✔️
{{ Form:get("<ID>"):response:body:<NAME> }}
Form Response Body
JSON Object
✔️
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 or Designated Market Area (DMA)

Location Macros

Macro
Description
Type
Support
{{ 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 & DMA Function Macros

Macro
Description
Type
Support
{{ Address:from_location(<LOCATION>) }}
Convert location object to address
Address Object
{{ DMA:from_location(<LOCATION>) }}
Convert location object to DMA
DMA Object
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

Functions

Macro
Description
Type
Support
{{ 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 Time
String
✔️
{{ Date:to_locale_time_string({},<UNIXTIME>) }}
Converts Unix Timestamp (milliseconds) into Date
String
✔️

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_local_string(), Date:to_local_date_string(), and Date:to_local_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_local_string({}, page:load_unixtimestamp) }}4/1/2020, 5:00pm
{{ Date:to_local_date_string({}, page:load_unixtimestamp) }}4/1/2020
{{ Date:to_local_time_string({}, page:load_unixtimestamp) }}5:00pm