Player widget

The player widget is the general player for drills, stories, courses, tests, and combinations of drills and courses.

Direct link Basic

An easy way to open a player widget full screen in a browser window is to refer to a URL like the below example:

https://www.drillster.com/connector/player/hwgaTGd0BAMqfxsrABT4_Z

Substitute the code for the unique ID of the drill, course, story or test.

Assuming that the user is already authenticated with Drillster, this will open a player for the given playable ID. To have more control over authentication, and the ability to interact with the player in the browser, please see the section about “embedding” below.

It is possible to open a player widget for a combination of drills by comma-separating the individual drill codes:

https://www.drillster.com/connector/player/hwgaTGd0BAMqfxsrABT4_Z,0EYWvDj45143OZTYIiEAmw

Combinations are only supported for drills.

Note that this URL structure cannot be used to place a player on a page using an iframe. In order to embed a player on the page, please see below.

Preview of player version 4

Drillster is in the process of rolling out the next iteration of the player – version 4. Eventually this version will be used when using the /connector/player link, but it is possible to select this new version now by adding a parameter ?version=4 to the URL. Example:

https://www.drillster.com/connector/player/hwgaTGd0BAMqfxsrABT4_Z?version=4

Embedding Advanced

It is also possible to place a player widget on your own web pages. Assuming that the widget loader is included in the page, a player may be embedded as follows:

<div class="drl-widget drl-player" drl-code="hwgaTGd0BAMqfxsrABT4_Z" id="player42"></div>

Attributes

The following attributes are supported for the player widget:

Attribute Description
drl-code

Represents the unique ID of the drill, story, test or course. For a combination of drills and/or courses, use a space separated list of codes as the value. Combinations of tests are not supported.

drl-activity

For courses, indicates at which step the player should start. Takes the activity ID.

Note: the drl-activity attribute is optional and only applies to courses.

drl-token

An optional OAuth token.

An OAuth token may be obtained by using a standard service account or by using the custom delegated login API.

drl-ticket

An optional ticket string for use with anonymous tests.

drl-adaptive-test-start

An optional starting level for use with adaptive tests. Only applies to adaptive tests.

drl-allow-full-screen

Indicates whether the user is permitted to switch the player to full screen mode.

Accepted values are true and false. If no value is given, the behavior is to disallow the full screen mode.

id

An optional identifier for the widget. The id is useful to determine which widget sent a client side event in case there are multiple widgets on the page. Please make sure to use a unique ID for each widget present on the page.

drl-auto-focus

An optional boolean to indicate that the player's content window will receive focus upon starting. The default value is false.

drl-can-close

An optional boolean which, if set to true, will cause a “×” close button to the upper right hand corner of the player widget. Also, a “Close” button will appear in the final screen of the learning object. Clicking these buttons will cause a PLAYER_CLOSE event to be emitted by the player. It does not automatically close the player; that is the responsibility of the component that opened the player in the first place. Please ensure this event is handled appropriately when making use of this option.

drl-preview

Starts the player in preview mode. This functionality is only available to the author of a drill or story. The contents of the current draft version are shown, without any progress or proficiency. It is up to the user to establish that the caller does have this permission.

Valid values are overview to make the player start on the overview screen, or play to start with the next story page or drill question.

drl-preview-start

Indicates the starting point, for the preview mode. Only applicable when the player is started in drl-preview mode. If not specified, the “next” page or question will be loaded.

drl-color

Adapts the color elements of the player using a given color code. The color must be a six-digit hexadecimal color code, without the #-prefix. Note that the given color is used to derive various other colors from. This means that you may see colors in the player widget that look like, but do not exactly match the given color. This is done to guarantee sufficient contrast between various screen elements, and to ensure balanced overall look.

Example: drl-color="ff0000".

drl-suppress-connect-apps

An optional boolean which, if set to true, will suppress the ability to request an access code to access the Drillster mobile app.

Example: drl-suppress-connect-apps="true".

drl-version

Drillster is in the process of rolling out the next iteration of the player – version 4. Eventually this version will be used by default, but it is possible to select this version now by adding drl-version="4".

Please note that at this time the drl-color attribute is not yet supported by player version 4.

Player dimensions

The width and height of an embedded widget can be set by manipulating the style attributes of the containing element. For example, to embed a player widget with dimensions of 600×400 pixels, the following code may be used:

<div class="drl-widget drl-player" style="width: 600px; height: 400px;" drl-code="hwgaTGd0BAMqfxsrABT4_Z" id="player42"></div>

Localization

Currently the player widget supports the following languages:

  • 🇧🇷  Portuguese (BR)
  • 🇩🇪  German
  • 🇩🇰  Danish
  • 🇪🇸  Catalan
  • 🇪🇸  Spanish
  • 🇫🇷  French
  • 🇮🇩  Indonesian
  • 🇳🇱  Dutch
  • 🇹🇷  Turkish
  • 🇺🇸  English (US)
  • 🇨🇳  Chinese
  • 🇮🇹  Italian
  • 🇳🇴  Norwegian
  • 🇷🇴  Romanian
  • 🇸🇪  Swedish

A player widget's locale is determined as follows:

  1. stored language preference – for authenticated users there may be a stored language preference
  2. declared language of the containing page – the page that embeds the player may have declared a language in the html tag using a lang attribute
  3. browser setting – there may be a preferred language set in the browser
  4. English – in all cases where the language preference cannot be determined, US English is used

