Overview
Zaius allows you to add dynamic content to your emails through personalization tags and quickly configure dynamic grids to inform content based on the actions customers are taking. However, sometimes you need to go beyond the simple UI-based configuration. Because of this, Zaius gives you the ability to script additional complexities into your dynamic content.
The Zaius templating and personalization language is based on the Shopify Liquid templating language. (Check out the reference material on the Liquid website. To perform Zaius-specific actions, Zaius added features on top of Liquid.
Behaviors
Dynamic grids automatically configure the Liquid required to pull the necessary content. To see what that Liquid looks like, simply drag a dynamic grid into an email, choose any behavior, and click Convert to Liquid. This will show a quick example of the Liquid code necessary to call data from a behavior.
For example, with a Cart Abandonment behavior, you might see something like:
{% assign products = behavior.cart_abandonment(range_start: 'auto', range_end: now(0), required: true, filters: array('z_content_shield_filter')).step1.list.product(image_url, name, price).top.limit(4) %}
behavior
: This tells Zaius that the message is querying for a behavior.cart_abandonment
: This is the identifier for the behavior. To find this manually, go to the Behaviors section, and click into a behavior. If the behavior is allowed to be used in content, the checkbox for "Make available for use in content templates" will be checked, and the identifier, called the "Content Reference Key", will be displayed.range_start
: The dynamic timestamp to use as the earliest timestamp a customer could have performed the first step of the behavior. Useauto
to allow Zaius to determine this automatically based on the campaign configuration. Otherwise, specify an offset from "now", in seconds, e.g.now(-604800)
would be 604800 seconds (1 week) before the message is sent to a customer.range_end
:The dynamic timestamp to use as the latest timestamp by which a customer must have performed the first step of the behavior. It is most common to usenow(0)
, which indicates that a user must have performed the first step of the behavior before the time of the campaign send. Otherwise, specify an offset from “now”, in seconds, the same as it is done forrange_start
.required
: Use this to further filter out the audience by requiring that customers must have completed the behavior at least once to be able to qualify for the campaign. Usetrue
if the behavior is important for the content (e.g, when showing cart abandoned products in a cart abandonment campaign). Usefalse
if it is not required that a customer completed the behavior (e.g., when showing cart abandoned products in a newsletter, which has its own core content).filters: array('z_content_shield_filter')
: This is a comma-separated list that further filters down the users to only those that match the behavior specifically for products that match the additional filter(s). By default, this includes thez_content_shield_filter
, which indicates that the Content Shield Filter is being applied (see this doc on the Content Shield Filter). It can also use other product filters (see this doc on filtering dynamic grid content). Note:filters
can only be used with product-based dynamic grids (i.e., those with an Object Feed of "Products").step1
: This tells Zaius to pull content from a specific step of the behavior. E.g., if a browse abandonment behavior is defined by "users who PDP View (step1) and then do not Order that product (step2)", specifyingstep1
tells Zaius to pull data from the PDP View event. Always use a step with a positive match (i.e., if the behavior is either the first step, or if the step starts "and then matched"). If the step is a negative match (i.e., if the behavior starts "and then did not match"), there is no event to pull data from. (See this doc for more information on behaviors.)list.product(image_url, name, price)
: This tells Zaius to pull a list of all matching behaviors, as well as which fields to pull. Typically this data is pulled from the product dimension. If data is needed at the event level, place the fields directly afterlist
(e.g.,list(event_type, action)
).top
: This specifies the sort order for the data returned. Use top to sort by frequency of match (e.g., to show the products that were viewed the most). Usenewest
to sort by recency of match (e.g., to show the most recently cart abandoned products first).limit(4)
: This provides the maximum number of results to return. The highest value this can be is20
.
Note: You cannot use behaviors in the first touchpoint of event-triggered behavior or transactional campaigns. Since the first touchpoint is sent to customers immediately upon being triggered, there is no time to pull additional complex datasets from the database.
Lookups
You can use Lookups to pull data directly from objects (tables) in the Zaius database.
For example, you could pull the most expensive products:
{% assign most_expensive_products = lookup.products(name, price).where(name =~ "*shirt*" and price < 300).top(price).limit(3) %}
lookup
: This tells Zaius that the message is querying for a lookup.products(name, price)
: This specifies the object from which the data is being pulled, and also the fields which are being requested.where(name =~ "*shirt*" and price < 300)
: This filters down the matches as specified. In this example, only products with "shirt" in the name, that have a price under $300, will match the lookup. If filtering on timestamp fields, the match can be based off ofnow
(e.g.,ts > now(-3600)
would match timestamps in the last hour), unix timestamps (e.g.,ts > 1234567890
would match timestamps after 2009-02-13 at 11:31pm UTC), or user-friendly dates (e.g.,ts > '2016-09-01T00:00:00'
would match timestamps after 2016-09-01 at midnight UTC).top(price)
: This specifies the sort order for the data returned. Use top or bottom to sort by the highest or lowest values of a given field. Note: if the object being queries is events, additional sort options are available by usingnewest
(most recent events are returned first) oroldest
(oldest events are matched first).limit(3)
: This provides the maximum number of results to return. The highest value this can be is20
.
Note: You cannot use Lookups in the first touchpoint of event-triggered behavior or transactional campaigns. Since the first touchpoint is sent to customers immediately upon being triggered, there is no time to pull additional complex datasets from the database.
cURL
cURL calls allow you to make API calls inside a message's content. This helps you to, for instance, call data from a Google spreadsheet, or send a customer update to a 3rd-party system. Note that Zaius now offers the API and Zaius channels to make API calls even easier (for example, see this help doc, which outlines how to use the Zaius channel to update a customer's consent when customers send a specific SMS message), but if the API needs to occur within the content itself, you will need to use cURL.
Take a look at the following example. Here, the goal is to update a customer attribute based on the dynamic content they were shown in an email. You'd see something like:
{% assign result = curl('https://api.zaius.com/v3/profiles').post.body('{"attributes": {"email":"{$ customer.email $}","last_shown_product_id": "{$ product.product_id $}"}}').headers(content-type: 'application/json',x-api-key: 'my_api_key').cache(0) %}
curl('https://api.zaius.com/v3/profiles')
: This tells Zaius that it is preparing an API call directed at a specified endpoint.post
: This is the type of API request; typicallypost
orget
.body('{"attributes": {"email":"{$ customer.email $}","last_shown_product_id": "{$ product.product_id $}"}}')
: This is the body of the request. In this case, the customer fields that are being updated. Note that in this example,last_shown_product_id
would need to be added as a custom field on the customer object (see this doc on creating custom fields), and thatproduct
is a variable assigned in Liquid that, separately, was supplied with aproduct_id
(e.g., via a behavior or lookup call).headers(content-type: 'application/json',x-api-key: 'my_api_key')
: This tells Zaius the headers to use on the Zaius call. In particular, make sure to specify thecontent-type
and any necessary API keys.cache(0)
: This is the amount of time to cache the returned data. If you need to always receive perfectly fresh data, use 0.
Other Zaius-Specific Data
Zaius makes several additional fields available. For instance, you can use a field for your company address in an email footer based on the value you provided in the Admin area. This will ensure that all your footers are automatically updated if the information changes in the Admin area.
Message-related information:
{{campaign.id}}
{{campaign.name}}
{{content.id}}
{{content.name}}
Account-level (these are the account values specified on the Admin > Company Info page):
{{zaius.account.site_url}}
{{zaius.account.company_address}}
{{zaius.account.company_name}}