Using Liquid Language Template

Rather than show the same content across all your wallet passes and text messages, you’ll likely want to personalize mobile experiences with the use of variables. To do so, Vibes uses a system known as the Liquid Template Language framework from Shopify.

In the scenarios below, we’ll demonstrate a few ways you may want to use the tags and filters to output data for your customer. However, keep in mind that the most comprehensive information about Liquid Template Language is found in Shopify’s documentation.

What is Liquid Template Language?

This framework makes it possible to insert variables to your mobile passes and messages, which will change for each customer based on their unique customer data. We often refer to these variables and their outputs as “tokens” or “variable tags”.

In addition to simply displaying variables, the language’s Liquid Filters allow you to edit the formatting, append additional data, remove data, make calculations (including date manipulation), and much more.

Vibes Use Cases & Examples

User-friendly date formats

In our first use case, we’ll utilize Liquid Template Language liquid filters to display a date in its most user-friendly form. The way your dates are formatted in your marketing database may not be the way you want them to display for your users. To display them in a more readable format, you can reformat the variable using date filters.

For example, let’s imagine we are inserting an offer’s expiration date into the wallet pass. In our database, our expirations are formatted as yyyy-mm-dd. However, we’d like our customer to see mmmm d, yyyy.

You have already formatted the SmartLink URL you’ll be delivering to your customer. It looks like:[first_name]=Patrick&data[code]=127856&data[exp_date]=2021-03-20

In one of our fields in our wallet pass, we will include the variable for expiration. In this case, the variable looks like:

{{ exp_date | date: "%B %d, %Y" }}

Even though the date format in the original SmartLink URL was yyyy-mm-dd, the output would appear in our filtered format as:

Formatting for international

Another common use case is editing date formats for specific regions of your audience.

For example, say you are launching a campaign in both the U.S. and Canada. In the U.S., you know that dates are typically formatted as mm-dd-yyyy, while in Canada, the date is usually written dd-mm-yyyy. To address this, you decide to set up a unique campaign for each country.

For the American campaign, the variable is:

{{ exp_date | date: "%m-%d-%Y" }}

For the Canadian campaign, you use:

{{ exp_date | date: "%d-%m-%Y" }}

Now the pass is localized for each county. In Canada, pass holders will see:

Rolling expiration dates

Another common Liquid Filter involves a rolling expiration date. Let's run through an example of how to make a campaign like this in platform.

Say say your business wants to run an offer campaign for a free side with a burger box. You’d like each customer to have the same amount of time to redeem the offer, so you’d like to make the offer expire 30 days after the customer adds the pass to their mobile wallet.

You’d also like to display the date as: Day, Month Date, Year.

Example: Monday, April 21, 1998

While you could simply set the date to 30 days from the send date, note that some customers may not add their pass the same day it is sent. To ensure they have 30 days for the offer, you can use a Liquid Filter with the “now” value:

{{ "now" | date: "%d-%m-%Y" }}

The “now” value will populate the date value with whenever the pass was added to the end user’s device. However, we’ll still need to add the 30 days to calculate the expiration date. To do so, we’ll turn 30 days into an equivalent number of seconds, then add those seconds to the date.

{% assign seconds = 30 | times: 24 | times: 60 | times: 60 %}
{{ "now" | date: "%s" | plus: seconds | date: "%a, %b %d, %Y" }}

Notice the variables which will output the date format - "%a, %b %d, %Y". We have adjusted the "%Y" to be capitalized instead of lowercase. A lowercase "%y" would out put the last two digits of the year, but we want to output the entire year value, so we used the uppercase value instead. Manipulating those values will adjust the formatting (more on date formatting can be found on Shopify).

Pasting in the string above, our pass, added to the phone on Thursday, Feb 20, 2020, will render a date on the pass that displays Sat, Mar 21, 2020.

Incentive pools

You can also use these Liquid Filters in conjunction with incentive pools, which offer promotional incentive codes to users.

When the tag is used, the liquid filter uses the wallet pass’s unique identifier to identify the person record associated with that customer. If the person record has previously been issued a code from this pool, it will retrieve and display that same code. If they have never received a code from the indicated pool, the system will retrieve a new code, if any are available.

To do so, you’ll need the incentive code’s pool_id, which can be found in the UI when you navigate to the incentive pool in the platform. To identify the pool_id, simply look at the URL:

When you add the liquid tag to the pass, it should look something like this:

{{ incentive_code | pool_id: 12 }}


Avoiding duplicate codes

If you include the incentive pool tag in your actual wallet pass, a new code will be generated every time the user clicks on the SmartLink. In addition, if you add the tag in the SmartLink URL and on the wallet pass, two unique codes will be generated. Because more unique codes are being generated than necessary, this may cause the codes in your pool to be quickly depleted.

As a best practice, if you are using SMS to distribute your pass, we recommend setting the wallet using the variable {{ code }} where you’d like the code to display. Then, add logic in the SMS message to pass the incentive code pool directly to the code value in the wallet pass.

Limited supply

Let's say that your business wants to issue a thousand codes to the first thousand customers to add the pass. For those who are not fast enough, you’d like to include a message to try again next time. Inside of the Incentive tab of our platform, you would upload a CSV containing 1000 unique codes.

You would place a 'default' filter after the pool id content in the liquid filter, so that once the pool was out of codes, it would display a particular message. An example of this could look like:

{{ incentive_code | pool_id: 104678 | default: "Better luck next time!" }}

Dynamic MMS images

Liquid tags are a good way to personalize your content to individual customers. In this scenario, we’ll explain how you can use liquid tags to add personalized images to your API-triggered MMS campaigns.

  1. Create your event-triggered campaign. When you get to the media_url string, instead of inserting of a static media URL to send to every recipient, insert the following tag:

    If you’d like to include a default fallback URL, you can format it as:
    {{ ev.media_url | default: “[INSERT URL HERE]” }}

  2. Then, when you send the triggering event to the system, be sure to include the following string field: ”media_url”: “[INSERT URL HERE]”

  3. That’s it! The media URL from the event will be used to insert an image in your event-triggered MMS send.

Formatting Notes

  • If you are using a default url, do not forget the “” around the default URL.
  • While you can use a tag to set up your campaign, you cannot insert a liquid tag into a partial URL. See the example below of a URL that cannot be used:
    • NOT VALID:{{ev.media_url}}