Linking user accounts

Seamlessly send logged-in users to Chronomics pages.

This page elaborates further on the concepts explained in White-label customisation. Please make sure you have read that first.

Why link user accounts?

By default, users going through a registration flow, whether it's branded as Chronomics or as your brand, will need to create an account and define a password. Similarly when accessing the results dashboard, they will need to log in with that account and password. This can be cumbersome and confusing for users if you are embedding those pages inside your own app. If that is the case, and users are already logged in inside your app, you can seamlessly link accounts and avoid that account creation/login step; you will be logging the user in with us, over API.

📘

This functionality can currently be used with the registration flow, but not the white-labeled results dashboard. This means you'll need to access results via API. We will be extending the functionality to cover the results dashboard in the future. Let us know if this is something you need!

How to link user accounts

In order to do this, all that is needed is a prior call to the Users API to generate a public token. That token is short-lived (it expires within an hour, effectively logging a user out) and contains user information that we use to create a user account on our side that is linked to the user account on your side. Because we trust the information you send us over that API, we don't need to ask the user to authenticate themselves. We will silently create an account if the user is new to us, and save the link to the user on our side. That link simply pairs the user's email address to the internal user ID on your side.

📘

Passing more information about the user

The base use case for the Users API endpoint is to simply pass the user ID on your side and the user's email. However, in some cases, it may be useful to share more information about the user, so that we can skip some questions during the test registration flow (such as date of birth, gender, and name). With some configuration on our side (ask your account manager) we can accept additional parameters in the same Users API call, and the extra information will be embedded in the token (we do not store that extra information to database, therefore it should be added to the Users API call every time it is necessary).

Finally, when the registration flow is complete, we can let you know this via DOM events so that you can close the window or popup in which the iframe was embedded.

The remainder of this page details each step more in detail.

Creating the public token

Call the Users API endpoint api.chronomics.com/users/v1/tokens/public with the following body:

{
  "partnerUserId": "123", 
  "email": "[email protected]"
}

The response body should be like this:

{
    "publicToken": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIn0..dSCpPLspF6KbfrPu.VUosZN5nJKHonFR8pvYLvHDphk_o_dVQLu9TS55AjhsIfdnYtyk_WI5mihYa5PP3apGb_sPXMxxVQQ-aViuAclaDp_DdLYA728d5w2p3iY8Xy_P_HnQmcaSUoAnMM2n_oU7LvB10jp9cHt67piXo0wGon28sodJyVM5xwB2GPFFj2cLSZo4TkYoWkkMv55Yysan12chjj_CQweL2dPgh8j1uDQJawWkvkiSpAx-IcAmd43VVly6B-wxIMPu73sy22_5f7tpbsIbHRb3wdC2jbxm7aM8nYrp2k_zn7juXBtox-jwrJxJDge0B8OcD22jW2lBznqtefpLjuhuO4Z9hGEyJwv0kxi3Swuq-ew.whDwOsaM5DNBEE3Jvj-vmg"
}

Embedding the Chronomics pages

This is similar to what is described in White-label customisation, with the iframe embedded in any way you like inside your own app (say, a popup on top of your app's dashboard). The Chronomics URL is the same, but contains the extra parameter for the token. For example: app.chronomics.com/register?partnerCode=healthCompany&publicToken=ALONGTOKEN, or if you already know the kit ID, app.chronomics.com/register?partnerCode=healthCompany&publicToken=ALONGTOKEN&kitId=ABC00012345.

(the URLs above use ALONGTOKEN for brevity and readability but this refers to the token returned in the previous step)

Detecting the completion of registration

Once the user completes the registration flow, a message will be published using window.postMessage(). In order to receive the published message, you need to add an event listener to the iframe's parent window. Upon receipt of the message, the iframe can be closed, and any appropriate further action can be taken.

window.addEventListener("message", (event) => {
  if (event.origin === "https://app.chronomics.com"){
    // Close the iframe
  }
}, false);