Message Personalization

Personalizing messages helps users connect more with your app and website. Common examples are putting the person's name or abandoned cart item in the notification title, message or image.

There are generally 2 ways to go about this:

1. Using OneSignal's Data Tags for Tag Substitution within the email and notification Title, Message, Launch URL and image.
2. Tracking the User ID through your CRM or Database and targeting the device directly with custom messages. See our Internal Database, DMP, & CRM for more on how to set this up.

Tag & Variable Substitution

Push Notifications, Emails and In-App Messages support liquid syntax inline placeholders based on Data Tags set on each user's device. The tag key will be substituted with each individual device's tag value.

Let says for example you want to send a message with a user's name and current stage they are on in your game. Example:

Hello Josh! We just improved our controls, come back and see if you can beat level 10!

You can set 2 tags to all your users, for example: first_name and current_level.

Within the message, set the "tag key" within the liquid syntax inline with your message, for example: {{ tag_key | default: 'default_value' }}. Replacing tag_key with your own key, as well as the required default value.

Example tags set across 3 users.

User 1: tags: {first_name : Josh, current_level: 10}
User 2: tags: {first_name: "George", current_level: 9}
User 3: tags: {}

Send a notification with the following contents:
Hello {{ first_name | default: 'there'}}! We just improved our controls, come back and see if you can beat level {{ current_level | default: '1' }}!

This will result in the following notifications going out to each user.

Tag Substitution happens client side for In-App Messages but server side for Push and Email.

🚧

Character Limitations

Only use alphanumeric characters and an underscore ("_"). Spaces, Periods (or "dots"), etc in tag keys cannot be substituted/processed and will result in a blank.

Launch URL Substitution

You can add tag substitution into the Launch URL (and associated web URL and app URL) of the push. You should not include the http:// or https:// protocol in the tag. Also not recommended to include the site origin. It is recommended to only tag the path of the URL the user should go to.

For example, let's say you want to send the user to an abandoned cart page: https://myshop.com/cart/jonf867 where jonf867 is my "cart id"

You would tag the user with OneSignal.sendTag("cart_id", "jonf867");

Then set the Launch URL to be: https://myshop.com/cart/{{cart_id}} the cart_id tag key will be replaced with the tag value when clicked by the user.

Another example we share is to Auto-Segment By Subscription Page where you tag the user with the sub_page : pathname which is the path of the subscription page which the user subscribed.

For instance, if I subscribed on https://yoursite.com/finance/tesla-soars-today, my device will be tagged with sub_page : /finance/tesla-soars-today

OneSignal.push(function(){
  OneSignal.sendTag("sub_page", location.pathname);
});

However, if the URL also contains query parameters that you want to include. For example: https://yoursite.com/en_us/apps/personas/booking?date=01&city=SFO&price=300

Then you can use the location.pathname + location.search browser variables to capture the entire URL.

OneSignal.push(function(){
  OneSignal.sendTag("sub_page", location.pathname + location.search);
});

You can reference this in the Launch URL by adding: https://yoursite.com{{sub_page}} because the tag already contains "/". If the tag does not contain "/" make sure you add it.

You can always test your implementation by setting yourself as a test user. See Find Devices & Set Test Users more details.

Image Substitution

A common example for Abandoned Cart is to add the last item set to the cart's image in the push. You can simply tag the user with a key like "cart_image" and the value is the full URL to the image.

Then in the Dashboard Image field or API Image parameters, you can set the tag key surrounded by curly brackets {{cart_image}} and/or add a default image
{{cart_image | default: 'https://cdn.pixabay.com/photo/2016/03/27/19/33/sunset-1283872_960_720.jpg'}}

In addition to the main notification image, you can also use tag substitution for images and icons for different platforms under platform settings.

Target Directly by User Id

You can detect the User Id and target the device directly with custom push message. You can use the OneSignal Player ID or your own External User Id.

For integrating your CRM or Database see the Internal Database, DMP, & CRM Guide.

Also more details on this in our Transactional Messages Guide.

Advanced Substitution

The push and email fields that support tag substitution use Liquid syntax which can come in handy for certain situations. Be careful not to get too complex with this code as it could create delays or issues with sending. Anything beyond simple if-else statements or addition/subtraction options are not recommended.

{% assign balance = balance %}{% if balance == 0 %}Your balance is 0. {% endif %}{% if balance != 0 %}Your balance from 1000 is {{1000 | minus: balance}}{% endif %}

{% assign first_name = first_name %}{% if first_name contains "guest" %} Hi Amazing Person! {% else %} {{first_name | default: "Amazing Person"}}!{% endif %}