Push notifications can be sent from Dotdigital but only to users who have had a push profile linked to them. The way an 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 will create a contact using the email address and link it to the push profile automatically.

We will explain how you register an email address using the SDK in this section.

🚧

Ask users to enter their email address

Ideally 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 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 with the push profile id it is associated with, 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.

Push Profiles

The SDK has a concept of a profile which is used to represent the app user, which is created after the SDK is initialized and a session is started. It is at this point where the SDK will ask 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 will be used for the push profile id, as explained here

Sessions

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:

client.service().session().endSession(
   new Callback<ComapiResult<Void>>(){/* implement */});

client.services.session.endSession();

sdk.session.endSession();

🚧

Does your app support switching users?

To avoid the same push profile being attached to multiple contacts in Dotdigital it is important to ensure your 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 initialized 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 */ });

[client.services.session startSessionWithCompletion:^{
  // session successfully created
} failure:^(NSError * _Nullable error) {
  // error ocurred
}];

COMAPI.Foundation.initialise(comapiConfig)
    .then(function (sdk) {
        console.log("Foundation interface created", sdk);
    })
    .catch(function (error) {
        $log.error("paragonService: failed to initialise", error);
    });

2. 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>>>() {
    @Override
    public void success(ComapiResult<Map<String, Object>> result) {	
      @Override
      public void error(Throwable t) {
        //Error
      }
    }
  }
}

[client.services.profile getProfileForProfileID:@"<PROFILE-ID>" completion:^(CMPResult<CMPProfile *> * result) {
    if (result.error) {
        // error occurred
    } else {
        // success
    }
}];

sdk.services.profile.getMyProfile()
    .then(function (profile) {
			// Use the profile
    })
    .catch(function (error) {
        console.error("getMyProfile() failed", error);
    });

3. When you have the user's profile data, add an email address to it and patch the profile.

📘

eTags

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>>>() { }

[client.services.profile patchProfileForProfileID:@"<PROFILE-ID>" attributes:@{@"email" : @"[email protected]"} eTag:result.eTag completion:^(CMPResult<CMPProfile *> * result) {
    if (result.error) {
        // error occurred
    } else {
        // success
    }
}];

sdk.services.profile.getMyProfile()
    .then(function (profile) {
  			profile.email = "[email protected]";
        sdk.services.profile.updateMyProfile(profile);
    })
    .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 will remain empty and they will not be able to 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

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 the Dotdigital portal. To do this do the following:

1. Log into the Dotdigital portal
2. Select the Email option from the left hand section menu
3. Select Contacts -> All contacts from the top menu
4. Search for the contact your have registered using the email address you registered
5. Select the Devices tab, and you should see the following...

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. Note, 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 you app code.

Common issues

No device details showing for a contact

Please 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 contacts 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. Note, 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 you app code. See:
  • for iOS
  • for Android
  • for JavaScript
• the push profile has valid 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