10

In-App Messages: Getting Started

In app messages let you incorporate dynamic, personalized content into your app or website with very little development or engineering and help you continue conversations across channels. By personalizing messages based on the activities your audience performs in- or outside your app, you can maintain highly relevant interactions with your audience.

What is an in-app message?

An in-app message is a message sent to a user inside your app or on your website. It’s distinct from a push notification in that a user must be in your app or on your website to receive it. They can’t get your message if they don’t open your app or login to your site.

How it works

When you send an in-app message, the message waits in a queue until your recipient opens your app or website on one of their devices. Your audience sees your message when they open your app or website, and we log events based on their responses—whether they tap an action in the message, dismiss it, etc.

You’ll target your message message to your audience by their ID or email rather than by device or browser. In-App messages go to the first device or browser that you identify a person from. After a person receives your message, they won’t get it on another device or browser session (unless they enter a campaign again or you re-broadcast your message).

Before you begin

Your setup path might change depending on whether you’re a developer integrating with Customer.io or a marketer who wants to send messages. Use the chart below to better understand what you, or other members of your team, must to do before you can send in-app messages.

Before you can send an in-app message, you’ll need to:

1. Enable in-app messaging in your workspace
2. Set up your branding and in-app messages
3. Use your messages in campaigns or broadcasts
4. Set up your app and/or website:
   • For your app: incorporate our SDKs into your mobile app
   • For your website: add the JavaScript snippet to your site, or update it if you used a previous version.

Enable in-app support

1. Go to Settings > Workspace Settings and click Get Started next to In-App.
2. Click Enable in-app.

After you enable in-app messages, here’s how you’ll set up and use in-app messages in Customer.io.

Set up branding

Before you create messages, you’ll set your Branding rules—the colors, fonts, and padding options that you want to use across all of your messages. Branding settings help you create messages that look like a part of your app or website, and ensure consistency across your messages.

Go to the Branding tab under Content > In-App Messages to set or change your in-app branding rules.

Set up your mobile app

If you haven’t already, you need to enable in-app support.

1. Incorporate the in-app notifications SDK, so that your app can receive notifications from Customer.io.
   • iOS SDK
   • Android SDK
   • React Native SDK
   • Expo Plugin SDK
   • Flutter SDK
2. Identify the device user. In general, this means that your app requires people to log in, or otherwise make themselves known to you to receive an in-app message. You cannot send anonymous in-app messages.

Set up your website

After you’ve enabled the in-app message channel, you need to add our JavaScript snippet:

1. Add the JavaScript snippet to your website and update it to include the data-use-in-app property shown below.
2. Identify people on your website—either when they login or otherwise make themselves known to you (by email or ID).

If you’ve already added the JavaScript snippet to your website, you’ll need to add a line to include the data-use-in-app property, highlighted in the sample below.

Otherwise, copy the snippet below and paste it to your pages immediately before the closing </body> tag. Then, add your workspace’s API credentials (replacing YOUR_SITE_ID).

<script type="text/javascript">
    var _cio = _cio || [];
    (function() {
        var a,b,c;a=function(f){return function(){_cio.push([f].
        concat(Array.prototype.slice.call(arguments,0)))}};b=["load","identify",
        "sidentify","track","page","on","off"];for(c=0;c<b.length;c++){_cio[b[c]]=a(b[c])};
        var t = document.createElement('script'),
            s = document.getElementsByTagName('script')[0];
        t.async = true;
        t.id    = 'cio-tracker';
        t.setAttribute('data-site-id', 'YOUR_SITE_ID');
        t.setAttribute('data-use-array-params', 'true');
        t.setAttribute('data-use-in-app', 'true');
        t.src = 'https://assets.customer.io/assets/track.js';
        //If your account is in the EU, use:
        //t.src = 'https://assets.customer.io/assets/track-eu.js'
        s.parentNode.insertBefore(t, s);
    })();
</script>

Identify your website visitors

You must identify people before you can send them messages. You can do this by adding the _cio.identify beneath the JavaScript snippet.

// Send this when a user logs in or you otherwise identify them. 

_cio.identify({
    // Required attributes — you must include your customer's identifier (this can be either an email address or a unique ID value) in a property named "id"
    id: 'example-person',
    
    // Strongly recommended when you first identify someone
    created_at: 1339438758,   // Timestamp in representing when the user
                              // first signed up in Unix format.

    // Other attributes (properties you'll reference with liquid)
    email: 'person@example.com',
    first_name: 'Cool',
    last_name: 'Person',
    plan_name: 'premium'
});

When you send _cio.identify, you must send at least one identifierThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace.. Depending on your workspace settings, this may be either an id (the unique identifier the maps a person to your backend systems) or email address.

You can also send in additional attributesA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages. that are of value to you. In the above example we send first_name, last_name and plan_name attributes. You can use these attributes to segment your audience or to personalize messages for people.

Listen to in-app message events

The JavaScript snippet exposes several in-app message events that you can listen to via the _cio.on and _cio.off API. All events have a payload object with a type property that indicates the type of event and detail property that contains data corresponding to the event type.

Make sure you add "on" and "off" to the list of functions you call on _cio in the snippet.

<script type="text/javascript">
    var _cio = _cio || [];
    (function() {
        var a,b,c;a=function(f){return function(){_cio.push([f].
        concat(Array.prototype.slice.call(arguments,0)))}};b=["load","identify",
        "sidentify","track","page","on","off"];for(c=0;c<b.length;c++){_cio[b[c]]=a(b[c])};
        var t = document.createElement('script'),
            s = document.getElementsByTagName('script')[0];
        t.async = true;
        t.id    = 'cio-tracker';
        t.setAttribute('data-site-id', 'YOUR_SITE_ID');
        t.setAttribute('data-use-array-params', 'true');
        t.setAttribute('data-use-in-app', 'true');
        t.src = 'https://assets.customer.io/assets/track.js';
        //If your account is in the EU, use:
        //t.src = 'https://assets.customer.io/assets/track-eu.js'
        s.parentNode.insertBefore(t, s);
    })();
</script>

Message opened event

This event is triggered when an in-app message is shown to the user. The detail property always contains the messageId property whereas the deliveryId is not present if it’s a test message.

const onMessageOpened = function (event) {
    console.log('Type: ', event.type);
    console.log('Message Id: ', event.detail.messageId);
    console.log('Delivery Id: ', event.detail.deliveryId); // not present in test messages
};

// run the listener everytime message is shown
_cio.on('in-app:message-opened', onMessageOpened);

// run the listener only once
_cio.on('in-app:message-opened', onMessageOpened, { once: true })

// turn off the listener
_cio.off('in-app:message-opened', onMessageOpened)

Message dismissed event

This event is triggered when an in-app message is dismissed by the user.

_cio.on('in-app:message-dismissed', function (event) {
    // handle dismissed message
});

Message action event

This event is triggered when the user performs an action on an in-app message.

_cio.on('in-app:message-action', function (event) {
    // handle action
    
    // optional call to dismiss the message after handling the action
    event.detail.message.dismiss();
});

Message error event

This event is triggered when an in-app message produces an error.

_cio.on('in-app:message-error', function (event) {
    // handle error
});