doctorlink

Members

Introduction

A feature of the Traversal Engine that may be important to end-users is that it's anonymous. However, as a client, using your own backend or utilising our in-built Members API you can create a permanent record that your users can come back to and update over time. This allows for a more usable experience by silently answering questions for the user that they already have data for. Meaning, the user sees less questions and isn't pestered by anything repetitive.

Setup

A member profile can be achieved because certain data points within an algorithm are marked as permanent. If you're using the Engine anonymously, you can call for your current traversal's permanent history once it's complete, and patch it with any data you've already saved for that user. You may then pass any permanent history into the "Start" method using Injected History.

However, if you use our in-built member service, as long as you started the product with a MemberReference, this process is automatic.

Create Member

In order to start a product with a memberReference one must first Create the member.

curl ".../api/v2/{CLIENT_ID}/Members" \
  -X "POST" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" -d '{
    "memberReference": "MEMBER_REFERENCE"
}'

The response to this will be an object containing your CLIENT_ID, the original MEMBER_REFERENCE, an internal, unique memberId, and an array of traversalIds.

{
    clientId: string,
    memberReference: string,
    memberId: guid
    traversalIds: [
        guids
    ]
}

Every time the user starts a product, the traversalId of that traversal is added to the traversalIds array. This is a historical record of every product started. If your app has been built to cater for these, a user may look back over complete traversals, or finish incomplete traversals, based in these Ids.

Member Traversals

As well as saving the traversalId, the Engine saves a MemberTraversal object. This object contains pertinent information to the traversal itself, and is useful in showing to the user which traversals are already finished and which need to be completed.

To obtain all of this data, you may call the members/traversals endpoint:

curl ".../api/v2/{CLIENT_ID}/members/{MEMBER_REFERENCE}/traversals" \
  -X "POST" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" -d '{
    "memberReference": "MEMBER_REFERENCE"
}'

To retrieve individual traversal data, you can simply add the traversalId to the url:

curl ".../api/v2/{CLIENT_ID}/members/{MEMBER_REFERENCE}/traversals/{TRAVERSAL_ID}" \
  -X "POST" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" -d '{
    "memberReference": "MEMBER_REFERENCE"
}'

These endpoints return MemberTraversal data:

{
    traversalId: guid,
    memberRef: string,
    clientId: string,
    productId: string,
    productName: string,
    startAlgoId: int,
    versionId: int,
    started: datetime,
    completed: datetime?
}

Permanent History

If you're using our built-in member service, once traversals are complete two things happen: 1. the MemberTraversal is updated with a complete datetime; 2. the permanent history from this traversal is merged into the member's current permanent history for use next time.

Permanent history contains a small selection of pertinent information from the traversal:

[{
    assetId: int,
    answerId: int?,
    value: string,
    traversalId: guid,
    createdDate: datetime
}]

This data can be retreived using the relevant endpoint. However, this is usually unneccessary as the data is automatically used when a memberReference is supplied.

curl ".../api/v2/{CLIENT_ID}/members/{MEMBER_REFERENCE}/permanent-history" \
  -X "GET" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"'