Overview

You can add custom key/value pairs to your push notification payload that will trigger a wide range of unique app experiences and give you more push message personalization options. Each key/value pair will enable specific app functionality designed by your app developers, and you can add as many as required.

Use cases

• Personalize the look and feel of your app for individual contacts
• Conditionally display content for different groups of contacts
• Pass tracking data for testing and analysis
• Preserve app functionality during SDK migration
• Play a custom notification sound

Custom keys defined at the channel level will be available across all push messages automatically. Your custom keys can also be edited uniquely for every message during message creation.

Create custom keys

1. Log in to your Cordial account and navigate to Settings > Account Settings.

2. Choose Push (or your custom push channel label) from the left navigation menu.

3. Select Edit in the Mobile Push Keys section to add new or modify existing key/value pairs. The value field accepts contact and system Smarty variables such as {$contact.attributeKey} and {$mcID}, giving you access to additional data for analysis and message personalization.

Custom key/value pairs are not visible to your contacts. These fields are interpreted by your app's code to trigger predefined app behaviors.

Changes to channel level custom keys will not affect existing message drafts. To update custom key/value pairs on existing drafts, modify them during message creation under Custom Keys.

• Key: A unique identifier for the data within the value field
• Value: Carries data associated with the key or points to the location of other data

Custom notification sound

Using custom keys, you can specify a sound file to play when the notification arrives on the device.

1. To do so, choose Sound in the Key dropdown.

2. You will need to specify a file for each applicable platform and include the full file name to be played.

Playing a custom notification sound requires some work from your app developer to prepare the sound file and have it bundled with your application.

Interruption level and relevance score

Cordial supports both new iOS 15 features: interruption level and relevance score.

Interruption level

Apps can specify what notifications include sounds or vibrations (interruptions), based on urgency. Select Interruption level in the Key dropdown and select one of the following:

• Active: The system presents the notification immediately, lights up the screen, and can play a sound.
• Passive: The system adds the notification to the notification list without lighting up the screen or playing a sound.
• Time Sensitive: The system presents the notification immediately, lights up the screen, and can play a sound. But it won't break through system notification controls.
• Critical: The system presents the notification immediately, lights up the screen, and bypasses the mute switch to play a sound.

You need to submit an application to Apple to get approval for your app to use the Critical setting.

Users are still in control of notifications on their device.

Relevance score

Apps can also specify which push notifications are most relevant by setting a relevance score. This score determines which notifications are shown in the Notification Summary, and which ones are available after users click into the summary.

In Cordial, select Relevance score from the Key dropdown and assign the appropriate value.

Edit custom keys

You can also edit default custom keys during message creation. Changes made at the message level will not update saved custom key/value pairs at the channel level.

During message creation, locate the Mobile Push Keys pane at the bottom of the page and select Edit. You can now edit custom keys unique to the message.