Registering your app users for push

Push notifications can be sent from Dotdigital ,but only to users who have had a push profile linked to them. The way a Dotdigital contact is linked to a push profile is by setting an email address on the push profile. When this is done, if the Dotdigital contact already exists using the email address, the push profile will be linked to it, otherwise we create a contact using the email address and link it to the push profile automatically.


Ask users to enter their email address

If you don't have an email address for your app user, you should ask users if they'd like to receive push notifications from you and prompt them to enter their email address.

Prerequisite knowledge

The following concepts are useful to understand when working with the SDK:

Your push audience is discovered

Unlike channels such as email or SMS, it's not possible to import data to make contacts in Dotdigital push contactable. Your push audience is discovered as your users or 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 is populated, otherwise this field is blank.


Do not edit or amend 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.

Push profiles

The SDK has a concept of a profile, used to represent the app user, which is created after the SDK is initialised and a session is started. It is at this point that the SDK asks your app for the JWT (JSON Web Token) that represents the app user, as explained in our Creating a JSON Web Token page. The sub claim from the JWT is used for the push profile id, as explained here


When a session is started, the JWT token is used to create the user's profile ID ('profileId' string). This profile ID remains the same until a session is stopped.

When a session is stopped and started again, a new JWT token is requested and used to create a profile. We recommend that your JWT always uses the same profile id for the same user in the JWT's sub claim so that you don't end up with any duplication of profiles.

A session is stopped in any of the following circumstances:

  • The user uninstalls the app, and then reinstalls it
  • The user clears all of the app's data

You can also stop a session by calling the endSession() method, but only do this if you are implementing a app user logout feature, because the ability to push to the device is lost when the session is stopped:

   new Callback<ComapiResult<Void>>(){/* implement */});;


Does your app support switching users?

To avoid the same push profile being attached to multiple contacts in Dotdigital it's important to ensure you stop the session whenever a user logs out of your app. Then when a new user logs in you can ensure a session with a push profile for the new user is used.

Updating the profile with the email address

  1. After you've initialised the SDK and before you can update the profile with an email address, you need to check whether a session has been started; the code to do this is:
if(client.getSession() != null && client.getSession().isSuccessfullyCreated()) {/*Implement*/}
BOOL isSuccessfullyCreated = [client isSessionSuccessfullyCreated];

If the session hasn't been started, start it by calling the startSession() method then continue to step 2. Otherwise, skip to step 2.

client.service().session().startSession(new Callback<Session>() { /*Implement */ });
[ startSessionWithCompletion:^{
  // session successfully created
} failure:^(NSError * _Nullable error) {
  // error ocurred
    .then(function (sdk) {
        console.log("Foundation interface created", sdk);
    .catch(function (error) {
        $log.error("paragonService: failed to initialise", error);
  1. Use the getProfileId() method on the Session object to retrieve the app users profile id, and then pass the profile id to the getProfile() method to retrieve the full profile.

The getProfile() method returns a ComapiResult<T> object with the following methods:

  • result.isSuccessful(): Indicates that the profile was retrieved or not

  • result.getResult(): The profile data

  • result.getETag(): Version of the data

  • result.getMessage(): HTTP status message

  • result.getErrorBody() Error details

  • result.getCode(): HTTP status code

if(client.getSession() != null && client.getSession().isSuccessfullyCreated()) {
  client.service().profile().getProfile(client.getSession().getProfileId(), new Callback<ComapiResult<Map<String, Object>>>() {
    public void success(ComapiResult<Map<String, Object>> result) {	
      public void error(Throwable t) {
[ getProfileForProfileID:@"<PROFILE-ID>" completion:^(CMPResult<CMPProfile *> * result) {
    if (result.error) {
        // error occurred
    } else {
        // success
    .then(function (profile) {
			// Use the profile
    .catch(function (error) {
        console.error("getMyProfile() failed", error);
  1. When you have the user's profile data, add an email address to it and patch the profile.



An eTag string contains data about the version of a resource and is returned from every service response.

When updating a profile, the eTag string is used to check that the profile hasn't already been updated before you update it.

When you use the patchMyProfile() method, you need to pass it the eTag, which is returned from the result of the getProfile() method.

public void success(ComapiResult<Map<String, Object>> result) {
  Map <String, Object> additionalMap = new HashMap<>();
  //Add the user's email address to the profile
  additionalMap.put("email", "[email protected]");
  client.service().profile().patchMyProfile(additionalMap, result.getETag(), new Callback<ComapiResult<Map<String, Object>>>() { }
[ patchProfileForProfileID:@"<PROFILE-ID>" attributes:@{@"email" : @"[email protected]"} eTag:result.eTag completion:^(CMPResult<CMPProfile *> * result) {
    if (result.error) {
        // error occurred
    } else {
        // success
    .then(function (profile) { = "[email protected]";;
    .catch(function (error) {
        console.error("getMyProfile() failed", error);


A push profile needs at least 1 valid device to be used for push

The push profile must have at least 1 device registered against it with an FCM or APNS token to be associated with an Dotdigital contact. If not the contacts PUSHOPTIN field remains empty and they cannot use the push channel.


All done!

Now, when a user launches your app, the user's profile data is sent to Dotdigital and (if that profile contains an email address that belongs to one of your contacts) that contact can now receive push notifications from Dotdigital :tada:

Checking a contacts device data

To verify that you have integrated the SDK correctly, and passed your user registration information correctly, you use the Devices tab when viewing a contact within Dotdigital. To do this:

  1. Log in to Dotdigital.
  2. Go to Audience > Contacts.
  3. Search for the contact using the email address you registered for them.
  4. Select the contact.
  5. Select the Devices tab.
The Devices tab when viewing a contact in Dotdigital

The Devices tab when viewing a contact in Dotdigital

A contact can have multiple devices registered to them, and when you push to a contact we send the push to all devices that have a valid push token. The push token can be seen in the device details on the right in the Registration ID field. If this is not present, then either the user has not allowed push permissions or you haven't registered the push token correctly with the SDK, so please check your app code.

Common issues

No device details showing for a contact

Check that you have registered an email address with the SDK as covered here, as it this email address that is used to link an instance of your app on a device to a contact in Dotdigital.

I have devices but I am not receiving pushes

The following two prerequisites are required in order to successfully send a push to a contact:

  1. They have 1 or more devices registered to them; check the contact's devices in the Devices tab as described above.
  2. At least one device has a valid push token. The push token can be seen in the device details on the right in the Registration ID field on the contacts Devices tab. If this is not present then either:
  • the user has not allowed push permissions
  • your app isn't registering the push token correctly with the SDK, so please check your app code. See:
  • the push profile has invalid APNS and/or FCM details configured; please check your settings again if you are not seeing push tokens registered but you believe your app code is correct.


Still having issues?

Please see the Push troubleshooting guide for more help