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. For more information: The Emarsys Personalization Service.
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
Mobile Engage segmentation is being deprecated and it is now included in the universal segmentation feature of Emarsys, available in the Contacts -> Segments menu.
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.
Sending rich notifications with image attachments
This feature is only available for Mobile Engage campaigns that were created after July 2019. If your campaign was created before July 2019 and you would like to send rich notifications with image attachments, we recommend creating a new campaign.
To add images to your rich notification, proceed as follows:
2. In the Media Properties window, you can choose from the following options:
- You can select an image from your Media DB by clicking the Media DB button.
- You can paste an HTTPS image URL into the Image URL field.
3. Click the Android tab and choose from the following options:
- Show the same image as on iOS for Android – Select this option if you would like to display the same image on Android as on iOS.
-
Show the following image on Android – Select this option if you would like to display a different image on Android than on iOS. Select one of the following options:
- You can add an image from your Media DB by clicking the Media DB button.
- You can paste an HTTPS image URL into the Image URL field.
4. You can check your push message on the Preview screen.
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 | JPEG GIF PNG |
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).
