Embedded learning building blocks: Course player widget

Introduction

Embedded learning allows you to start an instance of your Docebo platform on any external web page, as long as you have access to its HTML and JavaScript code.

The Docebo platform instance opens as a pop-up activated either when the user clicks on a button or interacts with an element - such as a link, or a string - on the external web page. When the pop-up opens, the platform instance shows the training content you, as the Superadmin, have selected for the user on the basis of the action they are performing, in order to provide the best learning on the fly experience, enriching it with ad hoc training.

Embedded learning is available as a web-based application on desktop and mobile platforms.

The course player widget allows you to play content from the Docebo platform as if you were using the Docebo platform itself. As such, all statistics that would be produced when using the Docebo platform are also reproduced by using the widget, allowing the platform to keep track of the learners in the usual manner.

If the training material you have selected is a downloadable file, you will be presented with a download button that you can press to save the file locally. In the event that you have already downloaded this file previously, you will be advised of this fact by the course player widget, while still being given the option to download it again.

The configuration of features like, closed captioning, playback speed controls and the ability to skip ahead or back are managed in the platform. For more information please see Configuring the course player (opens in a new tab).

Activating embedded learning

To activate embedded learning, reach out to Docebo via the Help Center (opens in a new tab), or by contacting your Account Manager (if your plan includes this option).

HTML tag

The Docebo course player requires the following tag to be inserted into the web page to display:

<dcbo-course-player
  [LIST OF ATTRIBUTES]
  >
</dcbo-course-player>

List of tag attributes

The dcbo-course-player tag can accept the following list of attributes, all values associated with the attributes should be encapsulated in double-quotation marks. All parameters are optional, unless stated otherwise in the description.

`id`

The ID of the course player

Type: String

Please note:
If this attribute is not supplied then the widget becomes non-interactive via JavaScript or other widgets in the page.

`type`

The single course player type. This attribute can be static or dynamic.

Type: String

Default value: static

`sources`

The ID of the widget providing the source material to be displayed. The IDs are separated by commas.

Type: String

`courseid`

The ID of the course that will be displayed in the player.

Type: String

Please note:
This parameter is required.

`autoplay`

If set to true the video in the widget will start playing the content as soon as the Start Learning button is pressed, otherwise it will wait for user-interaction.

Type: Boolean

Default value: false

`showfullscreen`

If this value is set to true or omitted, this widget will be playable in full screen, which can be activated by pressing the full-screen button in the player. If this attribute is set to false, this option will not be displayed.

Type: Boolean

Default value: true

`showpip`

If this value is set to true, a button allowing this widget to be played in "picture-in-picture" mode is displayed. When pressed, the output of the player is overlaid on screen. If set to false the button is hidden and the functionality is removed.

Type: Boolean

Default value: true

Tip:
This attribute is available only for video content

`showtoc`

If this value is set to false then the table of contents button will not be displayed.

Type: Boolean

Default value: true

`forcefullscreen`

If this value is set to true, this widget will be started in full-screen mode, otherwise it will remain within the constraints of the widget’s dimensions in the page.

Type: Boolean

Default value: false

`showthumbsintoc`

If this value is set to true then a thumbnail preview of this content to be displayed in the table of contents.

Type: Boolean

Default value: false

`showpreview`

If this value is set to false then the preview will not be displayed.

Type: Boolean

Default value: true

`tmdownloadmode`

A string value of either blob or link. This attribute changes the training material download mode.

Type: String

Default value: blob

`globalsearchfilter`

Sets the filter value for the global search.

Type: String

Possible values:

courses_and_learning_plans
course_content
course_catalogs

Default value: courses_and_learning_plans

Tip:
This option is only valid when type is set to dynamic.

`noresulttitle`

A custom title shown in the slate when the search result is empty.

Type: String

Default value: Whoops, there's nothing here

Tip:
This option is only valid when type is set to dynamic.

`noresultdescription`

A custom description shown in the slate when the search result is empty.

Type: String

Default value: Looks like there is nothing for you in this area right now

