Launching Courses

For your learners to take any of the courses that you've imported, you will have to launch the course through Engine. There are three main steps to launching a course:

  1. Create a registration in the course for the learner
  2. Get the launch URL for the registration
  3. Open the launch URL in an iframe or a new window

Let's look at each of these steps in more detail below.

Creating a Registration

Note: before you can create a registration, the course your learner needs to take must have already been imported into Engine. If it hasn't, you can refer to the Importing Courses section for more information on how to do that.

Once your course has been imported, you will be able to create a registration through the API by issuing a POST request to the /registrations resource. You will need to provide three required pieces of information in the body of your request:

  • courseId: the unique identifier that you specified when you imported your course
  • registrationId: a unique identifier for this registration that we're creating
  • learner: information about the person taking the course, specifically a unique id, their first name, and their last name.

Please see the Overview page for some more explanation about each of these pieces of information

Once you have a registration created, you can generate the launch link for it with a POST to the /registrations/{registrationId}/launchLink endpoint. This returns a URL to Engine's launch page with parameters specific to this registration.

When retrieving the launch link, you have some optional parameters that you can use to customize the behavior of the launch. You would pass these as properties of a JSON object in the body of the request:

  • redirectOnExitUrl: This allows you to specify where the learner will be directed to upon leaving the course. You only need to set it here (versus in your config) if you need this value to be different per-launch. You can read more about the behavior of that setting below.
  • tracking: if you pass this in with a value of false, then Engine will not record any progress from the launch. You might use this in order to give an admin or learner the ability to launch their registration after it has been completed without it affecting the current state.
  • startSco: For SCORM, the SCO identifier to launch first, overriding the normal sequencing. This applies to multi-SCO courses only.
  • expiry: this is a number of seconds that the launch link is valid. This parameter only takes effect if you are using the Signed Launch Links feature mentioned below.
  • additionalValues: these are extra parameters (name/value) that you want to be included on the launch URL. These are basically just appended to the launch URL we create with the other named parameters. One note: if you use signed launch links, these parameters will not be part of the token we create.

Optimizing the First Launch

The first time you launch a course for a learner, you will likely want to both create the registration and then immediately get the launch link at the same time. To help optimize this scenario, Engine has a separate endpoint for combining the two operations into one request: /registrations/withLaunchLink.

With this endpoint, you will be posting a JSON object that contains all the things necessary to do both operations. For example, you might use the following JSON to create a registration and get the launch link with an expiry of 30 seconds:

{
    "registration": {
        "courseId": "12345",
        "learner": {
            "id": "learner123",
            "firstName": "John",
            "lastName": "Smith"
        },
        "registrationId": "4c2a59b5-72d5-460f-9c85-6547c25a96e01621373241987"
    },
    "launchLink": {
        "expiry": 30
    }
}

One note: both properties are required, even if you are not passing any properties for the launch link creation. In that case, you would just use an empty object as the value for the launchLink property (eg. {}).

We generally recommend that customers utilize Engine's ability to create signed, expirable launch links. If the use of signed launch links is enabled, links generated by the API will be signed, and only signed launch links will be accepted by the player. Because of this, your launch links must be generated via the API every time you need one.

Enabling signed launch links will also configure the player to use an expirable token when it reports course progress back to Engine, which will block any attempts to record dubious course progress from third parties, or from stale launches.

In order to enable signed launch links in Engine, use the following configuration settings:

  • ApiUseSignedLaunchLinks: enables the feature [default: false]
  • ApiTokenSecret: secret used to sign tokens generated by the API. If the string starts with '0x' the remainder will be interpreted as hexadecimal.
  • ApiTokenPostbackValidHours: number of hours that the token used to authenticate player postbacks is valid. Remember, this setting can be set on a per-course basis, so you have the power to cater this setting to each course's expected duration, if desired. [default: 24]

In order to cause a launch link to expire, pass expiry as a parameter to either the /preview or /launchLink resources, where the value is the number of seconds till expiration (0 represents no expiration).

Once you have called the API to get the launch link for a particular registration, then you are ready to actually send the learner to the course. Typically customers will do one of two things:

  • use the launch URL as the source for an iframe within their applications own page
  • open a new window/tab with the launch URL

Once the launch URL is hit in the user's browser, it will redirect to the player page which will load the correct course content for the learner and retrieve any existing bookmark or progress details. At that point, the learner will interact with the course content and the player will record their progress back to Engine.

While the course is open, the player will periodically send the course's progress back to Engine, and Engine will in turn update your application with the status of the registration. You can read more about the data that is reported to your application in the Tracking Learner Progress section.

Redirect on Course Exit

When a learner finishes taking a course, they will typically either close a popup content window, or click an Exit button inside the content or the player. When they do this, Engine's player page will be triggered to redirect to a page of your choosing. Often this is sending the learner back to a summary page showing their status, or a page that will execute some custom logic to refresh a parent page, etc. You can use Engine's token replacement system to pass the ID of the completed registration back to your application's page as a query parameter.

To configure this behavior, you should set a value for RedirectOnExitUrlin your Engine config. The default value is a placeholder page that ships with Engine which is not appropriate for a production environment.

If you would like to specify this value at course launch time, you can pass a query parameter called redirectOnExitUrl when you call the API to get the launch link. Customers sometimes do this because the redirect URL needs to include parameters specific to that learner's launch of the course.

Some customers would rather not redirect the course window after launch at all. For those situations, you can set the value of RedirectOnExitUrl to noop, which is short for "no operation". This will disable the redirect behavior and leave the player open on exit. If you would like to specify a custom message that will display on this page, then you can use a setting value of noop_message=Your custom message here.

Note: the learner may never actually make it back to your redirectOnExitUrl page. Once a learner is finished with their registration, they might just close the their browser. In this case, our content player will use its onbeforeunload handler to fire off a final state save, but the browser will not have time to load your exit page.

As a result, your integration cannot rely on learners making it back to that page. This limitation is the primary reason that we stress using the registration postback feature to get registration results reliably.

Preview Launches

If you need to open a course outside of the context of an individual learner, you can generate a preview link with the API at /courses/{courseId}/preview. That endpoint works very similarly to the /launchLink endpoint, and you can treat that link the same way that you would treat a traditional launch link, using it in an iframe or a new window.

This functionality can be used to serve a couple of different purposes in your application. If you want to provide your content administrators with a way to audit a newly-imported course for any typos or misbehavior, then a preview launch works perfectly. You can also use it as a way for someone browsing courses to get a quick peek at the course contents, or as a way to preview any changes to the course's settings.

results matching ""

    No results matching ""