This article provides you with information for setting up Push notifications to user groups across multiple mobile platforms and devices.
Introduction
To check the existing Push Messages, go to Campaigns->Mobile Engage->Push Messages tab.
On the main Mobile Engage page you can switch between the following tabs:
Push Messages tab
On this tab you can see details of all your push messages listed with their Name, Recipient source, Status, App name, Push type, the date it was Created and last Changed.
You can also click here the Create Silent Push button.
Clicking the delete is a hard delete action. It means that the delete action is irreversible and will delete the Push message permanently.
Translator View
The Translator view feature is to enable multiple translators to independently work on the translation of the different language versions of a push campaign.
To use the feature, the push campaign must already be created and that at least 2 Language have been added to the campaign (i.e. the default language plus 1 other language). It is possible to have numerous sessions running simultaneously to allow multiple translators update the text for their respective language version. The translator view is shown below.
The translator view does not have permission system restrictions, meaning that a translator will be able to update any language selected, including the default language text.
Recipient Source
A Push message can have one of the following Recipient sources:
- Automation Center - Sends push messages from an Automation Center program.
- Using a segment - Sends push messages to a standard Emarsys segment.
- Using a contact list - Sends push messages to a contact list.
Status
A Push message can have one of the following statuses:
- In design – Some content or settings are still missing.
- Tested - Test message has been sent but not launched yet.
- Ready to launch – Not activated yet, but ready to launch.
Creating a new push message
Click Create Push Message in the Push Messages tab to open the message creation wizard. Emarsys offers a very intuitive workflow for creating new push messages. These are presented in the form of the following main steps:
Scheduling step is only available if the recipient source is using a segment.
Message settings
Define the General settings of your brand new push message campaign (or rename your existing one).
General settings
- Message name – You can name (or later rename) your push message to identify the campaign on the Push Messages tab.
- Mobile app – You can select the mobile application on which you want to display your message notification. You can send your message only to one application. Only apps already associated with your account are listed here.
-
Recipient Source – Define the target audience of your message. For options, see Recipient source.
- Segment – You can select a pre-built segment, if you are using a segment for your recipient source.
- Apply segment criteria for devices – Optionally you can apply segment criteria for devices with various conditions.
-
Internal ID – A unique identifier of a push message feed, that enables the push message update feature: The consecutive push messages sent with the same Internal ID will update the content of the push messages sent previously with the same Internal ID.
You can select any ID as you wish keeping the following rules:- Internal ID shall be any string, containing digits and/or characters.
- Push messages with the same InternalID are overwriting the push messages with the same InternalID sent earlier.
The Push Message Update feature is currently on Pilot release for a limited number of clients only. If you are interested in participating in the Pilot phase, please contact your Client Success Manager.
Recipient source
The options for Recipient source are as follows:
- Automation Center - Sends push messages from an Automation Center program.
Mobile Engage Push Message can only be used in an Automation Center Program if:
- the Recipient Source is set to Automation Center,
- the Push Message is launched, or
- in Ready to launch status.
After the Push Message is launched, or in ready to launch status, it can be selected in the drop-down menu of the Mobile Engage node in AC. If the Push Message is not yet launched, then it will not show up in the drop-down.
- Using a segment - Sends push messages to a standard Emarsys segment.
If you previously used the Broadcast Recipient source, then all subscribers will be available in the Segment drop-down after selecting the Using a segment Recipient source. You can use the segment all subscribers to send a message to all subscribers of your application.
Mobile Engage segmentation is included in the universal segmentation feature of Emarsys, available in the Contacts->Segments menu. For details, see Creating Mobile Engage segments.
To create a Mobile Engage segment for broadcast messages, select Contacts who have linked devices for application for the segment criteria. The result is that all contacts, anonymous and known, are included in the segment.
- Using a contact list - Sends push messages to a contact list.
If a contact has multiple devices registered, each device will receive the push notification sent to that contact.
If a multiple contacts are registered with the same email, each of them will receive a push message. However, only one per device. The connection between contacts and devices is one-to-many.One device will not receive duplicated Push messages.
Apply segment criteria for devices
Tick the Apply segment criteria for devices checkbox to enable device level filtering. By ticking this option, the Conditions drop-down list is appearing.
Conditions
In the Conditions drop-down list you can select a segment criteria for mobile devices. If you initially created the segment and you added device level criteria here you can select that segment. The earlier set device level condition will be taken into consideration when sending a push message.
If you want to specify a device level condition you can do so by creating Mobile Engage segments. Here you can only verify that device level conditions specified when created a segment and these conditions are really taken into account. The supported segment criteria's are: OS version, app version, anonymous contacts and platform.
An example of device-level conditions is to target a specific OS platform. Therefore if the contact has 2 registered devices, e.g. iPhone and Android, the contact is only received the message on the targetted OS device. Device-level conditions are also useful as the contact list does not display device information like OS platform, OS version etc.
To refresh conditions from the segment, click the Refresh icon on the right.
When you are finished with your general settings, click Save as Draft to save your message for the first time.
Click Next step to continue to the Content Creation step.
Content creation
In the Content creation step you have several tabs to use for defining the content of your push message campaign and also the Preview pane to add text/media. The tabs in the Content Editor are the following:
Adding text and rich media
To add text to the push message, type the text directly into the Preview pane available on the right hand side of the screen.
Rich media is attached to the push message by following the steps below:
- Click on the Media Icon at the bottom right of the push message.
- Click on Open Media DB.
- Click on the plus icon to the right of the image you wish to add to the push message.
- If the image is to be different for Android, untick the "Use same URL in Android" and repeat steps 2 and 3.
- If there is an additional image to be added on Android e.g. a profile picture for the user which appears in both lock screen and expanded view as a small icon on the top right side of the push message, tick the "Thumbnail image for Android" and repeat steps 2 and 3.
- Click Apply.
| Attachment | Supported File Type | Max Size |
|---|---|---|
| Audio (Android & iOS) |
|
5 MB |
| Image (Android & iOS) |
|
10 MB |
iOS image dimensions: 1038x1038 px. iOS automatically scales images. In case of oversize, i.e., the image height is more than 1038 px, iOS downscales the image and applies padding, to display the image as a square. To avoid this, use a maximum width of 1038 px and height less than 1038 px.
Android image dimensions: Recommended image size: 1024x2048 px. Android does not impose image size limit, but automatically crops the image to 2:1 ratio. It is highly recommended to test the image display on various devices.
Personalization tab
Use the Visual Content Editor (VCE) to add new content (personalized token) to the push message field.
RDS tokens created with the old UI are not converted to the new VCE-based UI. All other, non-RDS tokens are migrated automatically.
For example, a contact data token, which was added to the campaign using the old UI will be converted and will look the same as other tokens added using the new, VCE-based personalization UI.
You can add a personalized token to your push message, as follows:
- Use the dynamic search field to find the required personalized token.
- Alternatively, you can select a token from the following categories:
- Capabilities: Contact data (General, Personal, Company, Other)
- Use Cases: External, First Name, Voucher
- Alternatively, you can select a token from the following categories:
- Drag the selected token over onto the Preview pane and drop it to the field where you want.
Use the >> double arrow icon at the bottom of the tabs to show labels of each content creation tab.
Tap Actions
Tap Actions allow you to add action buttons to the push message and/or set the default action of the push message to be push to in-app. You can add personalized tokens to action buttons' payload with information from contact- and relational databases.
Action Buttons
There is a limit of 3 action buttons for both iOS and Android
It is possible to add a default action and/or action button(s). The default action allows the user to click anywhere on the push message and action type specified when creating the campaign will be triggered. If a default action has been specified on the campaign, in addition to action buttons, the user can click on anywhere in the push campaign message or the action buttons.
You can add a default action or action button to your push message, as follows:
- Click on Add Default Action or Add Button on the Tap Action tab.
- Choose the Event Type. The options are:
- Application Event - To trigger an app event using key and value pair.
- Custom Event - To fire a custom event, which could be used to tracking, to be used in segmentation, trigger an automation program (Automation Centre or Interactions) or launch an in-app campaign.
- Dismiss - To dismiss the message.
- External URL - To send the contact to an external URL in the browser.
- Deep Link - To fire a deep link using a deep link ID and URL.
For the event types Application Event, and Deep Links, the app needs to be preconfigured to understand how to handle the event. Please find below additional information that would be useful for the developers when updating the SDK configuration:
- Application Event - the payload will be passed into the
eventHandler.handleEvent()with the name App Event. - Deep Links - the payload will be passed into the
eventHandler.handleEvent()with the name DeepLink.
The developer documentation for Android and iOS SDK's, as well as payload examples is available on our Help portal.
- For External URL or Deep Link, insert the URL. For Application and Custom Events, it is required to enter the following fields:
- ID - The ID of the button to be used for reporting purposes.
- Name - The Name of the button to be used for reporting purposes.
- Key and Value - The key and value of the action button to be used in the JSON payload.
- Click Apply
- Update the text of the action button directly in the Preview pane.
Push to In-app
Before you can configure the push message to be linked to an In-app campaign, it is required to first create the In-app campaign and have it configured in the Message Settings Section to have the Recipient Source of Push Message or allow targeting the In-app campaign from push on scheduling screen. The In-app campaign must also be active.
- In the Tap Action tab, click on Default Actions.
- Select the Type as Push to In-app campaign.
- Select the In-app campaign in the second drop down menu.
- Click Apply
Preview pane & contact preview
Preview pane
The live Preview pane on the right shows how your message will appear. You can cycle through the available displays using the arrows under the phone preview image.
Click Test Message for testing a push message.
Contact preview
The contact preview feature allows marketers to preview the campaign with the inclusion of the personalisation tokens replaced with the appropriate contact data. To utilise the feature, click on the contact icon.
In the search bar at the top left of the screen that is displayed after clicking the contact icon, enter the email address of a contact within the account. As the email address is typed, available options will be displayed. Click on the contact email address to move them to the Recent contacts section. It is possible to repeat this process to list the test contacts in the Recent contact section of the screen, this will expedite previewing using multiple contacts.
Once all test contacts have been listed, click on the eye icon to the right of the email address. The preview screen will now be updated with the campaign and the personalisation tokens replaced with the appropriate contact data.
It is not possible to use the contact preview feature with external event based personalisation, only with contact data housed within the Emarsys account.
Languages tab
You can add and remove languages. Use the dynamic search field to find the requested language or select it from the drop-down list then click Add.
Add any new languages and write the message content in that language. Languages which are not shown here will receive the content in the app's default language.
You can delete languages as well, but a default language is mandatory.
If you add a language but it has no content, those customers will also receive content in the app's default language.
Custom Data tab
Please note that we do not recommend adding custom data fields to push messages anymore. This feature will be deprecated soon.
You can add links to push messages on the Tap Actions tab.
In this tab you can perform the following actions:
- View and edit the deep link to your product page.
- Create your custom data fields with personalized tokens.
Custom Data Personalization
For detailed information, see The Emarsys Personalization Service.
For more information on custom data fields, links and deep links, see Custom data fields.
Platform Settings tab
In this tab, you can set the platform-specific values of your messages. These settings are not optional; if nothing is entered, the platform default values are used.
Two platforms are available: iOS and Android.
Platform-specific settings
- iOS: Badges – Set the number of badges.
- iOS: Sound – Enter the name of a custom sound file located in the main bundle of your application. This sound will play when the message is delivered.
- iOS: Interruption Level – Constants that indicate the importance and delivery timing of a notification. The four available values are: Active, Passive, Time Sensitive and Critical. For more information, see:
- iOS: Relevance Score – Controls the order of your customers's notifications in the iOS Notification Summary. The score can be set between 0 and 1, in 0.1 increments. For more information, see our guide to the iOS 15 updates of September 2021.
- iOS+Android: Root parameters – Allows additional custom information to be included in the push message payload. However, the mobile app needs to be updated first to properly interpret the new information; therefore, please consult with the app developer prior to using this section.
- iOS+Android: Expiration time – The period defined in seconds after which the push will not be delivered if the device is offline.
- Android: Channel Name - Select the channel settings to be used for the push message, as defined in the SDK implementation. If there is only one channel defined on the app, this option will not be available and the one channel settings will be used.
For detailed information, see The Emarsys Personalization Service.
Testing a push message
Click Test Messages button on the left.
In the appearing Send Test Message window, you can specify an email address or contact list to which a test message will be sent.
The test email address must be a valid address in your Emarsys database, associated with a known device. There should only be one contact with the stated email address on the contact record. If there are more than one contact record with the same email address, it is not possible to send a test message to that email address.
For sending the test message to a contact list, the maximum number of contacts allowed in the contact list is 50. This is to mitigate the risk of sending to a large audience by accident.
If sending of the test message fails, a red warning message appears on the screen. The reasons for this could be the following:
- No contact has been found in Emarsys database with the given email address.
- The email address has been found, but there is no device associated to it.
To test your message, click Save & Send.
Click Next step to continue to the Scheduling step.
Scheduling step is only available if the recipient source is using a segment.
Scheduling
When you have tested your message, and the recipient source is using a segment you can continue to the Scheduling step.
On this screen, the number of users in the applied segment are displayed.
Apart from the Mobile Engage segments, which use the Mobile Engage database, the number of contacts in the other segments types comes from the Emarsys database. In order to make this number reflect the actual number of opted-in customers, when creating these segments you should include Push notifications enabled as one of your required contact criteria, as shown below.
In the Scheduling section, you can either select Launch now for immediate action, or you can define a specific date and time in the future and click Schedule. Scheduling launches in the future is available to all kinds of recipient sources except the Automation Center.
When a message is scheduled for launch, the contents of the message are still editable right up until launch and can even be deleted. If the message content is deleted for any additional language, the default language will be used; if that is empty no message will be sent.
Canceling the campaign launch
The Mobile Push Cancel Campaign Launch feature has been rolled out. In that case, you do not see it in your account, contact your Client Success Manager.
Optionally, you can click the Cancel button to call off an already launched campaign.
Before canceling a campaign a warning message notifies you that canceling a launched campaign is irreversible and the campaign cannot be re-launched at all, later on.
A canceled campaign cannot be edited. First, you have to copy the campaign and make modifications on the copied version of it.