Tip:
This option is only valid when type is set to dynamic.

`showcoursedeadline`

If set to true, shows the deadline of hte course in the course details tile. If set to false, the deadline of the course will not be displayed.

Type: Boolean

Default value: true

Tip:
This attribute shows the course deadline, not the user's enrollment deadline for the course.

Example

You can then add the following tag in the position you wish to place the widget:

<dcbo-course-player
  id="player1"
  courseid="insert valid course id"
  autoplay="false"
  forcefullscreen="false"
  showfullscreen="true"
  showpip="true"
  showthumbsintoc="false"
  sources="id_of_the_myC&LPs_widget"
  >
</dcbo-course-player>

Please note that you can place this tag inside a <div> </div> tag in order to manipulate the position, size and behavior of the widget itself.

Back button

A CSS token is provided to change the back button icon:

--dcb-flow-course-player-back-button-icon: <icon>

To use it, wrap the CSS token inside dcbo-course-player{}. For example:

dcbo-course-player {
  --dcb-flow-course-player-back-button-icon: 'close';
}

Views

The course player widget has three main views: preview, toc and viewer.

Unless the showpreview tag attribute is set to FALSE, the first view is preview. From there, both toc and viewer can be reached. In every view, if a previous view was shown, a navigation back button is also displayed.

Before a view is shown, a series of prerequisites need to be fulfilled. If these prerequisites are not met then a redirect to a fallback view is executed until the correct view is shown.

Every time a user changes a view, the selected course is refreshed to keep the data up-to-date.

Commands accepted by the course player widget

The following JavaScript commands can be issued to interact with the widget embedded in your page. The commands are dependent on the ID of the player being stated as an attribute when embedding the widget. In the following list, replace the term ID OF WIDGET with the actual ID of your widget.

Load current training material and play if video

Loads the current training material and if it is a video also starts playing it.

Command:

DSDK.getCommandBus().send(
  'play',
  'ID OF WIDGET',
  {}
)

Promise response payload:

After the command is received, the promise is resolved with:

{
  playing: true
}

Pause training material playback

Pauses the training material. Any further attempt to play the course will resume from the current training material.

Command:

DSDK.getCommandBus().send(
  'pause',
  'ID OF WIDGET',
  {}
)

Promise response payload:

After the command is received, the promise is resolved with:

{
  paused: true
}

Stop training material playback

Stops the playback of the current training material and resets the start point to the first training material of the course.

Command:

DSDK.getCommandBus().send(
  'reset',
  'ID OF WIDGET',
  {}
)

Promise response payload:

After the command is received, the promise is resolved with:

{
  reset: true
}

Move course pointer to next available training material

Moves the pointer of the course to the next available training material.

Tip:
This command has no effect if there is no further training material available.

Command:

DSDK.getCommandBus().send(
  'select_next_tm',
  'ID OF WIDGET',
  {}
)

Promise response payload:

After the command is received, if the command is accepted (Single course player is in the viewer) the promise is resolved with success: true otherwise success: false:

{
  success: true | false
}

Move course pointer to previous training material

Moves the pointer of the course to the previous available training material.

Tip:
This command has no effect if there is no previous training material available.

Command:

DSDK.getCommandBus().send(
  'select_prev_tm',
  'ID OF WIDGET',
  {}
)

Promise response payload:

After the command is received, if the command is accepted (Single course player is in the viewer) the promise is resolved with success: true otherwise success: false:

{
  success: true | false
}

Set the playback volume of the video player

Sets the playback volume of the video player to the predefined volume percentage levels.

Command:

DSDK.getCommandBus().send(
  'set_volume_level',
  'ID OF WIDGET',
  {
    level: VALUE BETWEEN 1 AND 100
  }
)

Possible values:

1 to 100

Promise response payload:

If the value can not be set due to invalid parameters passed to the command:

{
  success: false
}

If the command payload was sent in in the correct format:

{
  volume: [VALUE BETWEEN 1 AND 100]
}

Mute the video player

Sets the playback volume of the video player to 0.

Command:

