This article is also available in:

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

<html>
<head>
   <!-- Include the bundles -->
   <script src="https://cdn-apps.drimify.com/prod/widget/index.js" type="text/javascript"></script>

   <!-- Setup the widget on page load -->
   <script>
       window.addEventListener('load', function () {
           var widget = DigitaService.Widget.Create({
               autoscroll: true,
               element: 'gamification-widget',
               engine: 'https://apps.drimify.com/XBs15jKF/',
               fixed: false,
               height:['auto'],
               sharingurl: 'https://apps.drimify.com/XBs15jKF/',
               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) {};
           widget.load();
       });
   </script>
</head>
<body>
<div id="gamification-widget"></div>
</body>
</html>

Setup

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

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

Setup Options

Required

Option	Type	Description
options.element	string - HTMLElement	The 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.engine	string	The absolute URL to the application that will be loaded into the widget.

Optional

Option	Type	Default	Description
options.height	string	auto	The 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.autoscroll	boolean	true	Depending 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.sharingurl	string	The hosting URL containing the widget	When 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.fixed	boolean	false	Usually 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.width	string	“100%”	The width of the widget. Can be set to a CSS measurement such as “%” or “px” for example.

Load

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.

widget.load();

Event Callbacks

onReady

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(event.data); // {}
};

onError

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);
};

onComplete

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(event.data); // {}
   console.log("Users Score was" + event.data.gameMetrics.score);
};

onResize

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

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

onClose

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 () {
   DigitaService.Widget.Destroy();
};

onFirstInteraction

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");
};

onRouteChange

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(event.data) // {} or undefined
   console.log("User navigated to a new screen");
};

onScrollToTop

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");
};

Metrics

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

Key	Description
data.gameMetrics.CurrentAttempt	The attempts when of the user once he completed the game.
data.gameMetrics.prizeID	The prize ID.
data.gameMetrics.prizeImage	The prize image.
data.gameMetrics.prizeName	The prize name.
data.gameMetrics.prizeRef	The prize reference.
data.gameMetrics.totalPossibleAttempts	The total amount of possible attempts.
data.gameMetrics.userWon	true/false depending on the user status.
data.gameMetrics.score	The total amount of aggregate points that this user completes the game with.

Credentials

Key	Description
data.credentials.isPreviewMode	Check if the game is in preview mode.
data.credentials.projectID	The App id of the current app played.
data.credentials.projectLanguage	The language of the project in the widget (en, fr).
data.credentials.projectName	The name of the app.
data.credentials.projectType	The type of app (quiz, memory...).
data.credentials.publisherID	The publisher id.
data.credentials.sessionID	The session id of the current player.

Error Handling

There are two primary ways to detect errors and retrieve information about issues occurring within the widget:

onError Callback

The onError callback captures any fatal errors that occur after the widget is loaded. This can be useful to identify when a page does not exist or if a critical failure happens.

widget.onError = function (event) {
    if (typeof event.data.message !== 'undefined') {
        switch (event.data.message) {
            default:
                // Do nothing
                break;
            case 'ERR_15':
                console.log("Page doesn't exist");
                break;
        }
    }
};

onRouteChange Callback

The onRouteChange callback is triggered when the application navigates between different screens inside the widget. This is useful for tracking errors related to application state and content availability.

widget.onRouteChange = function (event) {
    if (typeof event.data.errorCode !== 'undefined') {
        switch (event.data.errorCode) {
            default:
                // Do nothing
                break;
            case 'ERR_01':
                console.log("No plan available");
                break;
            case 'ERR_02':
                console.log("Content is not yet available");
                break;
            case 'ERR_03':
                console.log("Content has expired");
                break;
            case 'ERR_04':
                console.log("No more views");
                break;
            case 'ERR_05':
                console.log("Security error");
                break;
            case 'ERR_07':
                console.log("Application not published");
                break;
            case 'ERR_08':
                console.log("Premium Application not available");
                break;
            case 'ERR_09':
                console.log("Session Uid not detected");
                break;
            case 'ERR_10':
                console.log("Session Uid already used");
                break;
            case 'ERR_11':
                console.log("Plan not activated");
                break;
            case 'ERR_12':
                console.log("Wrong data received");
                break;
            case 'ERR_13':
                console.log("SSO call has failed");
                break;
            case 'ERR_14':
                console.log("Language unavailable");
                break;
        }
    }
};

By using both onError and onRouteChange, you can effectively track and handle issues that might occur within the widget, ensuring a better user experience.

Updated on: 28/02/2025

Was this article helpful?

Thank you!