{"id":21065612,"url":"https://github.com/adaptlearning/adapt-contrib-xapi","last_synced_at":"2025-09-07T23:31:26.571Z","repository":{"id":3362688,"uuid":"44191124","full_name":"adaptlearning/adapt-contrib-xapi","owner":"adaptlearning","description":"TinCan/xAPI extension for the Adapt Framework ","archived":false,"fork":false,"pushed_at":"2024-07-01T09:58:52.000Z","size":479,"stargazers_count":12,"open_issues_count":6,"forks_count":28,"subscribers_count":28,"default_branch":"master","last_synced_at":"2024-09-19T03:38:45.047Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adaptlearning.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-10-13T16:53:09.000Z","updated_at":"2024-07-01T09:58:54.000Z","dependencies_parsed_at":"2024-06-12T17:13:32.870Z","dependency_job_id":"7e50c416-e2ff-43ed-875a-5e9356b7047c","html_url":"https://github.com/adaptlearning/adapt-contrib-xapi","commit_stats":{"total_commits":180,"total_committers":23,"mean_commits":7.826086956521739,"dds":0.6888888888888889,"last_synced_commit":"154473dc6ea99dfba3592e59dc03e5799f3ea019"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adaptlearning%2Fadapt-contrib-xapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adaptlearning%2Fadapt-contrib-xapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adaptlearning%2Fadapt-contrib-xapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adaptlearning%2Fadapt-contrib-xapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adaptlearning","download_url":"https://codeload.github.com/adaptlearning/adapt-contrib-xapi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232262319,"owners_count":18496432,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-19T17:55:48.509Z","updated_at":"2025-01-02T22:09:15.450Z","avatar_url":"https://github.com/adaptlearning.png","language":"JavaScript","readme":"# adapt-contrib-xapi\n\n**xAPI** is an *extension* intended for use with the [Adapt framework](https://github.com/adaptlearning/adapt_framework) version 3.0 or greater to pass Experience API (xAPI) statements between the Adapt content and a Learning Record Store (LRS), such as [Learning Locker®](https://learninglocker.net/).  It is compatible with both the Adapt Framework and the Adapt Authoring Tool.\n\nFrom this point on, the README assumes a certain level of familiarity with the xAPI and the philosophy behind it.  If the xAPI specification is new to you, please start with the documentation at [xapi.com](https://xapi.com/overview/) before continuing.\n\n## Configuration\nSome setup is required in order to configure the xAPI extension.  If using a standalone Adapt Framework, refer to  [example.json](https://github.com/adaptlearning/adapt-contrib-xapi/blob/master/example.json) for a JSON snippet which should be added to your course's config.json.  If using the Authoring tool you can configure the following attributes:\n\n|Setting|Default|Help|\n|--|--|--|\n|Is Enabled|  `false` | Set to `true` to enable the extension\n| Specification | xAPI or cmi5 | This must be set. Specify xAPI or cmi5 for course compliance. |\n|Endpoint| | URL to the LRS endpoint\n|User (or Key)| | This can be configured in your LRS, or omit if using ADL Launch mechanism\n|Password (or Secret)| | (as above)\n|Verb language | `en-US`| Indicates the language of the verbs which will be passed to the LRS\n|Auto generate IDs for statements | `false` | It is recommended this is not enabled, so that the LRS will generate unique identifiers\n|Track state| `false` | Lets the LRS manage the course state via the State API\n|Use registration| `false` | Uses the `registration` parameter defined by the launch mechanism for calls to the State API\n|LRS connection failure behaviour | Show errors | Indicates what should happen when the course cannot connect to the LRS\n|Component blacklist | `blank,graphic` | A comma-separated list of components which should not send statements.  Set this to an empty string if all components should send a statement.\n\nBy default the xAPI extension listens for the following *core* events.  Those without an asterisk (*) can be toggled via configuration:\n\n| Object |Event  |\n|--|--|\n| Adapt | `tracking:complete`* |\n| Adapt | `router:page` |\n| Adapt | `router:menu` |\n| Adapt | `assessments:complete` |\n| Adapt | `questionView:recordInteraction` |\n| contentObjects |`change:_isComplete` |\n| articles | `change:_isComplete` |\n| blocks | `change:_isComplete` |\n| components | `change:_isComplete` |\n\n\n## Statements\nIn response to the course, the statements based on the following ADL verbs may be sent:\n- launched\n- initialized\n- attempted\n- failed\n- passed\n- completed\n- suspended\n- terminated\n\nIn response to activity on navigating via pages and menus:\n- experienced\n\nIn response to completion of non-question components, blocks, articles or contentObjects:\n- completed\n\nIn response to completion of question components, along with details of the interaction the following verb will be sent:\n- answered\n\nNote that the xAPI extension works well with the core Assessment extension.  The Assessment is responsible for defining pass or fail criteria, while the xAPI extension merely reports on it.\n\n## Events\nThe following events are triggered by the xAPI extension:\n\n| Event | Description | Parameter(s) |\n|--|--|--|\n|`xapi:lrs:initialize:error`|Triggered when the plugin fails to initialize| An `error` object|\n|`xapi:lrs:initialize:success`|Triggered when the plugin successfully establishes connectivity with the LRS | - |\n|`xapi:preSendStatement`|Triggered just prior to sending a single statement to the LRS | The `statement` as an object |\n|`xapi:lrs:sendStatement:error` | Triggered on an error with sending a statement to the LRS | The `error` object |\n|`xapi:lrs:sendStatement:success` | Triggered when a statement is successfully sent to the LRS | - |\n|`xapi:preSendStatements`| Triggered just prior to sending multiple statements ot the LRS | An array of `statement` objects |\n|`xapi:lrs:sendState:error`| Triggered when state cannot be saved to the LRS | The `error` object |\n|`xapi:lrs:sendState:success`| Triggered when state is successfully saved to the LRS | An object representing `newState` |\n|`xapi:stateLoaded`| Triggered when state has been successfully loaded from the LRS | - |\n\n## Attachments\nAttachments can be added by plugins, by listening for the `xapi:preSendStatement` event. The statement is passed to the callback and can be augmented with an `attachments` array, where each item is an object with the following properties:\n\n**type** (object): The attachment's metadata, which contains values for **contentType**, **usageType**, **display** and **description**.\n\n\u003e**contentType** (string): The mime type of the attachment e.g. `\"application/pdf\"`.\n\n\u003e**usageType** (string): A URI (IRI) to describe why the file is being attached.\n\n\u003e**display** (string): A language map giving a readable name for the attachment.\n\n\u003e\u003e**[language]** (string): A readable name for the attachment.\n\n\u003e**description** (string): [optional] A language map similar to **display** but giving a more detailed description of the purpose of the attachment or other information about it.\n\n\u003e\u003e**[language]** (string): A readable description for the attachment.\n\nThe attachment object *must* contain either a **value** or a **url** property.\n\n**value** (string): The correctly encoded string value of the attachment\n\n**url** (string): The url of the file to be attached. **adapt-contrib-xapi** will handle the string encoding.\n\n#### Example implementation:\n\nThe following example attaches a certificate to the course completion statement\n\n```\nAdapt.on('xapi:preSendStatement', function(statement) {\n  // Only handle course completion\n  if (statement.object.definition.type !== ADL.activityTypes.course\n    || !(statement.verb.id === ADL.verbs.completed.id \u0026\u0026 statement.result.completion)) {\n    return;\n  }\n\n  var attachment = {\n    type: {\n      contentType: 'application/pdf',\n      usageType: 'http://id.tincanapi.com/attachment/certificate-of-completion',\n      display: {\n        'en-US': 'Completion of course: ' + Adapt.course.get('title');\n      }\n    },\n    value: '{{fileContentsAsString}}'\n  };\n\n   statement.attachments = [attachment];\n});\n```\n\n----------------------------\n\n**Version number:**  1.0.1   \u003ca href=\"https://community.adaptlearning.org/\" target=\"_blank\"\u003e\u003cimg src=\"https://github.com/adaptlearning/documentation/blob/master/04_wiki_assets/plug-ins/images/adapt-logo-mrgn-lft.jpg\" alt=\"adapt learning logo\" align=\"right\"\u003e\u003c/a\u003e\n**Framework versions:** 5.19.1+\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadaptlearning%2Fadapt-contrib-xapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadaptlearning%2Fadapt-contrib-xapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadaptlearning%2Fadapt-contrib-xapi/lists"}