Articles on: Developers & API
This article is also available in:

Advanced integration of the HTML integration code (widget) via the API

Widget sample code

   <!-- Include the bundles -->
   <script src="" type="text/javascript"></script>

   <!-- Setup the widget on page load -->
       window.addEventListener('load', function () {
           var widget = DigitaService.Widget.Create({
               autoscroll: true,
               element: 'gamification-widget',
               engine: '',
               fixed: false,
               sharingurl: '',
               width: '100%',
           widget.onReady = function (event) {};
           widget.onComplete = function (event) {};
           widget.onFirstInteraction = function () {};
           widget.onRouteChange = function (event) {};
           widget.onScrollToTop = function () {};
           widget.onClose = function () {};
           widget.onError = function (errorEvent) {};
<div id="gamification-widget"></div>


Create a Widget passing an Options object to the Create function:

var widget = DigitaService.Widget.Create(options);

Setup Options


options.elementstring - HTMLElementThe widget will be injected into this HTMLElement. You may pass direct access to an existing HTMLElement or provide the string ID for that element. If you do not provide this property, it will attempt to find a “digitaservice-widget” id on the page.
options.enginestringThe absolute URL to the application that will be loaded into the widget.


options.heightstringautoThe widget has a default height of zero before it has been loaded. You may override this with a placeholder value to avoid page jumping depending on where the widget is used in the parent page. The value is in pixels such as “600px”. When using options.fixed = true the height value will be locked to the provided value introducing scroll bars.
options.autoscrollbooleantrueDepending on content length of the widget content and the display of the user, it may require that the page containing the widget requires scrolling of the hosting page. The default behavior when a user is using the Widget, is to scroll the hosting page to the top of the widget to aid usability. To disable this, set autoscroll to false. This property will be false if options.fixed is true.
options.sharingurlstringThe hosting URL containing the widgetWhen using Social Sharing, this is the URL that people will share on Social Media to bring them to your campaign. If sharing is an empty string, it will use the hosting page (containing the widget) as the URL.
options.fixedbooleanfalseUsually the widget will change size automatically to fit the content of the engine and avoid scrollbars. If this is set to true, then the widget height will be persistent and will not change. When using this option, the options.height value should be set to anything other than “auto”. If the engine height is larger than height value, scrollbars will be used to navigate.
options.widthstring“100%”The width of the widget. Can be set to a CSS measurement such as “%” or “px” for example.


Once a Widget is set up, you must load it. You may load the widget at any time.

Note: Be sure to set up any of the callbacks below before loading so that you may catch all events.


Event Callbacks


Once widget.load() has been called, this will load and initialize the widget. When the widget has completed this process, it will invoke an optional onReady callback.

widget.onReady = function (event) {
   // loaded and ready to use
   console.log(event.type); // “ready”
   console.log(; // {}


Once widget.load() has been called, this will load and initialize the widget. Any fatal errors occurring after that point will invoke an optional onError callback.

widget.onError = function (event) {
   throw new Error(event.message);


Once the game has been completed and the user is looking at the last screen. It also provides a data object describing what occurred in the game.

Note: if you want to act on this, you may want to give a timeout inside the callback so that the user has time to read the End Screen as it occurs instantly when reaching the last screen. You may also use onClose.

widget.onComplete = function (event) {
   console.log(event.type); // “complete”
   console.log(; // {}
   console.log("Users Score was" +;


Occurs when the Engine has resized, provides the height as a pixel value.

widget.onResize = function (event) {
   console.log(event.type); // “resize”
   console.log(; // {}
   console.log("Application Height:" +;


The application may be configured with a dedicated close button which allows the user to implicitly close the experience. If this button is configured and the user interacts with it, then the close event will be dispatched. This is a good time to destroy the widget from your page and ends the widget lifecycle.

widget.onClose = function () {


When the user interacts (touch/click) with the loaded application for the first time.

widget.onFirstInteraction = function () {
   console.log("User interacted with the Application for the first time");


Occurs when the Application has changed route within the widget. (Navigates between screens). The event may or may not contain a data object depending on the context.

widget.onRouteChange = function (event) {
   console.log(event.type) // “routechange”
   console.log( // {} or undefined
   console.log("User interacted with the Application for the first time");


Occurs when the Application is trying to scroll back to the top of the page. Can be used on the parent page to make sure the scroll is not fired (CORS) or needs to be adjusted. The event does not contain a data object.

widget.onScrollToTop = function () {
   console.log("Scroll To Top");


Here is a list of the key metrics that can be used depending on the type of game:

data.gameMetrics.CurrentAttemptThe attempts when of the user once he completed the game.
data.gameMetrics.prizeIDThe prize ID.
data.gameMetrics.prizeImageThe prize image.
data.gameMetrics.prizeNameThe prize name.
data.gameMetrics.totalPossibleAttemptsThe total amount of possible attempts.
data.gameMetrics.userWontrue/false depending on the user status.
data.gameMetrics.scoreThe total amount of aggregate points that this user completes the game with.


data.credentials.isPreviewModeCheck if the game is in preview mode.
data.credentials.projectIDThe App id of the current app played.
data.credentials.projectLanguageThe language of the project in the widget (en, fr).
data.credentials.projectName The name of the app.
data.credentials.projectTypeThe type of app (quiz, memory...).
data.credentials.publisherIDThe publisher id.
data.credentials.sessionIDThe session id of the current player.

Updated on: 18/04/2024

Was this article helpful?

Share your feedback


Thank you!