Contents
Personalizing push messages
The Mobile Engage personalization feature allows you to personalize push messages for known users with contact-level data and external event data.
You can insert personalization parameters into the Push message editor using {{ and }}. Between these tags, you can define if the personalization is contact-level or driven by an external event.
Contact-level personalization
Contact-level personalization is added using the convention:
{{ contact.<fieldID> }}
Where fieldID is the numeric ID of the Emarsys contact database field. You can use any system or custom field for personalization.
Example
Here is an example of a contact-level personalization using the first name of the contacts:
Hey, {{ contact.1 }}! Brace yourself, winter is coming.
Note: The IDs of all contact fields are listed on the left of the table in the Field Editor (Admin menu) .
External event personalization
You can send external events which will trigger Automation Center programs and send out push messages. External event personalization is added using the convention:
{{ event.key }}
Where key is in the global section of the JSON object.
Example
Here is an example API request for external event personalization:
{
"key_id": "3",
"external_id": "t.odinsson@example.com",
"data": {
"global": {
"hero_first_name": "Jessica",
"hero_second_name": "Jones"
}
}
}
You must include the keys in the editor to use the values for personalization:
Hey {{ event.hero_first_name }} {{ event.hero_second_name }}! Brace yourself, winter is coming.
Please note that external events can also be tested via the Emarsys API demo. To access the demo environment, please visit https://api.emarsys.net/api-demo.
UI and preview
At the moment, no user interface is present for the personalization feature, and the live preview in Mobile Engage is not showing the personalization parameters either. To see the results, you must test the message with the Test message function, using a contact that already exists in your Emarsys database.
Custom data fields
What are custom data fields?
Custom data fields allow you to attach metadata to push messages and act on this data after a message is delivered. These data fields will be available for every message you send with the Mobile Engage application, and can be personalized.
Mobile Engage custom data fields are merely the tools to deliver the information needed for opening a page, and it is your responsibility to look for the custom data fields in the push message payload and to process the data in the application.
The data is sent in the u parameter of a push message.
{
aps =
{
alert = “Check out our new running shoes”;
sound = default;
};
u = “{“deep_link”:http://lifestyle-labels.com/mobile/deep/link/productpage/234567654,”sid:792_1rwvShB5bxJ5}"
}
Creating custom data fields
Click Create New, and fill in the fields:
- String ID – The key which will be included in the push message. Do not use spaces in string IDs.
- Name – The name displayed on the Emarsys interface.
- Default value – You can add default values for every field, which will appear in the Custom Data section of the Content Creation page of your push message. If you do not edit them in the message, these values will be sent out.
- Hint – You can add a hint for every field to remind you what it does when you edit the field in the message. This will appear in gray when the value field is empty.
If you do not define a default value for a field and you do not add one manually, the field will be sent out as empty.
Viewing and editing custom data fields
The custom data fields for that app are now listed on the Apps tab and you can open them and edit their values.
For each push message, you can also edit the field values in the Custom Data section of the Content Creation page.
Using custom fields for deep links and parameters
Deep links are links which point to a certain screen within your application. For example, if you receive a message from a friend, the application will be opened at the message thread, or if you leave something in your cart, the application will be opened at your cart. Without deep links, the applications open at their main pages.
To use a deep link, proceed as follows:
- Create a field called Deep link with a string ID deep_link, and without a default value.
- Create the following fields if you are using Google Analytics:
- utm_source
- utm_medium
- utm_campaign
- Use default values for your push campaign. Change the campaign value only if the defaults do not suite your needs.
- The deep link data is sent in the
uparameter of the push message.
Mobile Engage segmentation
What is Mobile Engage segmentation?
Mobile Engage segmentation lets you create app-based segments so that you can address your customers in a highly personalized way, based on several device- and behavior-level criteria.
The Segments tab is on the front page of the Mobile Engage feature.
Creating a Mobile Engage segment
To create a new Mobile Engage segment, click Create New on the Mobile Engage Segments overview page and proceed as follows:
1. Add the Mobile Engage segment details
For all segments, an app has to be selected, which means that the criteria for the segment are only valid for the given app.
2. Define the device-level criteria
The following device-level criteria are available:
- Push accepted
- App version
- Timezone
- OS version
- Last mobile activity
- Installation date
- Language
- Platform
3. Define the behavior-level criteria
The following behavior-level criteria are available for analysis and segmentation:
- Opened
- Received
- Custom event
4. Check the results
Click Save & Apply in the Filter results window to save your segment and view the result.
Editing a Mobile Engage segment
Refreshing a Mobile Engage segment
Deleting a Mobile Engage segment
Limitations of Mobile Engage segments
Only Mobile Engage data is used when creating the segments; there is no direct access to any other contact data field in the Emarsys databases.
Rich notifications
What are rich notifications?
Rich notifications enable you to send images within push messages. It is also possible to have a Title and a Body element of your message.
How to implement the rich notifications feature?
When using the Mobile Engage SDK with Android, there is no additional modification needed to use rich notifications.
In case of iOS, the following has to be implemented:
1. Add a new Notification Service Extension target to your project.
2. In the Podfile, add the MobileEngageRichExtension to this target.
3. Install the pods with the pod install command.
4. If your selected language is Swift, create a Bridging-Header for your new target.
5. Open the NotificationService class in the target, and
- import the
MobileEngageRichExtension - extend the class
MENotificationServiceinstead ofUNNotificationServiceExtension.
The JSON format for rich notifications
iOS
In iOS, notification displaying is handled by the system. The payload format is restricted. For example, if you don't want to send a title, you can remove the title entry from the payload so an empty string will be sent. A Body is always required.
If the title or body entries are missing from the payload, the app will receive the message but it will not be displayed.
The payload has the following format:
{
"aps": {
"alert": {
"title":"Game Request",
"body":"Bob wants to play poker"
},
"mutable-content":"1"//if we want image
},
"image_url":"https://www.xxx.jpg"//if we want an image
}
Android
By default, on Lollipop and earlier versions, if the title is missing, the SDK inserts the name of the application into the title. From Marshmellow version onwards, the name of the application is already displayed by default, so nothing is inserted in the title.
If customers do not want the application name as title, they can provide a title in the ems_default_title custom data field.
The payload has the following format:
{
"title":"Game Request",
"body":"Bob wants to play poker",
"image_url":"https://www.xxx.jpg"//if we want an image
}
Please note that in both systems, the title is truncated to one line.
Restrictions and limitations
The service has some limitations in its usage.
| iOS | ||
|---|---|---|
| Mode | Type | |
| Text | Image | |
| Notification Center collapsed | Title is one line and it is truncated if too long. Body is four lines and it is truncated if too long. |
The small image preview is shown on the right. Title is one line and it is truncated if too long. Body is four lines and it is truncated if too long. |
| Lockscreen collapsed | Title is one line and it is truncated if too long. Body is four lines and it is truncated if too long. |
The small image preview is shown on the right. Title is one line and it is truncated if too long. Body is four lines and it is truncated if too long. |
| Floating collapsed | Title is one line and it is truncated if too long. Body is two lines and it is truncated if too long. |
The small image preview is shown on the right. Title is one line and it is truncated if too long. Body is two lines and it is truncated if too long. |
| Expanded | Title is one line and it is truncated if too long. If the body is long, it becomes scrollable. |
The image is shown at the top. Title is one line and it is truncated if too long. If the body is long, it becomes scrollable. |
Please note:
- Only HTTPS image URLs are supported.
- On iOS 9 image display is not supported, and the body is shown only in four lines.
| Android | ||
|---|---|---|
| Mode | Type | |
| Text | Image | |
| Notification panel collapsed | Title is one line and it is truncated if too long. Body is one line and it is truncated if too long. Title length varies between 20 and 55 characters, based on screen density. Title and body length varies between 20 and 55 characters, based on screen density. |
The small image preview is shown center-cropped. Title is one line and it is truncated if too long. Body is one line and it is truncated if too long. Title length varies between 20 and 55 characters, based on screen density. Title and body length varies between 20 and 55 characters, based on screen density. |
| Notification panel expanded | Expanded notifications are available from API level 16. Title length varies between 20 and 55 characters, based on screen density. Body length varies between 200 and 700 characters, based on screen density. |
Expanded notifications are available from API level 16. The image is shown in larger. The preview image disappears. Title is one line and it is truncated if too long. Body is one line and it is truncated if too long. Title length varies between 20 and 55 characters, based on screen density. Title and body length varies between 20 and 55 characters, based on screen density. |
| Lockscreen | Lockscreen notifications are available from API level 21. They look the same as Notification panel - Collapsed/Expanded. |
|
| Heads up | Heads-up notifications are not supported. | |
Please note:
- Only HTTPS image URLs are supported.
- The SDK does not support setting notification sound, but the user can set notification sounds to notification channels.
Android Oreo changes
With Android Oreo, the user gains full control over displaying notifications. The notification channels have four levels of importance:
- Low:
- When collapsed, only the title is shown in one line with the application name and creation date of the notification.
- Small image previews are not available in collapsed mode.
- When expanded, the notification looks like a regular expanded notification.
- Does not play notification sound.
- The notification's icon is not displayed in the status bar.
- Medium:
- Expanded and collapsed notifications look as usual.
- Does not play notification sound.
- High:
- Plays notification sound.
- Urgent:
- Displays a heads up notification.
On Oreo, heads-up notifications are not set on a per notification basis, rather on a per channel basis. This means that if you post into a channel that has Urgent importance, then that notification will display as a heads up notification on Oreo devices. Keep in mind that the user can lower the importance of channels, so it is not guaranteed that your channel will remain in the Urgent category.
Image size and file type
iOS
For iOS, the maximum possible dimensions for an image are 1,038 px x 1,038 px.
Images that are taller than 1,038 pixels will be downscaled with padding to give them a square appearance.
As a general rule, we recommend using images that have a landscape orientation with the width no more than 1,038 px. That will reduce the risk of distortion.
Although a portrait orientation will work, it could make the push notification tall and awkward-looking.
The maximum file size depends on the file type:
| Attachment | Supported file types | Max. size |
|---|---|---|
| Audio | kUTTypeAudioInterchangeFileFormat kUTTypeWaveformAudio kUTTypeMP3 kUTTypeMPEG4Audio |
5 MB |
| Image | kUTTypeJPEG kUTTypeGIF kUTTypePNG |
10 MB |
| Movie | kUTTypeMPEG kUTTypeMPEG2Video kUTTypeMPEG4 kUTTypeAVIMovie |
50 MB |
Android
For Android, keep images between 800 and 1,038 px wide.
Always use landscape orientation, as rich push notifications on Android are cropped to something close to 16:9 (the exact ratio changes depending on the device).