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

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