DSDK.getCommandBus().send(
  'mute_player',
  'ID OF WIDGET',
  {}
)

Promise response payload:

{
  muted: true
}

Unmute the video player

Sets the playback volume of the video player the previously set volume levels before muting.

Tip:
This command has no effect if the video player is not already muted.

Command:

DSDK.getCommandBus().send(
  'unmute_player',
  'ID OF WIDGET',
  {}
)

Promise response payload:

{
  muted: false
}

Open the table of contents

Opens the Table of contents.

Tip:
This command is only available in full-screen mode.

Possible values for tab:

overview
content

Default value:

overview

Command:

DSDK.getCommandBus().send(
  'open_toc',
  'ID OF WIDGET',
  {
    tab: 'overview' | 'content' // optional
  }
)

Promise response payload:

If the table of contents cannot be opened:

{
  opened: false
}

Otherwise:

{
  opened: true,
  tab: 'overview' | 'content'
}

Close the table of contents

Closes the table of contents and reverts back to the player.

Tip:
This command is only available in full-screen mode.

Command:

DSDK.getCommandBus().send(
  'close_toc',
  'ID OF WIDGET',
  {}
)

Promise response payload:

{
  closed: false | true
}

Change the table of contents tab

Changes the selected tab of the table of contents.

Tip:
This command is only effective if:
the table of contents is already open in either the overview or content tabs
the widget is in full-screen mode

Possible values:

overview
content

Command:

DSDK.getCommandBus().send(
  'change_toc_tab',
  'ID OF WIDGET',
  {
    'tab': 'overview' | 'content'
  }
)

Promise response payload:

If the table of contents cannot be accessed:

{
  changed: false
}

Otherwise:

{
  changed: true,
  tab: 'overview' | 'content'
}

Hide course player widget

This commands hides the course player widget from the page (if visible).

Command:

DSDK.getCommandBus().send(
  'hide',
  'ID OF WIDGET',
  {}
)

Show course player widget

This command shows the course player widget in the page (if hidden).

Command:

DSDK.getCommandBus().send(
  'show',
  'ID OF WIDGET',
  {}
)

Load a course into the course player

Loads the course specified by the course ID into the widget specified by its ID.

Command:

DSDK.getCommandBus().send(
  'load_course',
  'ID OF WIDGET',
  {
    'id': 'Insert valid course ID here'
  }
)

Tip:
You can retrieve the ID of a course using the GET /course/v1/courses API call. For more information on retrieving IDs, please see API essentials - Retrieving IDs.

Promise response payload:

{
  loaded: true | false
}

Search by keyword

Search the keyword in the global search in order to retrieve and load the first playable course.

Command:

DSDK.getCommandBus().send(
  'search', 
  'ID OF WIDGET', 
  {
    'keyword': 'Insert a valid string'
  }
)

Tip:
This command is accepted only if the value of the type tag attribute value is dynamic.

Promise response payload:

{
  loaded: true | false
}

Play current training material

This command plays the currently loaded training material.

Command:

DSDK.getCommandBus().send(
  'play_current', 
  'ID OF WIDGET', 
  {
    'keyword': 'Insert a valid string'
  }
)

Promise response payload:

{
  playing: true
}

Change player view

Use this command to change the single course player view. The single course player will select the closest view regards the selected view.

Possible values:

preview
toc
viewer

Command:

DSDK.getCommandBus().send(
  'change_view', 
  'ID OF WIDGET', 
  {
    'view': 'preview' | 'toc' | 'viewer'
  }
)

Events generated by the course player widget

Events are generated by the course player widget usage, allowing you to listen and monitor the behavior of the user during the navigation of the widget and the consumption of the course with JavaScript to add extra functionality to your page.

To listen the events, embedded learning provides the proper listener, which is used as follows:

DSDK.getEventManager().on('event_name', (e,p) => {console.log('Event Name => ',p);});

Tip:
In the event listener, the following variables are used:
event_name is the name of the event
e is a string that indicates the emitter ID
p is the payload which is an object that depends on the events

widget_created

The widget has been created

