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 widget within the page. The platform instance shows the training content you, as the Superadmin, have selected for the user on the basis of the action he or she is performing, in order to provide the best learning on the fly experience, enriching it with ad hoc training.
Docebo embedded learning is available as a web-based application on desktop and mobile platforms.
Docebo embedded learning building blocks allow you to start single widgets presenting the content of your Docebo platform as part of the layout composition of any external web page, as long as you have access to its HTML and JavaScript code.
Building blocks has the advantage of modular training by using widgets that can be seamlessly injected into your HTML code using a low-code approach to guide behavior. This is coupled with the provisioning of the content, either using simple JavaScript commands or a small set of HTML tag attributes, by following the generic visibility policy rules set on the platform. The integrator building the web page will be able to create the best on-the-fly learning experience for the user based on vertical training needs by customizing the widget behavior without passing through the Flow configurator page of the Docebo platform.
The user who accesses the external web page must be authenticated by the Docebo platform before seeing any content on the page. Once the connection is established by granting the proper working session on the browser, the final user can be automatically provisioned with the training so that their learning flow is not interrupted, even by the need to log in.
Activating embedded learning
To activate Docebo embedded learning, reach out to Docebo via the Help Center, or by contacting your Account Manager (if your plan includes this option).
Integrating building blocks in your web site
The integration process for building blocks entails the loading of the kernel source, the positioning of the widget HTML tag in the page and the start of a JavaScript command with the the value of the platform domain and a valid access token.
Retrieving the latest kernel
To get the latest SDK Kernel URL you need to perform an API call to:
GET/setup/v1/flow/settings
For information on obtaining a bearer token, please see the article on APIs Authentication.
Here is an example of how to call it using cURL via the command line:
curl -X GET https://<yoursubdomain.docebosaas.com>/setup/v1/flow/settings \
-H 'Authorization: Bearer <your previously obtained bearer token>'This is an example of a JSON response from that API call. The building blocks kernel URL can be found in the value of sdk_kernel_url, represented in the example by the value buildingblocks-kernel-url-value.
{
"data":{
"kernel_url":"do-not-use-this-value",
"sdk_kernel_url":"buildingblocks-kernel-url-value"
},
"version":"1.0.0",
"_links":[]
}Please note:
The version number referenced in the previous response example refers to the Docebo API version, not the kernel version.
Only use the
sdk_kernel_urlvalue for your Building blocks kernel URL, do not use thekernel_urlvalue.
For more information about API calls, please see Introduction to Docebo APIs.
Loading the kernel
In order for building blocks to be able to load in your page, you will need to add the kernel. To do so, place the following script anywhere inside the <HEAD> </HEAD> section of your web page, replacing buildingblocks-kernel-url-value with the value retrieved in the retrieving the latest kernel step.
<script type="text/javascript" src="buildingblocks-kernel-url-value">Authenticating the kernel
After the kernel is loaded the user needs to be authenticated. This is accomplished by the use of simple JavaScript commands that will initialize the kernel and populate the widget based on the user’s training consumption.
Place the code shown here in your page, replacing the URL https://myplatform.com with the URL of your platform, anywhere after the script loading the kernel.
<script type="text/javascript">
function renewToken() {
// get the token from the backend
}
DSDK.kernel().setTokenProvider(renewToken);
DSDK.kernel().start({
domain: "https://myplatform.com",
language: "your preferred language code"}
);
</script>The start() command contains the following parameters:
Parameter | Description |
|---|---|
| The main or custom domain of your Docebo platform. |
| The display language used by the building blocks widgets. For more information please see the lang_browsercode column of the table in the article containing the list of all supported languages with their browser and ISO codes (opens in a new tab). If this value is not provided, English (US) will be used as a default language. |
Please note:
An older version of this command, which does not have the ability to set the language parameter, can also be used to start the kernel.
Warning
This command reached end-of-life on December 3, 2025. Docebo strongly advises you to update your code to use the new command to start the kernel.
The instructions for the old command are as follows:
start(domain)The
start()command starts the kernel. This command uses the following parameter:
domain(string, required): The domain of your Docebo platform (this can be also a custom domain)Example:
<script type="text/javascript"> function renewToken() { // get the token from the backend } DSDK.kernel().setTokenProvider(renewToken); DSDK.kernel().start("myplatform.com"); </script>
Configuring your site content security policy
If you are using content security policies on your hosting site, you will need to add rules to allow for the integration of building blocks. For more information please see Configuring your site content security policy for embedded learning.
Adding widgets to your web page
Adding widgets to your web page is as simple as adding a pair of HTML tags (start and end tags). The building blocks kernel will then inject the widget into the code at the desired location.
The code to be injected should be in the following format:
<dcbo-widget-name
id="ID NAME"
attribute1=”value”
attribute2=”value”
…
>
</dcbo-widget-name>Each widget has its own tag and specific attributes that can be specified. Please note that while the id attribute is technically optional, every widget should be given an ID in order to be able to interact with it using JavaScript commands.
Interacting with the widgets in your web page
As the widgets are displayed using JavaScript and <div> sections, you can easily interact with the widget in any manner you choose, using any event to issue commands to the widget. This can include, but is not limited to, window dimensions changing, a button being pressed, a timer expired, there is no limit to what you can use to trigger a command to send to the widget.
The following widgets are available for embedded learning Building Blocks:
Widget name | Description | Static / Dynamic support |
|---|---|---|
Plays content from the Docebo platform directly within your web page. All completion tracking and statistics are recorded in the usual manner. | Static and dynamic. In static mode, set a specific course ID via the | |
Displays the courses and learning plans the authenticated learner is enrolled in. Can be filtered by item type and status, and supports inline course playback or use with an external course player widget. | Static only. Content is determined by the learner's enrollment status in the platform. | |
Displays a list of courses to focus the learner's attention on selected training. Supports both a curated fixed list and a dynamically searched list. | Static and dynamic. In static mode, up to 20 specific courses are shown by course ID. In dynamic mode, results are pulled from the platform's global search and can be filtered by catalog, enrolled courses and learning plans, and course content. | |
Plays a specific asset from the Docebo platform. All tracking and statistics are recorded in the usual manner. | Static only. A specific asset is identified by its |
Please note
The My courses and learning plans widget and the Single asset player widget do not support dynamic mode. If your use case requires dynamically surfacing content based on user context or a search query, use the course list widget or course player widget instead.
Best practices
Structuring queries for dynamic widgets
When using widgets in dynamic mode (the course list widget and course player widget), content is retrieved using the platform's global search. The quality and relevance of results depend directly on how search queries are constructed.
Tip
Global search in dynamic mode searches across three areas:
course catalogs
enrolled courses and learning plans
course content (training materials within courses)
Use the
fromcatalogs,mycoursesandlpsandtrainingmaterialsattributes on the course list widget to control which areas are searched. Disabling areas you do not need improves result relevance and reduces noise.
When sending a search command programmatically, use specific, targeted keywords rather than broad terms. For example, searching for "onboarding compliance" returns more focused results than "training". If your platform uses consistent naming conventions for courses, align your search queries with those conventions.
Please note
Dynamic mode returns results according to the visibility rules set on the Docebo platform. A learner will only see courses and training materials they have permission to access. If a search returns unexpected results or no results, verify the course visibility settings and catalog configuration in the platform.
Providing widget IDs
Always supply an id attribute for every widget you embed. While the attribute is technically optional, omitting it prevents the widget from receiving JavaScript commands or interacting with other widgets on the page.
Example
A course list widget cannot send the selected course to a separate course player widget if either widget lacks an ID
Combining widgets
The course list widget and My courses and learning plans widget can both send a selected course to an external course player widget by referencing the player's ID in the sources attribute. This lets you separate the browsing experience from the playback experience, giving you more control over page layout.
Best practice
When embedding both a course list widget and a course player widget on the same page, set
includeplayer="false"on the course list widget and point the course player's sources attribute to the course list widget's ID. This keeps the layout predictable and gives you full control over the player's position and dimensions.