Personalization Templates

Personalization is here! If you follow our blog, you may have noticed that we have been tackling the issue of personalization for a while. See Big “P” and Little “p” in Message Personalization for more background.

tl;dr

  • Big-P Personalization means delivering timely and relevant messages to users. Messages are based on a user’s tastes and preferences, they show up at just the right time, and they do not disturb or annoy the user.

  • Little-p personalization means including that individual touch— a name, a rewards balance, a flight number.

We didn’t always think of it in these terms here at Urban Airship. But what we have been building, for going on 7 years now, is a Big-P Personalization service, one which allows you to provide engaging, relevant content for all users.

With the release of Templates, we now support personalization via the use of templates.

Example:

1. Create Template

In this example we will create a reusable template that defines fields for 3 variables: TITLE, FIRST_NAME, and LAST_NAME.

POST /api/templates HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-type: application/json

{
    "name": "Welcome Message",
    "description": "Our welcome message",
    "variables": [
        {
            "key": "TITLE",
            "name": "Title",
            "description": "e.g. Mr, Ms, Dr, etc.",
            "default_value": ""
        },
        {
            "key": "FIRST_NAME",
            "name": "First Name",
            "description": "Given name",
            "default_value": null
        },
        {
            "key": "LAST_NAME",
            "name": "Last Name",
            "description": "Family name",
            "default_value": null
        }
    ],
    "push": {
        "notification": {
            "alert": "Hello {{TITLE}} {{FIRST_NAME}} {{LAST_NAME}}, this is your welcome message!"
        }
    }
}

2. Get Template ID

After we create the template, we receive an ok response with the template ID:

HTTP/1.1 201 Created
Content-Type: application/vnd.urbanairship+json; version=3
Location: https://go.urbanairship.com/api/templates/ef34a8d9-0ad7-491c-86b0-aea74da15161

{
    "ok" : true,
    "operation_id" : "9ce808c8-7176-45dc-b79e-44aa74249a5a",
    "template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161"
}

3. Push to Template

Now we are ready to send a push notification to our audience, merging values for TITLE, FIRST_NAME, and LAST_NAME into the push payload, like so:

POST /api/templates/push HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-type: application/json

{
    "device_types": "all",
    "audience": {
       "ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881"
    },
    "merge_data": {
        "template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
        "substitutions": {
            "TITLE": "Mr.",
            "FIRST_NAME": "Boaty",
            "LAST_NAME": "McBoatface"
        }
    }
}

Dashboard support for personalization templates is coming soon!

For further details and additional endpoints, see Templates in our API reference.