{"__v":9,"_id":"575f759b64b8020e009cb8a2","category":{"project":"55e67aaa9cc7c62b00c4a1ea","version":"55e67aab9cc7c62b00c4a1ed","_id":"589b8e1fdbb7cd190026732c","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-02-08T21:31:11.878Z","from_sync":false,"order":6,"slug":"advanced-techniques","title":"Advanced Techniques"},"parentDoc":null,"project":"55e67aaa9cc7c62b00c4a1ea","user":"55d29988486de50d00327118","version":{"__v":10,"_id":"55e67aab9cc7c62b00c4a1ed","project":"55e67aaa9cc7c62b00c4a1ea","createdAt":"2015-09-02T04:27:23.612Z","releaseDate":"2015-09-02T04:27:23.612Z","categories":["55e67aac9cc7c62b00c4a1ee","55e67b5556007d23005fee7d","55e67b5dde6fef23009480ca","55e680efde6fef23009480db","55e6829485a9741900314e99","561c61b4ad272c0d00a892df","586c014c0abf1d0f000d04d4","58991d2ad207df0f0002186b","589b8e1fdbb7cd190026732c","58b8ca5e3265d70f001788d4"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-06-14T03:10:19.702Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"Interactive Notifications are a great way to let the user interact with your app without having to open it. \n\nCarnival supports sending to both iOS and Android to activate Interactive Notifications. \n\n\n## On iOS \nOn iOS, interactive notifications are configured via the [`UIUserNotificationSettings`](https://developer.apple.com/library/ios/documentation/UIKit/Reference/UIUserNotificationSettings_class/), [`UIUserNotificationCategory`](https://developer.apple.com/library/ios/documentation/UIKit/Reference/UIUserNotificationCategory_class/), [`UIUserNotificationAction`](https://developer.apple.com/library/ios/documentation/UIKit/Reference/UIUserNotificationAction_class/) classes, and their mutable counterparts.\n\n\nOn a UIUserNotificationCategory, an `identifier` property is set, which a push payload should include to activate this, plus any other relevant data. \n\nOn iOS, use the `startEngine` overload and call `startEngine:registerForPushNotifications:` with a `NO` value. Then register with your own types and settings. \n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"If you're supporting iOS 10 notifications, the structure of the payload does not change, however the classes you use natively will. The above classes have been deprecated in favor for those prefixed with `UN` (eg [UNNotificationSettings](https://developer.apple.com/reference/usernotifications/unnotificationsettings), [UNNotificationCategory](https://developer.apple.com/reference/usernotifications/unnotificationcategory), [UNNotificationAction](https://developer.apple.com/reference/usernotifications/unnotificationaction)).\",\n  \"title\": \"iOS 10 Support\"\n}\n[/block]\n## On Android\n\n[Actions](https://developer.android.com/design/patterns/notifications.html#actions) can be pre-defined for push notifications using the `addAction()` method. Actions are grouped by a \"category\" attribute that is sent as a part of the push bundle. When a notification arrives that contains a matching category attribute, the push data is injected into the action's intent and attached to the notification.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"//This Intent must explicitly define an Activity, Service, or BroadcastReceiver class.\\nIntent actionIntent = new Intent(this, MyBroadcastReceiver.class);\\nNotificationConfig config = new NotificationConfig();\\nconfig.addAction(\\n        \\\"category\\\",                       // Action Category\\n        R.drawable.ic_action_reply,       // Action Icon\\n        \\\"Reply\\\",                          // Action Text\\n        actionIntent,                     // Intent that is fired upon tap. \\n        PendingIntent.FLAG_UPDATE_CURRENT // PendingIntent Flags\\n);\\nCarnival.setNotificationConfig(config);\",\n      \"language\": \"java\"\n    }\n  ]\n}\n[/block]\nTo add more Actions to a category, call `addAction()` for each action and set them all to the same category.\n\n#### RemoteInput\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"NotificationConfig#addAction(String, int, CharSequence, Intent, RemoteInput, int) \",\n      \"language\": \"java\"\n    }\n  ]\n}\n[/block]\n`AddAction()` has an optional `RemoteInput` parameter that allows for user input to be included in the data that is sent. See [RemoteInput](https://developer.android.com/reference/android/app/RemoteInput.html) in the Android Documentation for more information, and see [Direct Reply](https://developer.android.com/preview/features/notification-updates.html#direct) For how to handle inline replies.\n\n#### Responding to Actions\n\nInside the bundle that is sent to the intent defined in `addAction()` is a valued called `\"_nid\"`. The hashcode of `_nid` is the identifier for the notification in the system tray.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"public void onReceive(Context context, Intent intent) {\\n    String notificationId = intent.getStringExtra(\\\"_nid\\\");\\n\\n    NotificationManager notificationManager = (NotificationManager) context.getSystemService(Context.NOTIFICATION_SERVICE);\\n    notificationManager.cancel(notificationId.hashCode());\\n}\",\n      \"language\": \"java\"\n    }\n  ]\n}\n[/block]\nAnother option is to use [`getActiveNotifications()`](https://developer.android.com/reference/android/app/NotificationManager.html#getActiveNotifications()) to get a reference to update the notification.\n\n## Sending a push\n\nOnce the category is defined and hard-coded by a developer, the key `category` can be used in both the Carnival Dashboard, Notifications, and Messages APIs. \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/0rWWfYQSRdqk2vJ2Dy3Q_5e1248d4-323a-11e6-8a9c-8c8e240e74e1.png\",\n        \"5e1248d4-323a-11e6-8a9c-8c8e240e74e1.png\",\n        \"653\",\n        \"552\",\n        \"\",\n        \"\"\n      ],\n      \"caption\": \"Fill in the Category box to trigger your interactive notification.\"\n    }\n  ]\n}\n[/block]\n## API Example\nSimply add the `category` key and value to the payload.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST -u BUNDLE_ID:API_KEY -H \\\"Content-type: application/json\\\" -H 'Accept: application/json' https://api.carnivalmobile.com/v3/notifications -d '{\\n  \\\"notification\\\": {\\n    \\\"to\\\": [{ \\\"name\\\": \\\"tags\\\", \\\"criteria\\\": [\\\"tag1\\\"]}, { \\\"name\\\": \\\"custom.string.mykey\\\", \\\"criteria\\\": [\\\"tag2\\\"]}],\\n    \\\"payload\\\": {\\n      \\\"alert\\\": \\\"This is a push notification test\\\",\\n      \\\"badge\\\": 1,\\n      \\\"sound\\\": \\\"Default.caf\\\",\\n      \\\"category\\\": \\\"TEST_CATEGORY\\\",\\n      \\\"any_key\\\": \\\"any_value\\\" //Arbitary keys/values.\\n    }\\n  }\\n}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"interactive-notifications","type":"basic","title":"Interactive Notifications"}

Interactive Notifications


Interactive Notifications are a great way to let the user interact with your app without having to open it. Carnival supports sending to both iOS and Android to activate Interactive Notifications. ## On iOS On iOS, interactive notifications are configured via the [`UIUserNotificationSettings`](https://developer.apple.com/library/ios/documentation/UIKit/Reference/UIUserNotificationSettings_class/), [`UIUserNotificationCategory`](https://developer.apple.com/library/ios/documentation/UIKit/Reference/UIUserNotificationCategory_class/), [`UIUserNotificationAction`](https://developer.apple.com/library/ios/documentation/UIKit/Reference/UIUserNotificationAction_class/) classes, and their mutable counterparts. On a UIUserNotificationCategory, an `identifier` property is set, which a push payload should include to activate this, plus any other relevant data. On iOS, use the `startEngine` overload and call `startEngine:registerForPushNotifications:` with a `NO` value. Then register with your own types and settings. [block:callout] { "type": "warning", "body": "If you're supporting iOS 10 notifications, the structure of the payload does not change, however the classes you use natively will. The above classes have been deprecated in favor for those prefixed with `UN` (eg [UNNotificationSettings](https://developer.apple.com/reference/usernotifications/unnotificationsettings), [UNNotificationCategory](https://developer.apple.com/reference/usernotifications/unnotificationcategory), [UNNotificationAction](https://developer.apple.com/reference/usernotifications/unnotificationaction)).", "title": "iOS 10 Support" } [/block] ## On Android [Actions](https://developer.android.com/design/patterns/notifications.html#actions) can be pre-defined for push notifications using the `addAction()` method. Actions are grouped by a "category" attribute that is sent as a part of the push bundle. When a notification arrives that contains a matching category attribute, the push data is injected into the action's intent and attached to the notification. [block:code] { "codes": [ { "code": "//This Intent must explicitly define an Activity, Service, or BroadcastReceiver class.\nIntent actionIntent = new Intent(this, MyBroadcastReceiver.class);\nNotificationConfig config = new NotificationConfig();\nconfig.addAction(\n \"category\", // Action Category\n R.drawable.ic_action_reply, // Action Icon\n \"Reply\", // Action Text\n actionIntent, // Intent that is fired upon tap. \n PendingIntent.FLAG_UPDATE_CURRENT // PendingIntent Flags\n);\nCarnival.setNotificationConfig(config);", "language": "java" } ] } [/block] To add more Actions to a category, call `addAction()` for each action and set them all to the same category. #### RemoteInput [block:code] { "codes": [ { "code": "NotificationConfig#addAction(String, int, CharSequence, Intent, RemoteInput, int) ", "language": "java" } ] } [/block] `AddAction()` has an optional `RemoteInput` parameter that allows for user input to be included in the data that is sent. See [RemoteInput](https://developer.android.com/reference/android/app/RemoteInput.html) in the Android Documentation for more information, and see [Direct Reply](https://developer.android.com/preview/features/notification-updates.html#direct) For how to handle inline replies. #### Responding to Actions Inside the bundle that is sent to the intent defined in `addAction()` is a valued called `"_nid"`. The hashcode of `_nid` is the identifier for the notification in the system tray. [block:code] { "codes": [ { "code": "public void onReceive(Context context, Intent intent) {\n String notificationId = intent.getStringExtra(\"_nid\");\n\n NotificationManager notificationManager = (NotificationManager) context.getSystemService(Context.NOTIFICATION_SERVICE);\n notificationManager.cancel(notificationId.hashCode());\n}", "language": "java" } ] } [/block] Another option is to use [`getActiveNotifications()`](https://developer.android.com/reference/android/app/NotificationManager.html#getActiveNotifications()) to get a reference to update the notification. ## Sending a push Once the category is defined and hard-coded by a developer, the key `category` can be used in both the Carnival Dashboard, Notifications, and Messages APIs. [block:image] { "images": [ { "image": [ "https://files.readme.io/0rWWfYQSRdqk2vJ2Dy3Q_5e1248d4-323a-11e6-8a9c-8c8e240e74e1.png", "5e1248d4-323a-11e6-8a9c-8c8e240e74e1.png", "653", "552", "", "" ], "caption": "Fill in the Category box to trigger your interactive notification." } ] } [/block] ## API Example Simply add the `category` key and value to the payload. [block:code] { "codes": [ { "code": "curl -X POST -u BUNDLE_ID:API_KEY -H \"Content-type: application/json\" -H 'Accept: application/json' https://api.carnivalmobile.com/v3/notifications -d '{\n \"notification\": {\n \"to\": [{ \"name\": \"tags\", \"criteria\": [\"tag1\"]}, { \"name\": \"custom.string.mykey\", \"criteria\": [\"tag2\"]}],\n \"payload\": {\n \"alert\": \"This is a push notification test\",\n \"badge\": 1,\n \"sound\": \"Default.caf\",\n \"category\": \"TEST_CATEGORY\",\n \"any_key\": \"any_value\" //Arbitary keys/values.\n }\n }\n}'", "language": "curl" } ] } [/block]