Payload type:

{
  id: string;
  type: WidgetType;
  view: FlowView;
}

widget_destroyed

The widget has been destroyed

Payload type:

{
  id: string;
  type: WidgetType;
  view: FlowView;
}

course_loaded

A course has been loaded by the player

Payload type:

{
  id: string,
  name: string,
  type: string,
  status: string,
  enrollment_status: string,
  enter_status: string,
  emitter: string
}

type parameter values:

elearning
classroom
webinar
learning_plan

status parameter values:

max_quota
expired
validity_in_future
user_unauthorized

enrollment_status parameter values:

in_progress
waiting_list
completed
suspended
overbooked
enrolled
not_started

enter_status parameter values:

in_waiting_list
in_waiting_list_play
in_waiting_list_enroll
locked
buy
enroll
play

Example payload:

{
  id: '189', 
  name: 'Course Example',
  type: 'elearning',
  status: null,
  enrollment_status:'in_progress',
  enter_status: 'enroll' 
  emitter: 'player1'
}

course_status_changed

A course status has been changed (user enrolled in the course, start the course, etc.)

Payload type:

{
  id: string,
  name: string,
  type: string,
  status: string,
  enrollment_status: string,
  enter_status: string,
  emitter: string
}

type parameter values:

elearning
classroom
webinar
learning_plan

status parameter values:

max_quota
expired
validity_in_future
user_unauthorized

enrollment_status parameter values:

in_progress
waiting_list
completed
suspended
overbooked
enrolled
not_started

enter_status parameter values:

in_waiting_list
in_waiting_list_play
in_waiting_list_enroll
locked
buy
enroll
play

Example payload:

{
  id: '189', 
  name: 'Course Example',
  type: 'elearning',
  status: null,
  enrollment_status:'in_progress',
  enter_status: 'enroll' 
  emitter: 'player1'
}

playback_started

Playback has started in the player

Payload type:

{
  trainingMaterialId: string,
  name: string,
  emitter: string
}

Example payload:

{
  trainingMaterialId: '89', 
  name: 'Course Example', 
  emitter: 'player1'
}

playback_paused

Playback has paused in the player

Payload type:

{
  trainingMaterialId: string,
  name: string,
  emitter: string
}

Example payload:

{
  trainingMaterialId: '89', 
  name: 'Course Example', 
  emitter: 'player1'
}

playback_reset

Playback has been reset in the player

Tip:
This event has no payload

volume_level_changed

The volume level in the player has changed

Payload type:

{
  level: number,
  emitter: string
}

Example payload:

{
  level: 80, 
  emitter: 'player1'
}

widget_fullscreen

The Fullscreen event is triggered when the fullscreen mode changes and the payload sends true if the fullscreen is open, and false if closed.

Payload:

{
  fullscreen: boolean
}

view_changed

The view has been changed either by a command or via the user interface

Payload type:

view parameter values:

preview
toc
viewer
viewer_toc
value emitted when the viewer (view where the current training material is played) and the right panel toc is open
waiting_list
when the modal message of waiting_list is shown
warning
when a full-screen blank slate is shown (if the parameter forcefullscreen is true and the blank slate is shown in the viewer view, the payload will be either viewer or viewer_toc)

Example payload:

{
  view: 'preview', 
  emitter: 'player1'
}

training_materials_list_loaded

Training material list is loaded when content tab in the table of contents is opened

Payload type:

{
  training_materials_list: [
    {
      id: string,
      name: string,
      type: string,
      locked: boolean | string,
      status: string
    }
  ]
  emitter: string
}

type parameter values:

scormorg
aicc
tincan
video
youtube
wistia
vimeo
file
deliverable
htmlpage
poll
test
sign
googledrive
authoring

locked string parameter values:

max_number_views
locked_maxattempts
locked

Example payload:

{
  training_materials_list: 
  [ 
    { 
      id: "181", 
      locked: false, 
      name: "Course name", 
      status: "in_progress",
      type: "elearning" 
    }
  ],
  emitter: "player1"
}

