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