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

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

- (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"];
        }
    }

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.

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo {
    if ([[userInfo objectForKey:@"screen"] isEqualToString:@"new_post"]) {
        NewPostViewController *npViewController = [NewPostViewController alloc] init];
        [self.window.rootViewController presentViewController:npViewController];
    }
}

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

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

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:

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

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

protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    
  Bundle extras = intent.getExtras();
  if (extras != null) {
    myValue = extras.get("myKey");
  }
}

🚧
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.