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
orhash
are passed. - The
hash
parameter does not match the hash generated from theid
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 theid
andtimestamp
parameter and the shared secret.