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

You can the Embedding User Flows the registration or results dashboard by passing the publicToken parameter, set to what you received from the API.

<iframe src="https://app.hurdle.bio/register?publicTokeneyJhbGciOiJkaXIiLC..."></iframe>

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);