Key-Value Payloads

Key Value Payloads are a great tool for sending custom data to your application inside of a push notification. You can specify the key and value in the push creation pane of the message creation screen.

IOS

From iOS 10+, notification payloads can be accessed by implementing the UNUserNotificationCenterDelegate methods and setting the delegate:

Objective-C

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [[UNUserNotificationCenter currentNotificationCenter] setDelegate:self];
}

- (void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler {
    // Get payload dictionary
    NSDictionary *userInfo = notification.request.content.userInfo;

    [[Game shared] setLevel:userInfo[@"special_level_jump_award"];
     
     completionHandler(UNNotificationPresentationOptionBadge | UNNotificationPresentationOptionSound);
}

- (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void (^)(void))completionHandler {
    NSDictionary *userInfo = response.notification.request.content.userInfo;
    
    [[Game shared] setLevel:userInfo[@"special_level_jump_award"];
     
    completionHandler();
}

Swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    UNUserNotificationCenter.current().delegate = self
}

func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
    let userInfo = notification.request.content.userInfo

    Game.shared().set(level: userInfo["special_level_jump_award"])
}

func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
    let userInfo = response.notification.request.content.userInfo

    Game.shared().set(level: userInfo["special_level_jump_award"])

    completionHandler()
}

On iOS 8 and 9, you need to implement two methods and use the userInfo dictionary to retrieve the value for a given key.

Objective-C

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo {
    [[Game shared] setLevel:userInfo[@"special_level_jump_award"];
}

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    NSDictionary *pushPayload = launchOptions[UIApplicationLaunchOptionsRemoteNotificationKey];

    if (pushPayload) {
        [[Game shared] setLevel:pushPayload[@"special_level_jump_award"];
    }
}

Swift

func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    Game.shared().set(level: userInfo["special_level_jump_award"])

    completionHandler(.noData)
}

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    if let pushPayload = launchOptions?[UIApplication.LaunchOptionsKey.remoteNotification] {
        Game.shared().set(level: pushPayload["special_level_jump_award"])
    }
}

On iOS, you can also create Deep Links in the same way to parts of your application without creating an In App Message via push payloads.

Objective-C

if ([[userInfo objectForKey:@"screen"] isEqualToString:@"new_post"]) {
    NewPostViewController *npViewController = [NewPostViewController alloc] init];
    [self.window.rootViewController presentViewController:npViewController animated:YES completion:nil];
}

Kotlin

if let screen = userInfo["screen"] as! String?, screen == "new_post" {
    let npViewController = NewPostViewController()

    self.window?.rootViewController?.present(npViewController, animated: true, completion: nil)
}

Android

On android the key value payload is passed through as a bundle on the Intent. If the application is not currently running, then you can get the bundle from the launching Intent:

Java

protected void onCreate(Bundle savedInstanceState) {
    ...
    Bundle extras = getIntent().getExtras();
    if (extras != null) {
        myValue = extras.get("myKey");
    }
    ...
}

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    ...
    val extras = intent.extras
    if (extras != null) {
        myValue = extras["myKey"]
    }
    ...
}

If the receiving Activity is currently running, then the intent is passed to the Activity’s onNewIntent(intent) method.

Java

protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);

    Bundle extras = intent.getExtras();
    if (extras != null) {
        myValue = extras.get("myKey");
    }
}

Kotlin

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    val extras = intent.extras
    if (extras != null) {
        myValue = extras["myKey"]
    }
}

Note: On Android, Key-Value Payloads can only be used with standard push notifications, not Messages. This is because the data is passed to the Activity launched by the pending intent in the push notification, and Message pushes open directly to the Full Screen Message.

Deep Linking with Key-Value Payloads

For both iOS and Android, _u is a special key that is handled differently to other Key-Value payloads. If found in a push payload, tapping that notification will instruct the operating system to open it. In the case of deep links, this means that your app will be called back. The ways these are called back are the same as described in Deep Linking. If the app is open on iOS, nothing will happen. If it is open on Android, you will still get the notification in your system tray, as per convention.

Disabling content-available on push notifications

When you send a push notification with an in-app message attached, Sailthru Mobile will automatically add content-available = 1 to the payload that is delivered to iOS devices. This is so that when a user taps on the push notification, the in-app message displays quickly because it has been preloaded in the background. There may be cases where you may not want to send content-available. For example, if you have implemented you own logic in the SDK callbacks, your servers would get requests on every push which may not be ideal. If you need to disable content-available, add the following key values to your push notification in the message composer.