Basics
Introduction
You can personalize your push notifications from the campaign editor using the data you have collected on your users. Batch provides a system of dynamic contents and a templating engine, allowing you to make dynamic messages for your campaigns.
Using the templating engine, you can reference and use user data inside your message. You can also add conditions to a message so that the content changes if some condition is fullfilled.
Here's a quick example to see how a dynamic content with a user attribute looks.
Dynamic Content
Before diving deep let's review the dynamic contents.
We have implemented a dedicated interface to allow you to use user attributes in dynamic content and display custom data easily. When editing your message, just click on the {...} button, choose the custom attribute you want to personalize your message with and the formatting.
That's it!
As some of the targeted users might not possess the attribute you are using, you can add a default value. The preview will let you see how the notification will look for 10 random installs.
Referencing attributes in your messages
If you are using APIs to send your notifications, here is the syntax to use dynamic contents in a message. All attributes usable in a query are available in dynamic contents.
They are:
attribute
orc.attribute
will refer to an installation attribute, collected from the SDK.u.attribute
will refer to a user attribute, collected via the Custom Data API.
If the user's c.current_level
attribute is 6
this evaluates to:
Referencing properties in object attributes
If you have an object attribute, you can reference its properties using the dot notation. Suppose you have an attribute address
that is an object with the following properties:
You can reference the properties like this:
Please note that, for now, object attributes are only accessible through event attributes.
Default values
Note that with the previous dynamic content, if the user doesn't have the attribute the resulting message will be:
This is probably not what you want, so you can add a default value. The default value is used when the attribute doesn't exist.
Here is how to use them:
If the user's u.special_offer
attribute is -15%
then it evaluates to:
Otherwise it evaluates to:
Referencing tag collections
All tag collections usable in a query are available in a dynamic content.
They are:
t.tag
will refer to an installation tag collection.ut.tag
will refer to a user tag collection.
However, there's a catch: since a tag is a collection of values and we can only output a single value using a dynamic content, we have to introduce the concept of filters. A filter is a function you can apply to a value to transform it.
In the case of a tag collection you can use the filter join
to concatenate all values into a single string.
For example:
Note that using a filter on a tag collection that doesn't exist always produces an empty string. Using the previous example, if the tag collection t.levels_done
doesn't exist the dynamic content evaluates to:
Loops are also available for tag collections, you can iterate over the values of a tag collection using the for
loop, as explained in the loop section.
Formatting
Using raw data like this is great but you might want to format the attributes yourself.
Formatting is done by using the following filters:
formatDate to format a date attribute
formatNumber to format a number attribute
The two filters are explained in details in the reference but here is a small example:
This evaluates to:
Be sure to check out the reference documentation to learn about all options !
Templating
Dynamic contents are already really powerful but they're not always enough.
For example, what if you want to display a completely different message based on which level a user is on, or how much fidelity points he has ?
This is a job for templates.
Templates allow you to do conditional statements, define variables and even do some light arithmetic.
Conditions
Suppose you want to congratulate a user based on how far he is into your game.
You could write something like this:
Now depending on the value of the user's current_level
attribute, the message will be one of the 3 possibilities.
Loops
You might want to exploit a list of values, for example to display a list of products a user has bought. for
loops are here for you, you can iterate over a list of values (like a tag collection or array attribute) and display them.
Variables and arithmetic
Sometimes it might be handy to compute some value and keep a reference to it so you can reuse it multiple times inside your template.
It is mainly a quality of life improvement but still useful.
For example, suppose you want to compute an expiration date based on multiple user attributes and remind the user when their subscription will expire.
Given the following rules:
premium users have 90-days subscription
users subscribed to the newsletter have a 75-days subscription
users younger than 25 and not premium have a 60-days subscription
all other have a 50-days subscription
You could write something like this:
This evaluates to:
Obviously the date will change based on what kind of subscription the user has.
There are a couple of new features here:
Defining a variable with
set $variableName = <expression>
. A valid expression has to return a single value of any type.Arithmetic. You can do simple math inside a template. Conveniently, you can add also do arithmetic on a date by using a duration
Concatenation. You can concatenate multiple values into a single one using the
~
operator.
Referencing custom app data
Dynamic contents and templating also allow you to reference custom application data to use in your messages.
These are tables of key/value pairs that you can upload using our dashboard.
For example, given a table with the name population_by_city
with the following content:
These are the population of Paris, Lyon, Marseille, Strasbourg and Bordeaux respectively.
You can now use them like this.
For someone in Paris, this evaluates to:
You can use any attribute or literal value as the lookup key. This works too:
However by doing this you lose the benefit of the custom app data table. This also works:
Language matching
The speaks
function allows to customize contents according to the user language. It's recommended to use this function instead of the b.language
native attribute as its value is not guaranteed to be stable. It accepts one or more languages as parameters, and returns true if the user language matches one of them according to the language matching rules.
Referencing trigger event data
In the context of a trigger campaign, using data from the trigger event is possible by using the attribute named trigger_event
. It is an object attribute that contains the attributes of the trigger event that triggered the campaign.
Here is how you can use it:
You can still access the trigger event label, tags and attributes using 3 specific functions:
triggerEventLabel()
: returns the label of the trigger eventtriggerEventTags()
: returns the tag collection attached to the trigger event. It can be used the same way as the tag collections.triggerEventAttr(attribute_key)
: returns the attribute value corresponding to the given key, it is the equivalent oftrigger_event.attribute_key
Here are a few examples of how you can use them.
Using the product name the user added to its cart:
Or if the products are listed in the tag collection:
Use cases
After looking into how it works, let's look at some use cases for dynamic contents and templates that would otherwise be hard or even impossible to do.
Electoral results
Suppose you want to report on electoral results for every city in France. There are currently 35416 cities in France and you want each user to have the result from their city when receiving the notification.
Without dynamic contents you could only do this by creating one campaign per city with a query matching the city. In that case you'd need more than 35k campaigns, this is obviously not good.
Instead you can do the following:
create a table named
electoral_results_201710
for example.each row in the table should be
$city_code => $result
.
Example:
These are the results of Paris, Lyon, Marseille, Strasbourg and Bordeaux respectively.
Then, create a message containing a lookup on the table and city code.
Example:
For someone in Paris this will evaluate to:
Each user will have a customised message based on where he is.
Loyalty program goals
Suppose you have a loyalty program for your application where the user can gain points and at some threshold you gain a loyalty level. Here is an example of a points scale:
100 points - regular
500 points - silver
1000 points - gold
5000 points - platinum
Suppose also that you attach special one time discounts every time the user gains a level.
Finally, suppose you want to remind a user that they're about to reach the next level with the following message:
Let's break down what we need:
the number of points to reach to get to a level
the number of points that a user has to gain
the discount for a level
Prerequisites
For this to work you need to feed us the data we'll be working with; you can do so using custom attributes or the Custom Data API.
We imagine the following user attributes:
u.loyalty_points
an integer
value representing the current number of points a user has
We also need two custom app data tables:
loyalty_thresholds
containing this:
The query
Before diving into the template let's look at what query we should use:
This will match any user that is just about to reach the next level.
The template
Here is how the template could look like:
Special discounts after a purchase
Suppose you want to give a user a special discount if they didn't buy anything after a month, and at the same time you want to remind them what they bought.
Suppose also that the discount changes based on how much time has passed since the purchase:
20% after a month
40% after more than two months
For example you could have the following message:
Let's break down what we need:
the product name of the last purchase
the date of the last purchase
Prerequisites
Like before, for this to work you need to feed us the data we'll be working with; you can do so using custom attributes or the Custom Data API.
In this use case we'll use custom events so you need to have that working too.
We image the following user attributes:
u.last_purchase_product_name
a string
containing the product name of the last purchase. It should be a properly formatted string.
We also need one custom event:
e.purchase
which tracks every time a user has purchased something.
The query
The query needs to filter users that haven't purchased anything since at least a month:
The template
Here is how the template could look like:
Did you like your {{ u.last_purchase_product_name }} ? Get a {{ $discount }} discount on all purchase today!
Last updated
Was this helpful?