A tutorial for setting up your app to receive push notifications from the Program Builder in Dotdigital
Understanding mobile Push in Dotdigital
Dotdigital has the capability to send mobile push notifications to your app users using either our Program Builder or our omnichannel messaging API. We support sending push messages with optional deep links, URLs or custom data, this allows you to leverage any built in functionality of your app directly from a user tapping a push message.
Deep linking and custom data with push messages
Your app must be written support deep links or understand custom data payloads sent via a push, we simply deliver the link URL or custom data, the app must interpret them.
It is important before we go over the steps on how to enable the push channel in Dotdigital that some key concepts are understood, and these are:
Users are addressed using email addresses
Dotdigital requires all users you want to send push notifications to have an email address, as this is used to create a contact in Dotdigital, 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.
Your push audience is discovered
Unlike channels such as email or SMS it is not possible to import data to make contacts in Dotdigital push contactable. Your push audience is discovered as your users/customers open your app with the App Messaging SDK integrated into it, as it passes to Dotdigital the necessary push tokens and email address to send a push message.
When a contact is push contactable the PUSHOPTIN_xxx data field will be populated, otherwise it will be blank.
Do not tamper with the PUSHOPTIN field
The PUSHOPTIN_xxx data field is automatically managed by the platform and should not be altered or populated manually, as this will cause issues with push messaging.
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 Dotdigital, 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).
The following diagram illustrates the SDKs use:
You will need your mobile developers to help you configure push
In order for Dotdigital 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 Dotdigital in order to enable us to push to your app.
We strongly recommend having your mobile development team assist your with this configuration.
Setting Up Push Notifications
To send push notifications from Dotdigital to your app, you need to do the following to link Dotdigital to your app and users:
These steps ensure that Dotdigital 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 Dotdigital 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.
Embed our SDK in your app
Now that Dotdigital 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 Dotdigital 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) 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.
To complete this step select the links below for the technologies used to build your app:
Supported iOS and Android versions
Our mobile SDKs support the latest versions of Android and iOS, as well as the previous two versions.
Pass app user information to the SDK
Dotdigital 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 Dotdigital to allow you to push to this specific app user.
Click here to find out now to implement this in your app
If you have followed all the steps above you should now see your app users appearing as contacts in Dotdigital, and you can use program builder or the omnichannel API to send them push notifications!