Getting Started with xAPI

xAPI Statement Structure

Below is an example statement that shows how we structure our xAPI statements:

Copy

	{
		"id": STATEMENT_ID,
		"verb": { "id": "http://adlnet.gov/expapi/verbs/completed" },
		"actor": ACTOR_IDENTIFICATION,
		"object": {
			"id": OBJECT_ID,
			"definition": { "type": "http://adlnet.gov/expapi/activities/course" }
		},
		"timestamp": "2022-08-26T09:14:32.577Z"
	}

  • STATEMENT_ID refers to the unique uuid given to the statement.
  • OBJECT_ID refers to the course uuid or course URI that the user completed.
  • ACTOR_IDENTIFICATION refers to the method used to identifiy a user. We support email or SSO identifiers for identification based on your providers preferences, and below are an example of how they are structured within the statement:
    • Email Structure: "actor": { "mbox": "mailto:[email protected]" }
    • SSO Identifier Structure: "actor": { "account": { "name": "example-sso-identifier" } }

Please note that at the moment we only support the completed verb.



Setting up a new xAPI Integration

  1. In order to add a new xAPI integration, navigate to the xAPI Portal page, and enter in your api key. For API Key information and best practices please refer to this page.
  2. Click the Add button on the top right of the table, a modal will then open.
  3. Fill out the required information in the modal.

    • Name: A custom name for your xAPI integration.
    • Provider: Determines which provider the integration will use. (Note that we only allow one integration per provider). Providers are responsible for setting the actor and object values that are sent over via the xAPI.
    • Technical Emails: The email(s) where notifications will be sent regarding the integration. To use multiple emails, seperate the emails with a comma: [email protected], [email protected]
    • Statement URL: The URL where the xAPI statements will be sent to.
    • Authentication URL: The URL to retrieve an access token.
    • Client ID: The client ID to retrieve an access token.
    • Client Secret: The client password to retrieve an access token.
    • Status: Determines whether your integration is active or not. If integration is set to Disabled, xAPI statements will NOT be sent to your statement URL.

  4. Click the Add Integration button. Your xAPI integration is now running.


Editing and Deleting xAPI Integrations

  1. To edit your integration, click on the pen icon at the end of a table row. A modal will open that contains the information about the integration. Make your changes and then click Edit Integration. Please note, previous client credentials will be used if none are provided.
  2. To delete an integration, click on the trashcan icon at the end of a table row. A confirmation modal will apear. Click Delete.


Troubleshooting

Possible Errors

  • Invalid Credentials (Client Id, Client Secret or Authentication URL may be incorrect).: This error indicates that the integration was unable to fetch an access token. Be sure that the Client Id, Client Secret and Authentication URL are all correct.
  • Error via email.: If an error occurs in your integration, we will relay the error provided by your server/LRS to your technical contacts.


Error Handling Policy

5xx Errors

  • In the event of any 5xx errors, we will continue to retry sending one xAPI statement every 60 seconds until either statement was successfully sent, or the integration was deleted/disabled. Once a statement is successfully sent, we will send back any xAPI statements that we have in our queue that were not able to be sent due to a 5xx error.

    For example, if your server/LRS was down for maintence, we will keep a queue of all xAPI statements that were not able to be sent over due to a 5xx error. Once your server is back online, we will send all of the statements in our queue to your statement URL.



4xx Errors

  • In the event of any 4xx errors, we will not continue to retry sending xAPI statements affected by 4xx errors until integration has been updated.

    For example, if your client credentials somehow became stale and unable to retrieve an access token, this would create a 4xx error when we would try to send the statement. We will alert you of this error, and once we detect that your credentials have been updated in your integration, we will attempt to send back any xAPI statement that were not able to be sent to your statement URL due to a 4xx error. You can update your integration on the xAPI Portal page.



Notification Policy

  • In the event of any 4xx or 5xx errors, we will alert the technical contacts in the integration via email. To avoid spam, we will only send up to one email per 24 hours if an error occurs.


Test your xAPI Integration

  • Navigate to the section called Test your xAPI Integration. This tool allows you to send a fake xAPI statement to your integration, and also allows you to see the response message from the provider. This will test if we are able to successfully send an xAPI statement to your endpoint. If you need to customize the values in the fake statement, click on the Edit test xAPI statement values to edit. This tool should be used for testing and troubleshooting purposes only.