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 Hurdle 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.

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.

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.hurdle.bio/users/v1/tokens/public with the following body:

{
  "partnerUserId": "123", 
  "email": "[email protected]"
  "firstName": "Joe",
  "lastName": "Smith",
  "sex": "m",
  "dateOfBirth": "1992-03-26"
}

📘

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). firstName, lastName, sex, and dateOfBirth are optional fields to include in API request, 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).

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"
}

Pages that can be embedded

• Test registration
  • https://app.hurdle.bio/register?partnerCode=...&publicToken=...
  • Embedding this allows users to register their test through a white-labelled experience hosted on your own domain without needing to create or login to a Hurdle account.
• Test results dashboard
  • https://app.hurdle.bio/?partnerCode=...&publicToken=...
  • Embedding this allows users to view their test results through a white-labelled experience hosted on your own domain without needing to login to their Hurdle account.

Embedding the Hurdle 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 Hurdle URL is the same, but contains the extra parameter for the token. For example: app.hurdle.bio/register?partnerCode=healthCompany&publicToken=ALONGTOKEN, or if you already know the kit ID, app.hurdle.bio/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)

Search parameters

Here is a list of search parameters that allow customisation of the user flow:

• partnerCode
  • e.g. partnerCode=test
• publicToken
  • e.g. app.hurdle.bio/register?publicToken=ALONGTOKEN
  • this is a token generated by the Users API to identify users without logging in on our side. This is explained more in depth in Linking user accounts.
• kitId
  • e.g. app.hurdle.bio/register?kitId=ABC00012345
  • allows to skip the first step of the registration flow, in which a kit Id is asked for. For certain products, this can be used in tandem with the white-labelling of the physical product box, so that there is a QR code on the box taking the user to your URL with the kit Id already pre-populated (speak to you account manager about this).
• hideFooter
  • used in combination with partnerCode, hides the Hurdle footer
  • e.g. app.hurdle.bio/register?hideFooter=true
• hideHeader
  • used in combination with partnerCode, hides the Hurdle header entirely or the header logo on pages where the user is logged in
  • e.g. app.hurdle.bio/register?hideHeader=true

These parameters can be combined to achieve the desired user experience.

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.hurdle.bio"){
    // Close the iframe
  }
}, false);