{"_id":"5d72754147c96700358d7400","project":"55dd9f2e0efd5821000d54d9","version":{"_id":"55dd9f4dab0e4d210045aae9","__v":47,"project":"55dd9f2e0efd5821000d54d9","createdAt":"2015-08-26T11:13:17.024Z","releaseDate":"2015-08-26T11:13:17.024Z","categories":["55dd9f4dab0e4d210045aaea","55ddb5fa9067202b00ddff6f","55e0472c6bad670d0081f213","55e04764a44fae0d00214671","55e047a9a44fae0d00214672","55e047b258c5460d0076a9a7","55e95e337fc27b2d00d32cf2","55e979bda7ca823900ad549a","55edb8c18dcb210d0056900b","55f0365c8563861700a33765","55f03677d58f9b1900acf996","55f036938eeefc23001ea5de","55f036a38563861700a33767","55f036c08563861700a33769","55f036d02911b72100482cd7","55f036e92911b72100482cd9","55f036fa8563861700a3376b","55f0370ee507711900e58c69","55f0371df6101b1900c70700","55f0374f2911b72100482cdb","55f0375e2911b72100482cdc","560eb0f659cb8d0d0015cd52","560eb25239fad419002ae1e0","561fb64d4d67490d00804b2a","562b9f775a39cd0d009aff22","562ba0505a39cd0d009aff23","562ba149d56bc30d00f0cb18","562ba595f68a5f0d007b1f3b","562ba78fd56bc30d00f0cb1b","562ba8b95a39cd0d009aff27","562baadf6562140d001501d2","562bab37f68a5f0d007b1f3d","562bc1bf9ebc950d000f7523","562bc99ced4bea0d00c11dfa","562bd29c1b98640d00714520","562bd5875a39cd0d009aff60","562bdfabff2da50d002c0aaf","562be0bd5a39cd0d009aff75","57a0b476d8313e1900454439","5b19051beece890003020163","5b34ded01cb20f000391ad6d","5b3a325acffe770003fd29e5","5b3c737a7f7b890003365501","5b3c929b367036000391b11e","5b7c1e210dc2e20003871521","5da48fa678007c00d3826dfd","5da4905f535c4a002716833a"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2"},"category":{"_id":"5b34ded01cb20f000391ad6d","project":"55dd9f2e0efd5821000d54d9","version":"55dd9f4dab0e4d210045aae9","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2018-06-28T13:12:48.898Z","from_sync":false,"order":1,"slug":"push-notifications","title":"Push notifications"},"user":"55114030a226890d00911658","__v":0,"parentDoc":null,"metadata":{"title":"","description":"","image":[]},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2019-09-06T15:03:29.003Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":6,"body":"[block:api-header]\n{\n  \"title\": \"Understanding Push in Engagement Cloud\"\n}\n[/block]\nEngagement Cloud has the capability to send mobile push notifications to your app users using our Program Builder. It is important before we go over the steps on how to enable the push channel in Engagement Cloud that some key concepts are understood, and these are:\n\n## Users are addressed using email addresses\nEngagement Cloud requires all users you want to send push notifications to have an email address, as this is used to create a contact in Engagement Cloud, and you target your pushes by sending to contacts!\n\nIf you have a requirement to send push to users without an email address this is possible via API only, please talk to your account manager about our CPaaS APIs.\n\n## You need to embed our App Messaging SDK into your app\nOur **App Messaging - Foundation SDK** will need to be embedded in your app to enable us to register users as contacts in Engagement Cloud, and acquire the necessary push tokens automatically from your app in order for you to push to the users device.\n\nYour app will pass our SDK a security token, which it validates, to register a user. The security token needs to be in the JWT format [(JSON Web Token)](https://jwt.io/).\n\nThe following diagram illustrates the SDKs use:\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/5fe9180-Push_channel_-_app_diagram.PNG\",\n        \"Push channel - app diagram.PNG\",\n        1166,\n        680,\n        \"#f1f3f0\"\n      ]\n    }\n  ]\n}\n[/block]\n## You will need your mobile developers to help you configure push\nIn order for Engagement Cloud to send push messages via Apple or Google you must first push enable your app, which is usually done by your mobile development team in the app admin portals for Google and Apple. Once configured the team will need to configure various identifiers, certificates and tokens into Engagement Cloud in order to enable us to push to your app.\n\nWe strongly recommend having your mobile development team assist your with this configuration.\n[block:api-header]\n{\n  \"title\": \"Setting Up Push Notifications\"\n}\n[/block]\nTo [send push notifications from Engagement Cloud to your app](https://support.dotdigital.com/hc/en-gb/articles/360001827870), you need to do the following to link Engagement Cloud to your app and users:\n\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/5ac7c6a-push-steps.PNG\",\n        \"push-steps.PNG\",\n        980,\n        175,\n        \"#5ebb6a\"\n      ],\n      \"caption\": \"Enabling Engagement Cloud to push to your app\"\n    }\n  ]\n}\n[/block]\nThese steps ensure that Engagement Cloud has the necessary information to use Apple and Googles push channels to reach your app, and that the app passes the necessary information to send push to individual app users.\n\nThe steps are:\n\n## Create a push notification profile\nIn this step you will configure Engagement Cloud to be able to use Google's FCM and Apples APNS push services to send messages to your apps. This involves configuring tokens and certificates that are issued for Apple and Googles platforms when configuring push for your app, so it is recommended that you have someone will mobile development knowledge available to complete this step.\n\nIn addition to the push platform configuration we also need you to configure your security token values so that our SDK can recognise authenticate security tokens (JWTs) passed by your app to the SDK. Don't worry we explain how we use security tokens in more detail later.\n\nTo complete this step [complete these instructions by clicking here.](doc:creating-a-push-notification-profile-new) \n\n## Embed our SDK in your app\nNow that Engagement Cloud knows how to use push with your app it is time to embed our SDK into your app so that it can pass back the necessary information to send messages to a specific user.\n\nThe SDK will communicate with our platform for you to:\n* Register your app users into Engagement Cloud as contacts\n* Collect the necessary push tokens from the users device to allow pushes to be sent\n\nWe need to ensure that it is your app registering users for push and this is done by your app passing a JWT [(JSON Web Token)](https://jwt.io/) to the SDK. The passed JWT is verified using the authorisation information for the JWT you configured in your *push notification profile* in the previous step, and if valid the user is registered. Your app will need to provide a valid JWT to initialise the SDK, you can [find out more about how to create a JWT by clicking here.](doc:creating-a-json-web-token-new) \n\nTo complete this step select the links below for the technologies used to build your app:\n* [Native Android Apps](doc:android-sdk-new) \n* [Native iOS Apps](doc:ios-sdk-new) \n* [Hybrid Javascript based Apps (Cordova)](doc:javascript-sdk-new) \n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Supported iOS and Android versions\",\n  \"body\": \"Our mobile SDKs support the latest versions of Android and iOS, as well as the previous two versions.\"\n}\n[/block]\n## Pass app user information to the SDK\nEngagement Cloud requires you to pass the SDK an unique email address per user in order for it to create / update a contact, so that you can target these contacts for push sends. Once the user is registered after passing a valid JWT all your app needs to do is update the SDKs user profile with an email address and a contact will automatically be created in Engagement Cloud to allow you to push to this specific app user.\n\n[Click here to find out now to implement this in your app](doc:registering-your-app-users-for-push)\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Done\",\n  \"body\": \"If you have followed all the steps above you should now see your app users appearing as contacts in Engagement Cloud, and you can use program builder to send them push notifications!\"\n}\n[/block]","excerpt":"A tutorial for setting up your app to receive push notifications from the Program Builder in Engagement Cloud","slug":"setting-up-push-notifications","type":"basic","title":"Setting up push notifications"}

Setting up push notifications

A tutorial for setting up your app to receive push notifications from the Program Builder in Engagement Cloud

[block:api-header] { "title": "Understanding Push in Engagement Cloud" } [/block] Engagement Cloud has the capability to send mobile push notifications to your app users using our Program Builder. It is important before we go over the steps on how to enable the push channel in Engagement Cloud that some key concepts are understood, and these are: ## Users are addressed using email addresses Engagement Cloud requires all users you want to send push notifications to have an email address, as this is used to create a contact in Engagement Cloud, and you target your pushes by sending to contacts! If you have a requirement to send push to users without an email address this is possible via API only, please talk to your account manager about our CPaaS APIs. ## You need to embed our App Messaging SDK into your app Our **App Messaging - Foundation SDK** will need to be embedded in your app to enable us to register users as contacts in Engagement Cloud, and acquire the necessary push tokens automatically from your app in order for you to push to the users device. Your app will pass our SDK a security token, which it validates, to register a user. The security token needs to be in the JWT format [(JSON Web Token)](https://jwt.io/). The following diagram illustrates the SDKs use: [block:image] { "images": [ { "image": [ "https://files.readme.io/5fe9180-Push_channel_-_app_diagram.PNG", "Push channel - app diagram.PNG", 1166, 680, "#f1f3f0" ] } ] } [/block] ## You will need your mobile developers to help you configure push In order for Engagement Cloud to send push messages via Apple or Google you must first push enable your app, which is usually done by your mobile development team in the app admin portals for Google and Apple. Once configured the team will need to configure various identifiers, certificates and tokens into Engagement Cloud in order to enable us to push to your app. We strongly recommend having your mobile development team assist your with this configuration. [block:api-header] { "title": "Setting Up Push Notifications" } [/block] To [send push notifications from Engagement Cloud to your app](https://support.dotdigital.com/hc/en-gb/articles/360001827870), you need to do the following to link Engagement Cloud to your app and users: [block:image] { "images": [ { "image": [ "https://files.readme.io/5ac7c6a-push-steps.PNG", "push-steps.PNG", 980, 175, "#5ebb6a" ], "caption": "Enabling Engagement Cloud to push to your app" } ] } [/block] These steps ensure that Engagement Cloud has the necessary information to use Apple and Googles push channels to reach your app, and that the app passes the necessary information to send push to individual app users. The steps are: ## Create a push notification profile In this step you will configure Engagement Cloud to be able to use Google's FCM and Apples APNS push services to send messages to your apps. This involves configuring tokens and certificates that are issued for Apple and Googles platforms when configuring push for your app, so it is recommended that you have someone will mobile development knowledge available to complete this step. In addition to the push platform configuration we also need you to configure your security token values so that our SDK can recognise authenticate security tokens (JWTs) passed by your app to the SDK. Don't worry we explain how we use security tokens in more detail later. To complete this step [complete these instructions by clicking here.](doc:creating-a-push-notification-profile-new) ## Embed our SDK in your app Now that Engagement Cloud knows how to use push with your app it is time to embed our SDK into your app so that it can pass back the necessary information to send messages to a specific user. The SDK will communicate with our platform for you to: * Register your app users into Engagement Cloud as contacts * Collect the necessary push tokens from the users device to allow pushes to be sent We need to ensure that it is your app registering users for push and this is done by your app passing a JWT [(JSON Web Token)](https://jwt.io/) to the SDK. The passed JWT is verified using the authorisation information for the JWT you configured in your *push notification profile* in the previous step, and if valid the user is registered. Your app will need to provide a valid JWT to initialise the SDK, you can [find out more about how to create a JWT by clicking here.](doc:creating-a-json-web-token-new) To complete this step select the links below for the technologies used to build your app: * [Native Android Apps](doc:android-sdk-new) * [Native iOS Apps](doc:ios-sdk-new) * [Hybrid Javascript based Apps (Cordova)](doc:javascript-sdk-new) [block:callout] { "type": "info", "title": "Supported iOS and Android versions", "body": "Our mobile SDKs support the latest versions of Android and iOS, as well as the previous two versions." } [/block] ## Pass app user information to the SDK Engagement Cloud requires you to pass the SDK an unique email address per user in order for it to create / update a contact, so that you can target these contacts for push sends. Once the user is registered after passing a valid JWT all your app needs to do is update the SDKs user profile with an email address and a contact will automatically be created in Engagement Cloud to allow you to push to this specific app user. [Click here to find out now to implement this in your app](doc:registering-your-app-users-for-push) [block:callout] { "type": "success", "title": "Done", "body": "If you have followed all the steps above you should now see your app users appearing as contacts in Engagement Cloud, and you can use program builder to send them push notifications!" } [/block]