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 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 applyconfig
- 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 lettercapitalizeAllFirst
- If its a string capitalize the first letter of every word in the stringuppercase
- transform all letters in a string to uppercaselowercase
- transform all letters in a string to lowercasedateFormat
- If the value is a valid date, parse the date and display it in the given format. This requires your accompanyingconfig
to be a date format string in valid DayJS format and advancedFormat syntax. E.G.YYYY-MM-DD
becomes 2022-07-01 ordddd [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, andtext
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
}
Updated about 1 year ago