Storyline 360: Supplying the Actor via a Query String

In this article, you'll learn when and how to supply the actor via a query string.

A query string is a set of characters that contains the values required to track a course: the LRS endpoint (endpoint), the authentication (auth), and the learner info (actor). Query string parameters are located after the "?" in the launch URL.

You only need to supply the actor via a query string when both of the following are true:

• The Supplied via launch URL option for the Actor section is selected
• The course isn't published for an xAPI or cmi5 LMS

How to Supply the Actor via a Query String

Install the November 2021 update or later, then follow the steps below, depending on whether you need to reference a specific actor or different actors.

Note: We created this LRS Launch Test guide to simplify the process of formatting and testing your query string. It's not meant for live production work.

Specific Actor

Follow these steps to test your query string for a specific actor.

1. Publish your course for LMS/LRS, then click Open in the Publish Successful window. This opens a file viewer where you can see the files Storyline 360 just created.
2. Go to the LRS Launch Test guide, right-click anywhere on the page and select Save As to download the page as an HTML file on your computer.
3. Move the LRS Launch Sample HTML file to the folder that contains your published output from step 1.
4. Open the LRS Launch Sample HTML file in a browser window, then select the query string format and enter the details for your LRS's endpoint, authentication, and actor.
5. Click the Test button to launch the course in your LRS. At this point, test your course as a learner to send data back and forth to the LRS.

Different Actors

When you need the supporting JavaScript for supplying different actors via a query string in live production work, use this approach. Choose from two query string formats—Storyline or xAPI—to generate a link to your content with an actor for the current learner. Use either query string format, except when publishing for both an xAPI/cmi5 LMS and LRS. For this scenario, we recommend using the Storyline query string format to avoid any issues.

Storyline Query String Format

For the Storyline query string format, share this code with your LRS admin since they're best equipped to configure your LRS:

var toBasicAuth = function(key, secret) {
  return 'Basic ' + btoa(key + ':' + secret);
};

var formatActor = function(name, email) {
  return {
    mbox: 'mailto:' + email,
    objectType: 'Agent',
    name: name
  };
};

var isEmpty = function(value) {
  if (value == null) {
    return true;
  }
  if (value.length === 0) {
    return true;
  }
  if (typeof value === 'object' && Object.keys(value).length === 0) {
    return true;
  }
  return false;
};

var formatSLXApiQueryString = function(actor, endpoint, auth) {
  var slXapi = {};

  if (!isEmpty(actor)) {
    slXapi.actor = actor;
  }
  if (!isEmpty(endpoint)) {
    slXapi.endpoint = endpoint;
  }
  if (!isEmpty(auth)) {
    slXapi.auth = auth;
  }

  if (isEmpty(slXapi)) {
    return '';
  }
  return 'slxapi=' + encodeURIComponent(JSON.stringify(slXapi));
};

/*

Usage:
var actor = formatActor('my-name', 'name@email.com');
var auth = toBasicAuth('key', 'secret');
var endpoint = 'http://url-to-my-endpoint/';
var queryString = formatSLXApiQueryString(actor, endpoint, auth);
window.open('http://path-to-content/story.html?' + queryString);

*/

xAPI Query String Format

For the xAPI query string format, share this code with your LRS admin since they're best equipped to configure your LRS:

var toBasicAuth = function(key, secret) {
  return 'Basic ' + btoa(key + ':' + secret);
};

var formatActor = function(name, email) {
  return {
    mbox: 'mailto:' + email,
    objectType: 'Agent',
    name: name
  };
};

var isEmpty = function(value) {
  if (value == null) {
    return true;
  }
  if (value.length === 0) {
    return true;
  }
  if (typeof value === 'object' && Object.keys(value).length === 0) {
    return true;
  }
  return false;
};

var formatTinCanQueryString = function(actor, endpoint, auth) {
  var params = [];

  if (!isEmpty(actor)) {
    params.push('actor=' + encodeURIComponent(JSON.stringify(actor)));
  }
  if (!isEmpty(endpoint)) {
    params.push('endpoint=' + endpoint);
  }
  if (!isEmpty(auth)) {
    params.push('auth=' + auth);
  }

  return params.join('&');
}

/*

Usage:
var actor = formatActor('my-name', 'name@email.com');
var auth = toBasicAuth('key', 'secret');
var endpoint = 'http://url-to-my-endpoint/';
var queryString = formatTinCanQueryString(actor, endpoint, auth);

window.open('http://path-to-content/story.html?' + queryString);

*/