Predict Id Integration

The goal of the predict-id integration in Mobile Engage is to enable customers to use one way of identifying their contacts when using both mobile engage and predict but still be compatible with the existing profiles in predict which might be based on a different id (email-hash, external-id).

Summary

The customer will use integrate the mobile-engage authentication in their app and when linking to a contact the client-service will give back a contact-token containing the predict-id. The whole contact-token is passed to predict from the SDK, and predict will validate the token and extract the right id.

Known limitations

  • Since the linking a device to an identified contact is an asynchronous operation there is a period of time where contact-token does not contain the predict-id.

Terms

  • Contact-Token - A signed jwt-token given back from the client-service when linking on a device to a contact. The token will contain a contact-reference and may contain contact-id, predict-email-hash, predict-external-id as well as keyId. This token short lived and when it expires the SDK will create a new one using the contact-token endpoint in the client-service api.

  • Predict-Id - contact identifier used for predict. Can be either email-hash or external-id.

  • Contact-field-id - id of the field used in mobile engage when identifying a contact.

  • Contact-field-value - value of the field used in mobile engage when identifying a contact. This value must be set by the customer when importing/creating the contact into emarsys.

Signature Validation

The contact-token contains a signature that can be validated using a public key. The contact-token indicates which public key should be used with the keyId property. Typically this id would be the customer-id but if available the keyId should always be used to retrieve the public-key for validation.

Cases

Predict + Mobile Engage Standard Auth

  1. Customer initializes SDK with merchant-id, contact-field-id.

  2. On startup the SDK registers the client and links the device to an anonynmous contact.

  3. The user logs in, the contact-field-id is set and the SDK links the device to the identified contact using the contact endpoint including the merchant-id as a header in the request. A contact-token containing the contact-reference is returned which will expire after shorter period than normally since predict is used.

  4. The contact-token expires and a new one is created using the contact-token endpoint.

    1. When refreshing the contac-token we get back the contact-id. The contact-id is used to synchronously lookup the predict-id using the contact-resolver-api.

    2. This time the returned token will include contact-id and either predict-email-hash or predict-external-id. The expiry of the token is now like normal.

  5. The contact-token is included as a header in requests against predict and predict will extract the right predict id and validate the signature of the token.

Predict + Mobile Engage OpenID Auth

  1. Customer initializes SDK with merchant-id, contact-field-id.

  2. On startup the SDK registers the client and links the device to an anonynmous contact.

  3. The user logs in, the authenticated contact is set and the SDK links the device to the identified contact using the contact endpoint including the merchant-id as a header in the request. A contact-token containing the contact-reference is returned which will expire after shorter period than normally since predict is used.

  4. The contact-token expires and a new one is created using the contact-token endpoint. This time the returned token will include contact-id and either predict-email-hash or predict-external-id. The expiry of the token is now like normal.

  5. The contact-token is included as a header in requests against predict and predict will extract the right predict id and validate the signature of the token.

Predict-only

  1. Customer initializes SDK with merchant-id, contact-field-id.

  2. The user logs in, the contact-field-id is set and the SDK uses context-less contact-token endpoint to create a contact-token. A contact-token containing the contact-reference is returned which will expire after shorter period than normally since predict is used.

  3. The contact-token expires and a new one is created using the same endpoint.

    1. When refreshing the contact-token we get back the contact-id. The contact-id is used to synchronously lookup the predict-id using the contact-resolver-api.

    2. This time the returned token will include contact-id and either predict-email-hash or predict-external-id. The expiry of the token is now like normal.

  4. The contact-token is included as a header in requests against predict and predict will extract the right predict id and validate the signature of the token.