Basic completion tracking

The H5P client is capable of sending a message to the server when the user has completed a content object. This includes the time when this occured, how long the content was open, the achieved score and the maximum score.
While technically this message is derived from a xAPI statement generated by the content types, it is not the same as xAPI and is a completely separate system that co-exists with xAPI and a potential LRS. You can enable completion tracking and xAPI tracking indepedently.
If you want to capture all xAPI statements, which allows you to have very detailed tracking, you either have to inject your own xAPI capturing JavaScript or use the xAPI capabilities of the H5PPlayerComponent in the webcomponent package) (or the corresponding functionality in the React package).
How it works
When the user presses "check", a xAPI statement indicating completion is generated by the content type (that supports it). The H5P client captures it and calls an AJAX route on the H5P server with basic information.
The H5P server saves the completion data in a special storage system. The server automatically deletes the data when the content object is deleted.
Limitations
While the storage classes support retrieving and deleting the completion data, there are no endpoints on the h5p-express package that implement this functionality. You have to implement these endpoints yourself.
Not all content types emit xAPI statements indicating completion and thus the tracking isn't fired.
Enabling completion tracking
Create an instance of IContentUserDataStorage. The recommended storage class for production is MongoContentUserDataStorage in the @lumieducation/h5p-mongos3 package. There's also a FileContentUserDataStorageClass in the @lumieducation/h5p-server package that you can use for development or testing purposes.
Pass the implementation of IContentUserDataStorage into the H5PEditor and H5PPlayer constructor.
Set setFinishedEnabled in IH5PConfig to true.
If you use h5pAjaxExpressRouter from the @lumieducation/h5p-express package, then the routes for the AJAX endpoint are automatically created. You can manually turn them on by setting routeFinishedData in the options when creating the route.
If you don't use h5pAjaxExpressRouter, you have to route everything manually. First get ContentUserDataManager from H5PEditor or H5PPlayer. Route this endpoint and return HTTP status code 200 with a JSON object that is based on AjaxSuccessResponse with empty payload:
POST {{setFinishedUrl}}/ -> ContentUserDataManager.setFinished
Configuration options
You can customize the URL to which the AJAX calls are made by setting setFinishedUrl in IH5PConfig.
You can enable or disable the feature by setting setFinishedEnabled in IH5PConfig.
Security considerations
You should implement CSRF tokens when using completion tracking as the POST endpoint would otherwise by vulnerable to CSRF attacks when using cookie authentication. The tokens are added to the endpoint URL in the IUrlGenerator implementation and thus sent to the server whenever a POST call is made. Check out the REST example on how to pass the CSRF token to the H5P server components and how to check its validity.
User content state
Localization
Last modified 11mo ago