Personalisation

Personalisation is the ability to add specific subscriber data to notification fields. For example if you have one subscriber called "Joseph" and another called "Andrew", you can send a notification with a title which will read "Hello Joseph" to the first and "Hello Andrew" to the other

Personalisation Object

Personalisation is essentially an object consisting of at least two fields, table and column. There are other additional fields which are is (only for when column is set to "tag"), default and modifiers

table

The table column signifies the data table you would like to refer to. Currently we only support the values subscriber and preferences

column

Column field refers to the specific column in the table you would like to use. This varies depending on what you chose as your table value:

subscriber

If you chose subscriber as the table value, you can pick from following columns:

  • deviceType - the subscribers device type, will be resolved as either "IOS" or "ANDROID"
  • customerId - resolves subscribers customer id
  • lastSeen - resolves to a ISO date string of the last time the subscriber opened your app
  • totalSessionDuration - resolves to subscribers total sessions duration in milliseconds
  • averageSessionDuration - resolves to subscribers average sessions duration in milliseconds
  • sessionCount - resolves to subscribers total sessions count
  • countryCode - resolves to the ISO code of the subscribers current country e.g. "GB", "FR", "US"
  • cityName - resolves to the name of the subscribers current city

preferences

If you chose preferences as the table value, you can pick from following columns:

  • name - refer to the specific preference column. This must be followed on with the is personalisation field to specify which preference you are referring to. To get a full list of available preferences you can use the GET /preferences endpoint

is

This is used for preferences. So once you've assigned "name" as the value for the column field, you specify which preference you want to refer to using the is field. So lets say you have a preference with a name field of "firstName", to refer to it you would specify the is field as "firstName" so that the subscribers first name may be resolved

default

Value to default to if the targeted subscriber column contains no value

modifiers

Once the subscriber column has been resolved, you can assign various modifiers to it to display it in a certain way:

  • capitalizeFirst - If its a string capitalize the first letter
  • capitalizeAllFirst - If its a string capitalize the first letter of every word in the string
  • uppercase - transform all letters in a string to uppercase
  • lowercase - transform all letters in a string to lowercase

Referring to a personalisation within a notification field

As specified in the POST /notification and POST /notification/push endpoints, a notification object can take in a personalisation field which basically is an object of UUID keys and personalisation object values. To refer to these in the notification fields, refer to their UUID's within {{ ... }} brackets wherever you want to use them

NOTE: The only notification fields which are permitted personalisation are title, subTitle, message, url for video buttons or carousel images, and text field for video buttons

Examples

These examples use the POST /notification/push as an example and assume you have already created segments and uploaded content

In these examples, lets assume one subscriber has a firstName preference of "John", a lastName preference of "Wick", a age preference of 34, email preference of "[email protected]", customerId of "john007" and cityName of "London". The subscriber does not have a subscription preference

