dotdigital Engagement Cloud

The dotdigital Engagement Cloud developer hub

Official dotdigital Engagement Cloud APIs documentation

Registering your app users for push

Push notifications can be sent from Engagement Cloud only to users who have a profile that contains an email address. We will explain how you register an email address using the SDK.

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.

User Profiles

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

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 user id in the JWT's user id (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:

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

Updating the profile with the email address

  1. After you've initialised the SDK, you need to check whether the session was started
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, continue 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);
    });
  1. Use the getProfileId() method on the Session object, and pass the returned ID to the getProfile() method.

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

  • result.isSuccessful(): True if the HTTP status returned from the result.getCode() method is in the range 200..300

  • result.getResult(): Response data (profile data in a Map<String, Object> map)

  • result.getMessage(): HTTP status message

  • result.getErrorBody() Error details

  • result.getCode(): HTTP status code

  • result.getETag(): Version of the data

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.profile.getMyProfile()
    .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.

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.profile.getMyProfile()
    .then(function (profile) {
  			profile.email = "[email protected]";
        sdk.services.profile.updateMyProfile(profile);
    })
    .catch(function (error) {
        console.error("getMyProfile() failed", error);
    });

All done!

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

Updated about 13 hours ago

Registering your app users for push


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.