Liquid extensions

5 min

Liquid extensions are small, executable blocks of code, similar in concept to Connect Platform for Optimizely Data Platform (ODP) functions. They let app developers extend Connect Platform for ODP templating language used by marketers to configure ODP campaigns. It is based on the Shopify Liquid templating language. Each liquid extension is a function marketers working with your channel app can use in their templates to personalize messages.

Declare liquid extensions

Declare liquid extensions in the app.yml file. Below is an example of a generate_coupon liquid extension:

liquid_extensions:
  generate_coupon: #<-- function reference in liquid
    entry_point: GenerateCoupon #<-- File and Class name
    description: Generates a unique coupon code
    input:
      rule:
        type: string
        required: true
        description: The coupon rule to create the coupon from
      email:
        type: string
        required: false
        description: Email address to tie the coupon code to

Implement liquid extensions

The entry_point property defines the file and class name of the liquid extension. The file must be located in the src/liquid_extensions folder of your app.

The class needs to extend the LiquidExtension class and implement the perform method.

Below is an example class that generates a coupon code based on the input:

import {LiquidExtension, LiquidExtensionContext, LiquidExtensionInput, LiquidExtensionResult} from '@zaiusinc/app-sdk';
import {createHash} from 'crypto';

interface GenerateCouponInput extends LiquidExtensionInput {
  rule: string;
  email?: string;
}

export class GenerateCoupon extends LiquidExtension {
  public async perform(
          context: LiquidExtensionContext,
          input: GenerateCouponInput
  ): Promise<LiquidExtensionResult> {
    const rule = input.rule;
    const email = input.email ? input.email : '';

    // hash rule and email
    const couponCode = createHash('sha256')
            .update(rule)
            .update(email)
            .digest('hex');
    return LiquidExtensionResult.success(couponCode);
  }
}

Note The perform method executes per render.

Access liquid extensions in campaigns

Marketers can use liquid extensions you define in the content template form of your channel app. Inside liquid extension code (between {{ and }} brackets), marketers can use channel context. For example, the customer.email variable shown in the example below:

Execution of a liquid extension has the following syntax:

{{ app.<app_id>.<extension>(<input>: <value>, ...) }}

With the example above, if the app's ID is my_coupon_app, this extension is called:

{{ app.my_coupon_app.generate_coupon(rule: 'foo', email: customer.email) }}

This results in the generated coupon code being inserted into the rendered content at this location.

Liquid extensions are resolved every time a campaign runs and are passed to the validate and publish methods of your channel app.

Note You must document liquid extensions you provide in either the app overview document or the content template form.