{
  "type": "STANDARD",
  "title": "Hello {{1451076a-b2bd-46a8-9ed6-6a328f9579a7}}", // resolves to "Hello JOHN"
  "subTitle": "You are {{9c82e6f7-51b0-4085-b157-93a077a950f0}} years old", // resolves to "You are 34 years old"
  "message": "You live in {{f2de0378-e3cb-41e4-ae65-0617744fc210}}", // resolves to "You live in London"
  "personalisation": {
    "1451076a-b2bd-46a8-9ed6-6a328f9579a7": {
      "table": "preferences",
      "column": "name",
      "is": "firstName",
      "modifiers": ["uppercase"]
    },
    "9c82e6f7-51b0-4085-b157-93a077a950f0": {
      "table": "preferences",
      "column": "name",
      "is": "age"
    },
    "f2de0378-e3cb-41e4-ae65-0617744fc210": {
      "table": "subscriber",
      "column": "cityName",
      "modifiers": ["capitalizeAllFirst"]
    }
  },
  "segment": {
    "id": "4beafba6-b851-4bf0-8ca4-695b38b7efff"
  },
  "ttl": 604800,
  "isDraft": true
}
{
  "type": "VIDEO",
  "title": "Ronaldo scores a double!",
  "message": "Choose his best goal",
  "contents": [
    {
      "options": {
        "orientation": "portrait",
        "zoomMode": "zoom",
        "useEmbeddedPlayer": true,
        "allowPreview": true,
        "fullScreen": true,
        "buttons": [
          {
            "text": "First goal",
            "textColor": "#F9AF05",
            "fontSize": "41",
            "backgroundColor": "#A71680",
            "position": {
              "top": 1693,
              "left": 387,
              "bottom": 1776,
              "right": 690
            },
            "buttonAppear": 3,
            "buttonDisappear": 3987,
            "url": "https://example.com/1?id={{752e6ae3-4268-4a42-ad4b-b0562b38e843}}", // resolves to "https://example.com/1?id=john007"
            "linkHandling": "defaultBrowser",
            "fullScreen": false
          },
          {
            "text": "Second goal",
            "textColor": "#F9AF05",
            "fontSize": "41",
            "backgroundColor": "#A71680",
            "position": {
              "top": 1588,
              "left": 393,
              "bottom": 1671,
              "right": 696
            },
            "buttonAppear": 4478,
            "buttonDisappear": 9130,
            "url": "https://example.com/2?id={{7ffb0e95-d9df-4440-b63b-754f350c3082}}", // resolves to "https://example.com/2?id=john007"
            "linkHandling": "defaultBrowser",
            "fullScreen": false
          },
          {
            "text": "We bothering you {{97a50fe4-5636-47eb-9cfa-41e2541040a2}}? Unsubscribe", // resolves to "We bothering you wick? Unsubscribe"
            "textColor": "rgba(249, 5, 5, 1)",
            "fontSize": "41",
            "backgroundColor": "rgba(245, 255, 25, 1)",
            "position": {
              "top": 1802,
              "left": 103,
              "bottom": 1883,
              "right": 967
            },
            "buttonAppear": 9474,
            "buttonDisappear": 15000,
            "url": "https://example.com/unsubscribe?email={{5604233f-5251-4d86-b1ed-d7543f2927fd}}", // resolves to "https://example.com/[email protected]"
            "linkHandling": "defaultBrowser",
            "fullScreen": false
          }
        ],
        "allowSharing": false,
        "allowScrubbing": false
      },
      "contentItem": {
        "id": "a47acd1c-5c14-4b25-b016-d8423f2fb1b9"
      },
      "presentation": "DEFAULT"
    }
  ],
  "personalisation": {
    "752e6ae3-4268-4a42-ad4b-b0562b38e843": {
      "table": "subscriber",
      "column": "customerId"
    },
    "7ffb0e95-d9df-4440-b63b-754f350c3082": {
      "table": "subscriber",
      "column": "customerId"
    },
    "97a50fe4-5636-47eb-9cfa-41e2541040a2": {
      "table": "preferences",
      "column": "name",
      "is": "lastName",
      "modifiers": ["lowercase"]
    },
    "5604233f-5251-4d86-b1ed-d7543f2927fd": {
      "table": "preferences",
      "column": "name",
      "is": "email"
    }
  },
  "segment": {
    "id": "4beafba6-b851-4bf0-8ca4-695b38b7efff"
  },
  "ttl": 604800,
  "isDraft": true
}
{
  "type": "CAROUSEL",
  "title": "New Summer Line!",
  "message": "View new summer collection while stocks last!",
  "contents": [
    {
      "sortOrder": 0,
      "options": {
        "buttons": [
          {
            "url": "https://example.com/hoodie?customerId={{97ce5db0-438b-4fd4-83ce-38c88546ce78}}" // "https://example.com/hoodie?customerId=john007"
          }
        ]
      },
      "contentItem": {
        "id": "b3c8844d-c3d7-4c23-906b-5c3b99b8d335"
      },
      "presentation": "CAROUSEL"
    },
    {
      "sortOrder": 1,
      "options": {
        "buttons": [
          {
            "url": "https://example.com/jeans?customerId={{b6bb5637-d3ec-429f-87f3-b8735f4ef97e}}" // resolves to "https://example.com/jeans?customerId=john007"
          }
        ]
      },
      "contentItem": {
        "id": "201593ef-6e77-495e-bfc3-53156e9ab753"
      },
      "presentation": "CAROUSEL"
    },
    {
      "sortOrder": 2,
      "options": {
        "buttons": [
          {
            "url": "https://example.com/special-offer?type={{5548dfa3-199e-4cb3-b809-4260026847d9}}" // resolves to "https://example.com/special-offer?type=basic"
          }
        ]
      },
      "contentItem": {
        "id": "25afed30-4163-4bdd-8c60-b7fc49baed12"
      },
      "presentation": "CAROUSEL"
    }
  ],
  "personalisation": {
    "97ce5db0-438b-4fd4-83ce-38c88546ce78": {
      "table": "subscriber",
      "column": "customerId"
    },
    "b6bb5637-d3ec-429f-87f3-b8735f4ef97e": {
      "table": "subscriber",
      "column": "customerId"
    },
    "5548dfa3-199e-4cb3-b809-4260026847d9": {
      "table": "preferences",
      "column": "name",
      "is": "subscription",
      "default": "basic"
    }
  },
  "segment": {
    "id": "4beafba6-b851-4bf0-8ca4-695b38b7efff"
  },
  "isDraft": true
}