Personalize messages using Custom Events

Custom Events help you track user activities and conversions from your app, website, etc. When you trigger an AutomationA set of conditions that your audience must meet before they receive a message., SceneA single or multi-screen in-app experience cached on users’ devices and displayed when users meet certain conditions in your app or website, such as viewing a particular screen or when a Custom Event occurs. They can be presented in fullscreen, modal, or embedded format using the default swipe/click mode or as a Story. Scenes can also contain survey questions., or SequenceA series of messages that is initiated by a trigger. Airship sends messages in the series based on your timing settings, and you can also set conditions that determine its audience and continuation. Sequences can be connected to each other and to other messaging components to create continuous user experiences in a Journey. with a Custom EventEvents that indicate that a user performed a predefined action, such as adding an item to a shopping cart, viewing a screen, or clicking an Unsubscribe button. Custom Events can trigger automation, including Sequences and Scenes. You can code them into your app or website, or send them to Airship from an external source using the Custom Event API. Custom Events contain properties that you can use to personalize messages., you can use properties from the event to personalize the resulting messages. For Sequences, you can reuse Custom Event properties in any message in the Sequence, which can help remind your audience about items they left in their shopping cart, or that an event that they’re interested in is happening soon.

Automations and Sequences support server-side and client-side Custom Events for personalization. Scenes support client-side Custom Events only.

Referencing properties in message content

Custom Events are associated with a channel or a Named UserA customer-provided identifier used for mapping multiple devices and channels to a specific individual. and carry properties that you can use to trigger and personalize your messages.

Start by creating an Automation, Scene, or Sequence using the Custom Event trigger, and select one or more Custom Events or event properties.

When writing the message, you can reference properties from the Custom Event trigger in your message or template. For example, you could iterate over the items a user purchased by referencing an items_purchased property.

{{#each items_purchased}}
{{qty}} x {{item_name}} = {{item_total}}
{{/each}}
{{total}}

If you reference a property that is not in an event, is null, or empty, the reference will be empty in your message, and your message may not make sense. Use the default handler $def to set default values, so that your message still makes sense if variables are empty or absent. For example, {{$def name "you"}} would insert you in the message if the name property in your Custom Event is empty or missing.

Custom Event personalization example

When personalizing messages or templates for a Custom Event-triggered Automation, Scene, or Sequence, you can use anything in the Custom Event’s properties object.

The following is an example Custom Event. We will use that to send a personalized receipt in a Message Center message.

{
   "occurred": "{{event_time}}",
   "user": {
      "named_user_id": "user"
   },
   "body": {
        "name": "purchase",
        "subscribe": true,
        "properties": {
            "customer_name": "Dave",
            "total": 48,
            "cost_units": "USD",
            "purchase": [
                {
                    "qty": 4,
                    "item": "MLB regulation baseball",
                    "per": "$12",
                    "total": "$48"
                },
                {
                    "qty": 2,
                    "item": "MLB official hat",
                    "per": "$15",
                    "total": "$30"
                }
            ]
        }
    }
}

Because Custom Event properties can include arrays, objects, and arrays of objects, we can loop through complex Custom Event properties using {{#each}}.

Next we put it all together with the default handler to craft the message:

Hi, {{$def customer_name "valued customer"}}!

Thanks for your purchase of:
{{#each purchase}}
{{qty}} x {{per}} {{item}} = {{this.total}}
{{/each}}
Total: ${{total}} {{cost_units}}

Your order is being processed. We'll message you again when it ships!

The result will look like this:

Hi, Dave!

Thanks for your purchase of:

4 x $12 MLB regulation baseball = $48
2 x $15 MLB official hat = $30

Total: $78 USD

Your order is being processed. We'll message you again when it ships!