Push notifications can be sent only to registered profiles who have had a native push token linked to them. We will explain how you register a user profile using the SDK in this section.

Prerequisite knowledge

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

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 JWT for an app user 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();

Updating a profile

1. After you've initialized the SDK you can update the profile with any details you need. Before trying to access the app users profile 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 your additional details such as email 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);
    });

👍

Integrating the SDK

Now you understand the concepts of how to register a app users profile, update it and create sessions to communicate with them its time to integrate the SDK into your app. The following sections cover off the different platforms SDKs and how to integrate them.