To setup the App Messaging channels you need to configure your authentication parameters so that we can recognize your app users, and if you want to use the native push channels, such as APNS and FCM, then follow the instructions below to do this:

Authentication Explained

App Messaging and Push are secured messaging channels and therefore requires you to authenticate users prior to them being able to use the channels. Authentication can be performed by any authentication server or service that can issue a JWT (JSON Web Token). There are plenty of authentication platforms available to use that can issue tokens for your authenticated users, or use your existing systems. More information on how to create a JWT can be found on this website.

There are two ways to ways to configure the authentication for App Messaging and they are:

Anonymous - Use JWTs that are self generated and simply contain a unique identifier for the user
Fully Authenticated - Configure the system to accept JWTs issued from an existing security system, so only authenticated and recognized users can use the channels.

Anonymous Authentication

App Messaging requires a JWT token in order to recognize users, but if you want to support anonymous users this is still possible by simply creating a unique user Id (such as a GUID) for them and issuing them a JWT. This process is sometimes referred to as self issued tokens.

There are two ways of creating a JWT for anonymous users, you can:

Use the Session API to create a JWT

This is a convenient way to create an anonymous user JWT, simply call the Session API to generate an anonymous JWT. You can pass a user id, which is unique per user or device, and a nonce to ensure the JWT is the one you requested.

Self Issued JWT

With this option you must create a valid JWT matching the settings you will enter into the configuration; you have total control of the user id and claims. There are plenty of code examples of how to create JWT online, and a lot of good information and code libraries can be found at the JWT home page.

Fully Authenticated

To configure Push / App Messaging to be fully authenticated utilizing your systems JWT tokens enter the values for your existing systems JWT tokens claims into the Push profile configuration, so that we can recognize and validate the JWTs for your users.

The claims and details required are as follows:

Field	Description
Issuer	This should match the value of the iss (issuer) claim in your JWT. It is used to identify the principal that issued the JWT. The iss value is a case-sensitive string containing a unique string or a URL.
Audience	This should match the value of the aud (audience) claim in your JWT.
Shared secret	This is the secret used to create your signature for your JWT so we can ensure it has not been tampered with before accepting it.
ID Claim	This is the name of the claim in your JWT that should be used to identify a user, the sub claim is usually used. This will be mapped to the Id field for a users profile.

Configuring Push / App Messaging

A push notification profile is a way to let Dotdigital know how to communicate with your app via Apple's APNS and Google's FCM push systems, as well as how to authorize a user for push.

You can have only one profile, which can be set up to send push notifications to both Android and iOS devices.

To setup your push notification profile please do the following steps:

Log into Dotdigital
Click the icon in the bottom right, and go to Channel management > Push Notification and then click the New profile button
Click in the text box under New profile and enter the name of your app
In the Authentication section, either make a note of the values for each field or update them to match your existing systems JWT values as desired. See the Authentication section above for more details.

Now you need to configure you apps push systems. Depending on the operating systems that your app was built for enter your FCM credentials and/or enter your APNS credentials and return back here after to complete the setup
Click Save
You will now have a value in the API Space Id field, which you'll need to initialize the SDK, so note this down for the development team.

Entering your FCM credentials in Dotdigital

Our Android SDK uses Firebase Cloud Messaging (FCM) to send push notifications to your Android app users. Therefore, you need to give us some details about your Firebase project.

You need to have the Firebase console open.

If you don't have a Firebase project, create one.

In the Firebase console, click the cog icon and go to Project settings

In the General tab, copy your package name and paste it into the 'Name' field in Dotdigital

📘
Don't see your package name?
If you don't see your package name in the General tab, you need to click Add Firebase to your Android app.
Complete only steps 1 and 2 (register your app, and download your config file).

In the Cloud Messaging tab, copy your server key and paste it into the 'Server key' field in Dotdigital

Entering your APNS credentials in Dotdigital

Our iOS SDK uses the Apple Push Notification Service (APNS) to send push notifications to your contacts. Therefore, you need to configure your APNS token details in order for us to send pushes to your app. dotdigital utilises the APNS tokens rather than APNS Certificates, as the tokens do not expire annually. Instructions for creating an APNS token in the Apple Developer Portal can be found here.

You need to have your Apple Developer Portal open.

If you don't have an app ID that has the 'Push Notifications' service enabled, create one.

In your Apple Developer Portal, create a new certificate of type Apple Push Notification Service SSL (Sandbox and Production) and upload that certificate to the 'Private key' field on your Dotdigital profile page
In the 'Key ID' field in Dotdigital, enter the value of your private key's ID
In the 'Team ID' field in Dotdigital, enter the value of your team ID

Finding your API space ID

The API space ID is used to initialise our mobile SDKs.

This ID is displayed at the bottom of your push notification profile page as shown below:

👍
Complete
Now you have configured the App Messaging channels you need to integrate the App Messaging SDK into your app(s), so that you can test you settings.