If the requested language is not supported, the player will use English (US). Additional localizations may be added in the future. If you require a specific localization that is not yet supported, please get in touch with us.

Client side events

The player widget is able to emit the following client-side events.

Event Fired if Payload
INITIALIZED

The player was correctly initialized and is ready to be used.

If there is an authenticated user, the INITIALIZED event may include a payload with status details for that user. This may include a current and highest proficiency, or a progress in case of a test.

{
  "type": "DRILL",
  "proficiency": {
    "current": 42,
    "highest": 82
  },
  "timeSpent": 542
}
{
  "type": "STORY",
  "progress": 100
}
{
  "type": "COURSE",
  "proficiency": {
    "current": 42,
    "highest": 82
  },
  "progress": 86,
  "timeSpent": 542
}
{
  "type": "TEST",
  "progress": 75
}

In case of a completed test, the INITIALIZED event may also include the outcome of the test. For drills, an estimate of the time spent on it by the learner, expressed in seconds, is included.

{
  "type": "TEST",
  "progress": 100,
  "result": {
    "score": 95,
    "transformations": [
      {
        "id": "narrative",
        "result": "very good"
      },
      {
        "id": "outcome",
        "passed": true,
        "result": "passed"
      }
    ]
  }
}
INITIALIZATION_FAILED

The player could not be initialized.

An explanation of the problem.

{
  "error": "not_authorized"
}
STARTED

The user started the drill, course, test or story by using the Start button.

None.

QUESTION_ANSWERED

A drill or test question was answered.

For test answers the payload contains the progress.

{
  "type": "TEST",
  "progress": 42
}

For drill answers the payload includes the up-to-date proficiency, whether the given answer was correct, and an estimate for the time spent, expressed in seconds, by the learner on this drill. If a single drill is being practiced, the drill ID is also included.

{
  "type": "DRILL",
  "id": "6oh1EsxpJYqEcNuRwxS76Q",
  "proficiency": {
    "current": 42,
    "highest": 80
  },
  "timeSpent": 542,
  "correct": true
}
PROFICIENCY_CHANGED

The user's proficiency has changed as a result of answering a drill question.

The current (updated) and highest proficiency, as well as an estimate for the time spent by the learner expressed in seconds. If a single drill is being practiced, the drill ID is also included.

{
  "type": "DRILL",
  "id": "6oh1EsxpJYqEcNuRwxS76Q",
  "proficiency": {
    "current": 42,
    "highest": 80
  },
  "timeSpent": 542
}
TEST_PROGRESSED

There is a change in the progress of a test because a question was answered for the first time.

The current (updated) progress. Progress is expressed as a number between 0 and 100.

{
  "progress": 75
}
TEST_COMPLETED

The test was completed, either because the user submitted the test (navigable tests), reached the last question (non-navigable tests), or the time ran out on a test with a time limit.

The test score, if permitted by the test's author, possibly including any test score transformations. Also, the time spent by the learner on this test is included, expressed in seconds.

{
  "result": {
    "score": 95,
    "timeSpent": 542,
    "transformations": [
      {
        "id": "narrative",
        "result": "very good"
      },
      {
        "id": "outcome",
        "passed": true,
        "result": "passed"
      }
    ]
  }
}
FULL_PROFICIENCY_ATTAINED

100% proficiency for the current drill or drills was attained by the user.

An estimate for the time spent by the learner, expressed in seconds.

{
  "timeSpent": 542
}
ACTIVITY_COMPLETED

Emitted at completion of each course activity.

The current (updated) activity status, plus an overview of the current status of the course as a whole. The payload consists of three parts:

  1. activity information about the activity (step) that was just completed
  2. result information about the achieved results for that activity
  3. course information about the overall achievements at course level

Example for a completed drills step:

{
  "activity": {
    "type": "DRILLS",
    "id": "zL8-QWa1Bfyy4IbRwx8Upw",
    "playables": [{
      "type":"DRILL",
      "id":"6oh1EsxpJYqEcNuRwxS76Q"
    }]
  },
  "result": {
    "proficiency": {
      "current": 100,
      "highest": 100
    },
    "timeSpent": 216
  },
  "course": {
    "proficiency": {
      "current": 100,
      "highest": 100
    },
    "progress": 100,
    "timeSpent": 234
  }
}

Example for a completed story step for a course that also contains drills:

{
  "activity": {
    "type": "STORY",
    "id": "YmdP2Z4gv2PUCtCP6nDymA"
  },
  "result": {
    "progress": 100
  },
  "course": {
    "proficiency": {
      "current": 88,
      "highest": 100
    },
    "progress": 100,
    "timeSpent": 234
  }
}

Example for a completed story step for a course that does not contain any drills:

{
  "activity": {
    "type": "STORY",
    "id": "YmdP2Z4gv2PUCtCP6nDymA"
  },
  "result": {
    "progress": 100
  },
  "course": {
    "progress": 100
  }
}
OBJECTIVE_MET

A pre-set learning objective was met.

None.

STORY_PROGRESSED

There is a change in the progress of a story because a page was acknowledged for the first time.

The current (updated) progress. Progress is expressed as a number between 0 and 100.

{
  "progress": 75
}
STORY_COMPLETED

All pages in the story have been acknowledged. The progress is 100%.

None.

{}
PLAYER_CLOSE

The user has clicked the close button in the player.

None.