warning_shown

A blank slate is shown

Payload type:

{
  type: string,
  emitter: string
}

type parameter values when the emitter is a single course player:

widget_invalid_configuration
The attributes are not valid or the course type is not supported
widget_no_content
There is no content to show. Currently, this occurs only when the course is priced.
widget_no_course
user_authentication_failed
The user is not authenticated
user_unauthorized
The user is not authorized to view the requested content
user_not_enrolled
user_in_waiting_list
The user is in the waiting list
training_material_list_empty
There is no training material in the course
training_material_error
The training material has an error. This could happen when the training material is removed, or the Docebo platform has problem and embedded learning cannot retrieve the content.
training_material_with_prerequisites
purchase_info
no_result_search
course_max_quota
course_validity_in_future
course_expired

Example payload:

{
  type: 'training_material_error', 
  emitter: 'player1'
}

training_material_status_changed

The status of a training material is changed

Payload type:

{
  emitter: string,
  id: string,
  name: string,
  type: string, 
  status: string
}

type parameter values:

aicc
scormorg
video
tincan
wistia
vimeo
file
htmlpage
youtube

status parameter values:

in_progress
incomplete
completed
passed
attempted
failed

Example payload:

{
  emitter: "player1",
  id: "181",
  name: "Course",
  type: "scormorg"
  status: "in_progress"
}

Course player widget handling of course visibility rules

Based on the course visibility settings (opens in a new tab) in the Docebo platform, the course player widget restricts access to courses. Unlike in the platform, the courses will still remain visible in the player but will display a message explaining that the course can not be played. The following scenarios are possible:

Scenario	Outcome
The visibility of the course in the catalog is set to Show the course only to enrolled learners and the user is not enrolled	The course player will display a message denying access to the course
The course self-enrollment setting in the catalog is set to Self-enrollments are not available	The course player will present the course's preview page with the Start Learning button disabled, it will also display a message denying access to the course when clicking on the Table of Contents
The course enrollment policy in the catalog is set to Only Admins can enroll learners	The course player will present the course's preview page with the Start Learning button disabled, it will also display a message denying access to the course when clicking on the Table of Contents
The course has filled its maximum quota for enrollments and is configured without a waiting list	The course player will present the course's preview page with the Start Learning button disabled, it will also display a message denying access to the course when clicking on the Table of Contents
The course has filled its maximum quota for enrollments and is configured without a waiting list and is set to require admin approval for enrollments	The course player will present the course's preview page with the Start Learning button disabled, it will also display a message denying access to the course when clicking on the Table of Contents
The course is set to self-enrollment with pre-set dates	The course player will present the course's preview page with the Start Learning button disabled, it will also display a message denying access to the course when clicking on the Table of Contents
The course is set to self-enrollment with a waiting list and pre-set deadline times not met	The course player will present the course's preview page with the Resume Learning button disabled, it will also display a message denying access to the course when clicking on the Table of Contents

Supported training material

At this time only the following types of training material are supported (all links in this list open in a new tab):

Tip:
Only e-learning courses are supported

Video
- Imported Video
- YouTube
- Vimeo
- Wistia
  Please note:
  Your Wistia administrator needs to add the domain where embedded learning is being hosted to the allow list in Wistia to ensure that the video can be properly viewed by your learners. Not adding the domain to the allow list can result in the following error being displayed in the widget:
SCORM
TinCan (xAPI)
AICC
VILT sessions
HTML
Slides Converter
Survey
Test
Central Repository
Observation Checklist
Google Drive
Best practice:
Docebo recommends viewing Google Drive training materials in full-screen mode.
LTI
Elucidat

Important notes:
Please make sure you allow third party cookies. This is particularly important when using SCORM objects as some course providers make use of cookies in packages and without allowing them, their courses may encounter functionality issues.
The SCORM, TinCan (xAPI) and AICC player might require a session cookie to be hosted by the external site. If this occurs, the hosting web site may need to adjust their own cookie policy to accept this behavior. These cookies are mandatory to allow for the correct usage of the Docebo content player.