Overview

Trackable links are a way of embedding Coassemble courses into an existing platform or website while maintaining the ability to track learner progress and results.

They work similarly to preview links but will accept query parameters that will setup tracking of the learner’s progress.

How to use trackable links

You can get a trackable link by logging into Coassemble and opening the Share modal for the course you want to embed. You can also use the API to create and fetch trackable links for your courses.

To enable tracking for a trackable link, you must pass an id query parameter to the link:

https://{YOUR_HOSTNAME}.coassemble.com/enter/{TRACKABLE_LINK_KEY}?id={IDENTIFIER}

The id can be anything that is meaningful in your system—it could be user IDs, email addresses or names of users. It is important however that you choose something that is unique within your system.

If you do not pass an id the trackable link will still function but will not track the learner’s progress (that is, it will essentially function as a regular preview link).

Handling progress events (optional)

If you would like to handle progress events and are embedding the trackable link in an <iframe> you can do so by listening for postMessage events.

window.addEventListener('message', message => {
    if (message.origin !== YOUR_COASSEMBLE_DOMAIN) return;
    const payload = JSON.parse(message.data);
});

The format of the payload is as follows:

{
    "type": "course", // course, module
    "event": "completed", // progress, finished, completed
    "data": {
        "id": 123, // course id, module id
        "progress": 100, // progress percentage as an integer
        "completed": true, // is entity completed
        "finished": true, // is entity finished
    }
}

Alternatively, there is a report available for trackable links within the Coassemble platform or you can also use the API to fetch results for trackable links.

Securing your trackable links (optional)

Optionally, you may secure trackable links with a shared secret. You can enable this in the Share modal or pass it as a parameter when you create the trackable link via the API.

When enabled, you are required to pass a hash parameter along with the id:

https://{YOUR_HOSTNAME}.coassemble.com/enter/{TRACKABLE_LINK_KEY}?id={IDENTIFIER}&hash={HASH}

The hash parameter should be a hex digest of your id parameter encoded using HMAC-SHA256 and the shared secret. When a user loads the trackable link, the shared secret will be used to generate a hash of the id parameter in our system.

An error will be thrown in these cases:

• The trackable link has been secured but no id or hash are passed.
• The hash parameter does not match the hash generated from the id parameter and the shared secret.

Expiring your trackable links (optional)

Optionally with secured trackable links you may also pass a timestamp parameter. This is useful if you want to ensure that the link is only valid for a certain amount of time.

This should be a Unix timestamp in seconds. If you pass a timestamp, the hash will be generated using the id and timestamp parameters concatenated together with no spaces or delimiters. If you do not pass a timestamp, the hash will be generated using only the id parameter as above.

An error will be thrown in these cases:

• The timestamp parameter is not a valid Unix timestamp.
• The timestamp parameter is older than 30 minutes.
• The hash parameter does not match the hash generated from the id and timestamp parameter and the shared secret.