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

Macro Overview

Macros are short commands used in the Blue Bite Studio that return associated data or values when the Experience is rendered on an end user’s device.

You can also check out the tutorial What are Blue Bite Studio Macros? and see a List of Macros.


Any numeric expression inside a Macro will be treated as a number. Numbers can be used in conjunction with arithmetic and comparative operators.

{{ 1 + 1 }} → 2

String Literals

Double straight quotes " " inside a Macro denote that the text between those quotes is a string literal and not a reference. This is particularly useful with the fallback operator.

{{ "red" }}red

String Interpolation

The Macro operator can be used inside a string literal.

{{ "This shoe is {{ tag:data:color }}" || "Can’t find this item" }}

When tag:data:color is green → This shoe is green
When tag:data:color does not exist → Can’t find this item


Macro Operator

The Macro operator {{ }} indicates that any text inside double curly braces should be treated as an expression. For example, including {{tag:data:color}} will show the value of the tag's color attribute (e.g. "blue") – "tag:data:color" will not appear on the rendered experience.

Access Operator

In order to return the correct value, most Macros use objects and properties separated by the access operator :. The example below demonstrates how to use the access operator to reference the mtag_id property from a tag object.

{{ tag:mtag_id }}0123456789

In some cases, custom properties may have characters which are not supported in the Macro syntax. For example, properties that begin with a number or that have spaces. The example below demonstrates how string literals and the access operator can be used to create a valid expression.

{{ tag:data:"shoe color" }} when custom tag:data property shoe color exists and is green → green

{{ tag:data:shoe color }} has two expressions, {{ tag:data:shoe }} and {{ color }} the latter is not a recognized Macro expression → Error

It is even possible to use a reference as a key. Notice how parentheses are used to establish precedence.

{{ tag:data:(tag:data:color) }} when tag:data:color is green → {{ tag:data:green }}

Fallback Operator

A fallback value specified in a Macro displays if a reference is unavailable, or an expression is malformed. Add a fallback operator || to the Macro, followed by a fallback value — which is an expression, usually a string literal.

{{ tag:data:color || "red" }}

- When tag:data:color is green → green
- When tag:data:color does not exist → red
- When the key tag:data:color exists, but the value is empty → Empty String

Fallbacks can also be used for expressions that produce errors. In the example below, the Macro {{ tag:data:color }} is interpolated into a string and will either return the value or an error. A fallback value can be provided for the error cases.

{{ "This shoe is {{ tag:data:color }}" || "Can’t find this item" }}

- When tag:data:color is green → This shoe is green
- When tag:data:color does not exist → Can’t find this item

Tip: Notice how the Macro operators {{ }} are used inside a string literal to escape the string and return the respective value. This is covered in the string interpolation section.

Arithmetic Operators

In a Macro, basic mathematical operations can be performed on numeric expressions.

{{ 1 + 1 }} → 2

List of Arithmetic Operators
Arithmetic Operator
Using String Literals in Arithmetic Operators

When arithmetic operators are used with string literals, the Macro will try to coerce the string into a number. Adding a string literal that does not contain a number will result in an error.

{{ "1" + 1 }}{{ 1 + 1 }}2

Comparative Operators

In a Macro, comparative operators perform comparisons between strings, numbers, or booleans, returning either a true or a false value. Unlike arithmetic operators, comparative operators will not coerce a string into a number.

{{ "hello" == "hello" }}true

{{ "1" == 1 }}false

List of Boolean Operators
Arithmetic Operator
Not Equal To
Less Than
Less Than or Equal To
Greater Than
Greater Than or Equal To
Is Not
Exclusive Or

Escape Operator

Use a backslash \ to escape most reserved characters inside a Macro expression. Prepending opening braces with \ will escape the entire Macro expression and show double curly braces as a string.

My Shoe Is \{{ tag_data:shoe_color }}!My Shoe Is {{ tag_data:shoe_color }}!
{{ "Hell\"o" }}Hell"o
{{ "Hell\\o" }}Hell\o
{{ "Hello\" }} → Error, opening quote is not closed.


Functions are a specific type of Macros that take inputs and return a value or object. Functions, once called, may return a value or a JSON object whose properties can be indexed-into with the access operator :.
{{ Address:from_location(Location:get("ip",{})) }} → Address Object

     "street":"121 E 24TH",
     "city":"New York",
          "name":"United States",

{{ Address:from_location(Location:get("ip",{})):country:code }}US

Click here for a list of supported functions.

Order of Operations


Parentheses are used to ensure that part of a Macro expression evaluates before another.

{{ (tag:data:color_1 || tag:data:color_2) || "red" }}

Special Characters & URL Safe String

Values must be converted to be a URL safe string. There are two sets of characters to watch out for: reserved and unsafe.

List of Reserved Characters

Plus Sign
Equals Sign
Forward Slash
Exclusive Or

List of Unsafe Characters

Less Than Sign
Greater Than Sign
[ ]
{ }
Forward Slash

Array Processing

The values in this array can be access in a number of ways. Suppose a Studio form (component ID 1) returned this value via API

{{ Form:get("1"):response:body }}

          "name":"Men's Green Boot",
          "name":"Women's Red Heel",
          "name":"Gray Trainer",

Using index:
{{ Form:get("1"):response:body:shoes[0]:name }}Men's Green Boot

Using search:
{{ Array:find("sku","001",Form:get("1"):response:body:shoes):name }}Men's Green Boot