What are Macros?

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

A simple Macro illustration

An NFC tag embedded in a shoe contains color data for that shoe, stored as Custom Tag Data in the Blue Bite Dashboard. As a Studio user, you want your end user’s Experience to display the color of the shoe when tapped, so you insert a Macro in a Studio field to return that tag data:
My shoe is {{ tag:data:color }}

The Macro — in double curly braces — returns that tag information, displaying it in the rendered digital Experience:

If the user then went and tapped a red version of the same type of shoe, the Experience would change to display “My shoe is red.” Because the Macro itself doesn’t change even though it displays different information, macros are simple ways to create contextual and personalized Experiences.

Macros can return information from a wide variety of sources, including tag properties, tag data, local variables, forms, API responses and more.

Macro Syntax

Macros are written as a single expression surrounded by double curly braces {{ }}. The most common type of Macro expression contains an object and one of its properties separated by the access operator :. Multiple access operators can be used to continually index into nested objects using additional references. You also can add a fallback default value to display if the Macro returns an error by entering it after a double pipe ||. A completed macro, then, for a tag with assigned color data looks like: {{ tag:data:color || "no color" }}. See more on Macro syntax and language.

You can insert Macros in nearly every field within the Studio, including:

  • Text field
  • Image source
  • Action URL
  • Event Wrapper: Value 1 or Value 2
  • Form Inputs and Form Body

Macros usually return their corresponding value automatically when the Experience is rendered. However, in the case of Macros that rely on the end user to take an action in an Experience — such as submitting a form — the Macro returns a value in response to that action.

Common Macro Examples and Use Cases

Local Variables

Local variables represent in-page actions consumers take while visiting an Experience and are saved locally on their device. Local variables are used for many purposes, including tracking page views, remembering if a consumer has filled out a form, or even for creating two different Experiences for a sales associate and shopper. Local variables are available until a devices’ browser local data and device cookies are cleared.

The following example illustrates how local variables can be used to display the number of times a consumer has viewed a page:

Local variable Macro:  {{ local:page_views || "0" }}

Step 1. Add an Action component to the Studio file. Configure the Action component as follows:

Step 2. Add a Text component and insert this Macro: {{ local:page_views || "0" }}

Step 3. Preview the Experience:

First page view on the left; second page view on the right.

Tag Properties

Tag properties are data you assign in the Blue Bite Dashboard that cannot be modified by end users, such as Asset ID, Asset Type, Venue Type, Venue Name, etc.

See the Dashboard Overview to learn how to edit tag properties.

This example shows how to use tag properties to track a Venue Name, which is a property you can set to display the location of the tapped object:

Tag property Macro: {{ tag:venue_name || "unknown" }}

Step 1. Configure the property value in the Dashboard:

Step 2. Add a Text component in the Studio file utilizing this Macro:

Tip: Make sure the Experience is assigned to the object. See the Studio Overview for more information.

Step 3. Preview the Experience:

Tag Data

Tag data consists of custom properties nested under tag properties in an object’s data defined in the Dashboard, allowing you to create additional descriptive fields.

This example shows how to use Tag Data properties in the Studio for an object with a defined SKU:
Tag data Macro: {{ tag:data:sku || "unknown" }}

Step 1. Edit the “Custom Tag Data” field in the Dashboard to add the SKU number of the item:

Note: Don’t forget to press the ⊕ icon
See the Dashboard Overview to learn how to edit tag properties in the Blue Bite Dashboard.

Step 2. Add a Text component in the Studio file that includes the Macro:

Step 3. Preview the Experience:

Note: A Macro may fail due to improper syntax or because the referenced field does not exist. If a Macro fails, it will return an error and the component it is used in will not be displayed. See the Fallback and Errors section below to see what to do in case a Macro fails.

Fallbacks and Errors

As a best practice, include a fallback, or default, value in every Macro to display if the Macro expression fails to return properly. In Macro syntax, fallback values are indicated with a double pipe ||, called the fallback operator.

This Macro includes a fallback: {{ tag:data:custom_property || "fallback value" }}.

The following examples demonstrate what a Macro will return given different sets of Tag Data for a luxury purse with an NFC chip embedded.

Case 1: Tag Data property color exists on the object, its value is: Black.
Macro: {{ tag:data:color || "Unknown" }}

Case 2: Tag Data property color does not exist on the object, so the fallback value is rendered on the Studio page.

Macro: {{ tag:data:color || "Unknown" }}

Case 3: Tag Data property color does not exist on the object, because there is no fallback, the Macro returns an error and there is no output.

Macro: {{ tag:data:color }}

Posted 
Mar 31, 2020
 in 
Tutorials
 category

More 

Tutorials

View All

Join Our Newsletter and Get the Latest
Posts to Your Inbox

No spam ever. Read our Privacy Policy
Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.