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 Variables

Personalisation Variables are placeholders that you can use within your notification text. When a device receives a notification with one or more of these placeholders, the device will swap out the placeholder with the correct personalised value belonging to that specific subscriber. This is done before the notification is displayed.

You must define each of your variables using the Pushologies Portal/API before they can be used. Devices will not display notifications if unknown variables are found within the text, as this would result in placeholders being shown to the subscriber.

Each Personalisation Variable is an object consisting of name, description and defaultValue. When considering all of your variables together, they are referred to as your organisation's Personalisation Schema. The schema is a complete list of which variables are allowed to be used and is synced to each and every subscriber device once every 24 hours. This ensures all subscribers keep up to date with changes in your schema.

name

The name property is a unique identifier for your variable. This allows you to see at a glance what the variable is for.

description

The description allows you to provide a more detailed explanation to accompany your variable name. This can be useful to explain the context in which the variable should be used.

defaultValue

In the event a subscriber receives a notification containing a variable for which they do not have a personalised value, this value will be used.

For example: You want to say "Hey John", but no FIRST_NAME value is set for a subscriber. Using the defaultValue, your notification may say "Hey Subscriber" instead. defaultValue is a required field to ensure your notifications can always display correctly.

Modifiers

When creating a notification, you can add personalisation variables from your schema into notification text fields. Depending on the context in which the variable is used, you may want to alter how it is formatted - Dates/times are a great example of this. Our "modifiers" feature was created to make this possible.

You can assign various modifiers during notification creation to display a Personalisation Variable in a certain way. Each modifier you use can have the following properties:

type - This specifies which modifier you wish to apply
config - This is an optional property that allows you to further customise the behaviour of certain modifiers, such as our date formatter

The following types are supported:

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
dateFormat - If the value is a valid date, parse the date and display it in the given format. This requires your accompanying config to be a date format string in valid DayJS format and advancedFormat syntax. E.G. YYYY-MM-DD becomes 2022-07-01 or dddd [the] Do [of] MMMM YYYY becomes Friday the 1st of July 2022

Note: dateFormat is currently not supported in the Pushologies Portal.

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 array of UUID keys and personalisation variable 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 and assume you have already created segments and uploaded content:

{
  "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": [
    {
      "uuid": "1451076a-b2bd-46a8-9ed6-6a328f9579a7",
      "variable": {
        "name": "firstName",
        "modifiers": [
          {
            "type": "uppercase"
          }
        ]
      }
    },
    {
      "uuid": "9c82e6f7-51b0-4085-b157-93a077a950f0",
      "variable": {
        "name": "age"
      }
    },
    {
      "uuid": "f2de0378-e3cb-41e4-ae65-0617744fc210",
      "variable": {
        "name": "cityName",
        "modifiers": [
          {
            "type": "capitalizeAllFirst"
          }
        ]
      }
    },
    {
      "uuid":" 799cb86d-1699-4eee-b1ec-4173fcd438c9",
      "variable": {
        "name": "lastSeen",
        "modifiers": [
          {
            "type": "dateFormat",
            "config": "dddd [the] Do [of] MMMM YYYY [at] HH[:]MMA"
          }
        ]
      }
    }
  ],
  "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": [
    {
      "uuid": "752e6ae3-4268-4a42-ad4b-b0562b38e843",
      "variable": {
        "name": "customerId"
      }
    },
    {
      "uuid": "97a50fe4-5636-47eb-9cfa-41e2541040a2",
      "variable": {
        "name": "lastName",
        "modifiers": [{ "type": "lowercase" }]
      }
    },
    {
      "uuid": "5604233f-5251-4d86-b1ed-d7543f2927fd",
      "variable": {
        "name": "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": [
    {
      "uuid": "97ce5db0-438b-4fd4-83ce-38c88546ce78",
      "variable": {
        "name": "customerId"
      }
    },
    {
      "uuid": "b6bb5637-d3ec-429f-87f3-b8735f4ef97e",
      "variable": {
        "name": "customerId"
      }
    },
    {
      "uuid": "5548dfa3-199e-4cb3-b809-4260026847d9",
      "variable": {
        "name": "subscription"
      }
    }
  ],
  "segment": {
    "id": "4beafba6-b851-4bf0-8ca4-695b38b7efff"
  },
  "isDraft": true
}