{"id":22446947,"url":"https://github.com/learnosity/learnosity-sdk-nodejs","last_synced_at":"2025-08-01T21:32:21.350Z","repository":{"id":12232870,"uuid":"161250854","full_name":"Learnosity/learnosity-sdk-nodejs","owner":"Learnosity","description":"Learnosity SDK for NodeJS","archived":false,"fork":false,"pushed_at":"2024-07-15T08:23:25.000Z","size":306,"stargazers_count":4,"open_issues_count":5,"forks_count":6,"subscribers_count":32,"default_branch":"master","last_synced_at":"2024-07-16T09:32:02.618Z","etag":null,"topics":["learnosity","nodejs","sdk"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Learnosity.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","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":"2018-12-10T23:39:48.000Z","updated_at":"2024-07-15T08:15:35.000Z","dependencies_parsed_at":"2024-07-15T09:26:36.054Z","dependency_job_id":null,"html_url":"https://github.com/Learnosity/learnosity-sdk-nodejs","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Learnosity%2Flearnosity-sdk-nodejs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Learnosity%2Flearnosity-sdk-nodejs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Learnosity%2Flearnosity-sdk-nodejs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Learnosity%2Flearnosity-sdk-nodejs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Learnosity","download_url":"https://codeload.github.com/Learnosity/learnosity-sdk-nodejs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228407877,"owners_count":17915083,"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":["learnosity","nodejs","sdk"],"created_at":"2024-12-06T04:13:09.637Z","updated_at":"2024-12-06T04:13:10.173Z","avatar_url":"https://github.com/Learnosity.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\u003cimg width=\"50%\" height=\"50%\" src=\"docs/images/image-logo-graphic.png\"\u003e\u003c/p\u003e\n\u003ch1 align=\"center\"\u003eLearnosity SDK - Node.js\u003c/h1\u003e\n\u003cp align=\"center\"\u003eEverything you need to start building your app in Learnosity, with Node.js and the JavaScript programming language.\u003cbr\u003e \n(Prefer another language? \u003ca href=\"https://help.learnosity.com/hc/en-us/sections/360000194318-Server-side-development-SDKs\"\u003eClick here\u003c/a\u003e)\u003cbr\u003e\nAn official Learnosity open-source project.\u003c/p\u003e\n\n[![Latest Stable Version](https://img.shields.io/github/tag/Learnosity/learnosity-sdk-nodejs.svg?label=stable)](https://github.com/Learnosity/learnosity-sdk-nodejs/releases)\n[![Build Status](https://app.travis-ci.com/Learnosity/learnosity-sdk-nodejs.svg?branch=master)](https://app.travis-ci.com/Learnosity/learnosity-sdk-nodejs)\n[![License](docs/images/apache-license.svg)](LICENSE.md)\n[![Downloads](docs/images/downloads.svg)](https://github.com/Learnosity/learnosity-sdk-nodejs/releases)\n---\n\n## Table of Contents\n\n* [Overview: what does it do?](#overview-what-does-it-do)\n* [Requirements](#requirements)\n* [Installation](#installation)\n* [Quick start guide](#quick-start-guide)\n* [Next steps: additional documentation](#next-steps-additional-documentation)\n* [Contributing to this project](#contributing-to-this-project)\n* [License](#license)\n* [Usage tracking](#usage-tracking)\n* [Further reading](#further-reading)\n\n## Overview: what does it do?\nThe Learnosity Node.js SDK makes it simple to interact with Learnosity APIs.\n\n![image-concept-overview.png](docs/images/image-concept-overview.png)\n\nIt provides a number of convenience features for developers, that make it simple to do the following essential tasks:\n* Creating signed security requests for API initialization, and\n* Interacting with the Data API.\n\nFor example, the SDK helps with creating a signed request for Learnosity:\n\n![image-signed-request-creation.png](docs/images/image-signed-request-creation.png)\n\nOnce the SDK has created the signed request for you, your app sends that on to an API in the Learnosity cloud, which then retrieves the assessment you are asking for, as seen in the diagram below:\n\n![image-assessment-retrieval.png](docs/images/image-assessment-retrieval.png)\n\nThis scenario is what you can see running in the Quick start guide example ([see below](#quick-start-guide)).\n\nThere's more features, besides. See the detailed list of SDK features on the [reference page](REFERENCE.md).\n\n[(Back to top)](#table-of-contents)\n\n## Requirements\n1. Runtime libraries for Node.js installed. ([instructions](https://nodejs.org/en/download/))\n\n2. To follow the tutorial on this page, also install some other libraries: \n* [Express.js](http://expressjs.com/), a minimal web framework, \n* The [EJS](https://ejs.co/) templating language, and \n* The [UUID](https://www.npmjs.com/package/uuid) library. These are not actually a requirement of the SDK itself, so if your app doesn't use these libraries, no need to install them. They are only required for the tutorial on this page.\n\nNot using Node.js? See the [SDKs for other languages](https://help.learnosity.com/hc/en-us/sections/360000194318-Server-side-development-SDKs).\n\n### Supported Node.js Versions\nThe Learnosity SDK - Node.js is verified against [Active LTS and Maintenance LTS releases of Node.js](https://nodejs.org/en/about/releases/).\n\n[(Back to top)](#table-of-contents)\n\n## Installation\n###  **Installation via NPM**\nUsing NPM is the recommended way to install the Learnosity SDK for Node.js in production. The easiest way is to run this from your parent project folder:\n\n\tnpm install https://github.com/Learnosity/learnosity-sdk-nodejs\n\nTo follow the tutorial on this page, also install some other libraries: \n* [Express.js](http://expressjs.com/), a minimal web framework, \n* The [EJS](https://ejs.co/) templating language, and \n* The [UUID](https://www.npmjs.com/package/uuid) library.\nInstall these by running the following commands from the root folder of the project.\n\n```\n    npm install express\n    npm install ejs\n    npm install uuid\n```\n\n*Note*: these additional libraries are not required by the Learnosity SDK. They are only required for the tutorial on this page.\n\n### **Alternative method 1: download the zip file**\nDownload the latest version of the SDK as a self-contained ZIP file from the [GitHub Releases](https://github.com/Learnosity/learnosity-sdk-nodejs/releases) page. The distribution ZIP file contains all the necessary dependencies. \n\nOne downloaded, run this command from the root folder to install dependencies:\n\n```\n    npm install\n```\n\nTo follow the tutorial on this page, also install some other libraries: \n* [Express.js](http://expressjs.com/), a minimal web framework, \n* The [EJS](https://ejs.co/) templating language, and \n* The [UUID](https://www.npmjs.com/package/uuid) library.\nInstall these by running the following commands from the root folder of the project.\n\n```\n    npm install express\n    npm install ejs\n    npm install uuid\n```\n\n*Note*: these additional libraries are not required by the Learnosity SDK. They are only required for the tutorial on this page.\n\n### **Alternative method 2: development install from a git clone**\nTo install from the terminal, run this command:\n\n    git clone git@github.com:Learnosity/learnosity-sdk-nodejs.git\n\nTo follow the tutorial on this page, also install some other libraries: \n* [Express.js](http://expressjs.com/), a minimal web framework, \n* The [EJS](https://ejs.co/) templating language, and \n* The [UUID](https://www.npmjs.com/package/uuid) library.\nInstall these by running the following commands from the root folder of the project.\n\n```\n    npm install express\n    npm install ejs\n    npm install uuid\n```\n\n*Note*: these additional libraries are not required by the Learnosity SDK. They are only required for the tutorial on this page.\n\nNote that these manual installation methods are for development and testing only.\nFor production use, you should install the SDK using the NPM package manager for Node.js, as described above.\n\n[(Back to top)](#table-of-contents)\n\n## Quick start guide\nLet's take a look at a simple example of the SDK in action. In this example, we'll load an assessment into the browser.\n\n### **Start up your web server and view the standalone assessment example**\nTo start up your Node.js web server, first find the following folder location under the SDK. Change directory ('cd') to this location on the command line.\n\n    .../learnosity-sdk-nodejs/docs/quickstart/assessment/\n\nTo start, run this command from that folder:\n\n```\nnpm run start-standalone-assessment\n\n```\n\nFrom this point on, we'll assume that your web server is available at this local address (it will report the port being used when you launch it, by default it is port 3000): \n\nhttp://localhost:3000/\n\nWhen you open this URL with your browser, the page will load. This is a basic example of an assessment loaded into a web page with Learnosity's assessment player. You can interact with this demo assessment to try out the various Question types.\n\n\u003cimg width=\"50%\" height=\"50%\" src=\"docs/images/image-quickstart-examples-assessment.png\"\u003e\n\n[(Back to top)](#table-of-contents)\n\n### **How it works**\nLet's walk through the code for this standalone assessment example. The source file is included under the quickstart folder, in this location:\n\n    .../learnosity-sdk-nodejs/docs/quickstart/assessment/standalone-assessment.js\n\nThe first section of code is JavaScript and is executed server-side. It constructs a set of configuration options for Items API, and securely signs them using the consumer key. The second section is HTML and JavaScript and is executed client-side, once the page is loaded in the browser. It renders and runs the assessment functionality.\n\n[(Back to top)](#table-of-contents)\n\n### **Server-side code**\nWe start by including the LearnositySDK constructor. This make it easy to generate and sign the config options.\n\n``` javascript\nconst Learnosity = require('../../../index'); // Learnosity SDK constructor\n```\n\nNext, we declare the Learnosity consumer credentials we'll use to authorize this request. We also construct security settings that ensure the report is initialized on the intended domain. The value provided to the domain property must match the domain from which the file is actually served. The consumer key and consumer secret in this example are for Learnosity's public \"demos\" account (loaded from the [config.js](docs/quickstart/config.js) file). Once Learnosity provides your own consumer credentials, your Item bank and assessment data will be tied to your own consumer key and secret.\n\n``` javascript\nconst config = require('../config'); // Load consumer key \u0026 secret\n```\n\n\u003ci\u003e(of course, you should never normally put passwords into version control)\u003c/i\u003e\n\nWe bring in the UUID library.\n\n``` javascript\nconst uuid = require('uuid');  // Load the UUID library\n```\n\nWe also specify a few libraries to run a minimal web server, \"Express.js\" for the purposes of this example.\n\n``` javascript\nconst express = require('express'); // Load Express.js web server \nvar app = express();                // Instantiate the web server\n```\n\nWe also choose EJS as the view engine, \n\n``` javascript\napp.set('view engine', 'ejs'); // Set EJS as the templating language\n```\n\nNow we set up the user_id, session_id (both UUID values), and domain configuration.\n\n``` javascript\nconst user_id = uuid.v4();    // Generate a UUID for the user ID\nconst session_id = uuid.v4(); // Generate a UUID for the session ID\nconst domain = 'localhost';   // Set the domain\n```\n\nNow we'll declare the Learnosity configuration options for Items API. These specify which assessment content should be rendered, how it should be displayed, which user is taking this assessment and how their responses should be stored. \n\n``` javascript\napp.get('/', function (req, res) { \n    const learnositySdk = new Learnosity(); // Instantiate the SDK\n    const request = learnositySdk.init(  // Set Learnosity init options\n        'items',                              // Select Items API\n        {\n            consumer_key: config.consumerKey,\n            domain: 'localhost',\n        },\n        config.consumerSecret,\n        {\n            user_id: user_id,\n            activity_template_id: 'quickstart_examples_activity_template_001',\n            session_id: session_id,\n            activity_id: \"quickstart_examples_activity_001\",\n            rendering_type: 'assess',\n            type: 'submit_practice',\n            name: \"Items API Quickstart\",\n            state: 'initial',\n            config: {\n                regions: 'main'\n            }\n        }\n    );\n```\n\n* `user_id`: unique student identifier. Note: we never send or save student's names or other personally identifiable information in these requests. The unique identifier should be used to look up the entry in a database of students accessible within your system only. [Learn more](https://help.learnosity.com/hc/en-us/articles/360002309578-Student-Privacy-and-Personally-Identifiable-Information-PII-).\n* `activity_template_id`: reference of the Activity to retrieve from the Item bank. The Activity defines which Items will be served in this assessment.\n* `session_id`: uniquely identifies this specific assessment attempt for save/resume, data retrieval and reporting purposes. Here, we're using the `Uuid` helper to auto-generate a unique session id.\n* `activity_id`: a string you define, used solely for analytics to allow you run reporting and compare results of users submitting the same assessment.\n* `rendering_type`: selects a rendering mode, `assess` mode is a \"standalone\" mode (loading a complete assessment player for navigation, as opposed to `inline` for embedding without).\n* `type`: selects the context for the student response storage. `submit_practice` mode means the student responses will be stored in the Learnosity cloud, allowing for grading and review.\n* `name`: human-friendly display name to be shown in reporting, via Reports API and Data API.\n* `state`: Optional. Can be set to `initial`, `resume` or `review`. `initial` is the default.\n\n**Note**: you can submit the configuration options either as an array as shown above, or a JSON string.\n\nIn the example above, we're calling LearnositySDK's `init()` constructor to construct our Items API configuration parameters, and signing them securely.\n\n[(Back to top)](#table-of-contents)\n\n### **Web page content**\nWe've got our set of signed configuration parameters, so now we can set up our page content for output. The page can be as simple or as complex as needed, using your own HTML, JavaScript and your frameworks of choice to render the desired product experience.\n\nThis example uses HTML in an EJS template, served by the Express.js web server. However, the template used here can be easily modified for use in another framework.\n\nThe following example HTML template can be found in the [standalone-assessment.ejs](docs/quickstart/views/standalone-assessment.ejs) file.\n\n``` html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003chead lang=\"en\"\u003e\n    \u003cmeta charset=\"UTF-8\"\u003e\n    \u003ctitle\u003eLearnosity SDK - NodeJS\u003c/title\u003e\n    \u003cscript src=\"//items.learnosity.com/?latest-lts\"\u003e\u003c/script\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n    \u003ch1\u003eStandalone Assessment Example\u003c/h1\u003e\n\u003cdiv id=\"learnosity_assess\"\u003e\u003c/div\u003e\n\u003cscript\u003e\n    const request = \u003c%- JSON.stringify(request) %\u003e;\n    const itemsApp = LearnosityItems.init(request, {\n        readyListener() {\n            console.log('ready');\n        },\n        errorListener(err) {\n            console.log('error', err);\n        }\n    })\n\u003c/script\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\nThe important parts to be aware of in this HTML are:\n\n* A div with `id=\"learnosity_assess\"`. This is where the Learnosity assessment player will be rendered to deliver the assessment.\n* The `\u003cscript src=\"https://items.learnosity.com/?latest-lts\"\u003e\u003c/script\u003e` tag, which includes Learnosity's Items API on the page and makes the global `LearnosityItems` object available. The version specified as `latest-lts` will retrieve the latest version supported. To know more about switching to a specific LTS version, visit our [Long Term Support (LTS) page](https://help.learnosity.com/hc/en-us/articles/360001268538-Release-Cadence-and-Version-Lifecycle). In production, you should always pin to a specific LTS version to ensure version compatibility.\n* The call to `LearnosityItems.init()`, which initiates Items API to inject the assessment player into the page.\n* The variable `request` dynamically sends the contents of our init options (Learnosity configuration) to JavaScript in the browser, so it can be passed to `init()`.\n\nThis marks the end of the quick start guide. From here, try modifying the example files yourself, you are welcome to use this code as a basis for your own projects. As mentioned earlier, the EJS template used here can be easily re-used in another framework.\n\nTake a look at some more in-depth options and tutorials on using Learnosity assessment functionality below.\n\n[(Back to top)](#table-of-contents)\n\n## Next steps: additional documentation\n\n### **SDK reference**\nSee a more detailed breakdown of all the SDK features, and examples of how to use more advanced or specialised features on the [SDK reference page](REFERENCE.md).\n\n### **Additional quick start guides**\nThere are more quick start guides, going beyond the initial quick start topic of loading an assessment, these further tutorials show how to set up authoring and analytics:\n* [Authoring Items quick start guide](https://help.learnosity.com/hc/en-us/articles/360000754958-Getting-Started-With-the-Author-API) (Author API) - create and edit new Questions and Items for your Item bank, then group your assessment Items into Activities, and\n* [Analytics / student reporting quick start guide](https://help.learnosity.com/hc/en-us/articles/360000755838-Getting-Started-With-the-Reports-API) (Reports API) - view the results and scores from an assessment Activity. \n\n### **Learnosity demos repository**\nOn our [demo site](https://demos.learnosity.com/), browse through many examples of Learnosity API integration. You can also download the entire demo site source code, the code for any single demo, or browse the codebase directly on GitHub.\n\n### **Learnosity reference documentation**\nSee full documentation for Learnosity API init options, methods and events in the [Learnosity reference site](https://reference.learnosity.com/).\n\n### **Technical use-cases documentation**\nFind guidance on how to select a development pattern and arrange the architecture of your application with Learnosity, in the [Technical Use-Cases Overview](https://help.learnosity.com/hc/en-us/articles/360000757777-Technical-Use-Cases-Overview).\n\n### **Deciding what to build or integrate**\nGet help deciding what application functionality to build yourself, or integrate off-the-shelf with the [Learnosity \"Golden Path\" documentation](https://help.learnosity.com/hc/en-us/articles/360000754578-Recommended-Deployment-Patterns-Golden-Path-).\n\n### **Key Learnosity concepts**\nWant more general information about how apps on Learnosity actually work? Take a look at our [Key Learnosity Concepts page](https://help.learnosity.com/hc/en-us/articles/360000754638-Key-Learnosity-Concepts).\n\n### **Glossary**\nNeed an explanation for the unique Learnosity meanings for Item, Activity and Item bank? See our [Glossary of Learnosity-specific terms](https://help.learnosity.com/hc/en-us/articles/360000754838-Glossary-of-Learnosity-and-Industry-Terms).\n\n[(Back to top)](#table-of-contents)\n\n## Contributing to this project\n\n### Adding new features or fixing bugs\nContributions are welcome. See the [contributing instructions](CONTRIBUTING.md) page for more information. You can also get in touch via our support team.\n\n[(Back to top)](#table-of-contents)\n\n## License\nThe Learnosity Node.js SDK is licensed under an Apache 2.0 license. [Read more](LICENSE.md).\n\n[(Back to top)](#table-of-contents)\n\n## Usage tracking\nOur SDKs include code to track the following information by adding it to the request being signed:\n- SDK version\n- SDK language\n- SDK language version\n- Host platform (OS)\n- Platform version\n\nWe use this data to enable better support and feature planning.\n\n[(Back to top)](#table-of-contents)\n\n## Further reading\nThanks for reading to the end! Find more information about developing an app with Learnosity on our documentation sites: \n\n* [help.learnosity.com](http://help.learnosity.com/hc/en-us) -- general help portal and tutorials,\n* [reference.learnosity.com](http://reference.learnosity.com) -- developer reference site, and\n* [authorguide.learnosity.com](http://authorguide.learnosity.com) -- authoring documentation for content creators.\n\n[(Back to top)](#table-of-contents)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flearnosity%2Flearnosity-sdk-nodejs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flearnosity%2Flearnosity-sdk-nodejs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flearnosity%2Flearnosity-sdk-nodejs/lists"}