Plain JavaScript

A JavaScript library is provided to enable easy integration of the widget into websites. If you are using React, Angular, or Vue, please use the provided wrappers. This guide is for those who do not use any frameworks or if a wrapper has not yet been provided.

Test Mode

With the parameter isTestMode: true, the widget generates test data for itself and does not require a backend connection. This is useful for integrating the UI efficiently without worrying about backend connections. When using the widget with a backend, the isTestMode parameter must be set to false or omitted, and the token parameter must be provided.

Test Mode Example

Simply copy and paste the snippet below onto the page where you want the widget to appear for players. This code will render the widget in test mode. The script elements should be placed at the end of the page, before the closing body tag. Generally, this should be on the page where the games are launched so that the widget appears on top of the games.

<div id="gamityWidgetRoot"></div>
 
<script>
    function initGamityWidget() {
        window.GamityWidget.mount({
            isTestMode: true,
            plainJsIntegration: true,
            openOnRightSide: true,
            hostElementSelector: '#gamityWidgetRoot',
        });
    }
</script>
 
<script
  async
  src="https://cdn-qa.gamity.io/apps/in-game-widget/generic/in-game-widget.js"
  onload="initGamityWidget()"
></script>

The container div determines where the compact widget will render. This does not necessarily mean the widget will appear in that exact location on the screen; see the Positioning section for more details.
The script src element references the external widget JavaScript file. This tag should be placed at the bottom of the page, before the closing </body> tag, but before the mount call.
A separate script tag includes the mount call that renders the widget with the specified parameters. If you are including the widget this way instead of using JavaScript framework wrappers (React, Angular, or Vue), always include the plainJsIntegration: true parameter.

Real Mode

Instead of the isTestMode parameter, you need to provide the token parameter, which contains the JWT token with brand, game, and player information. See more details on its structure in the Parameters section below.

Real Mode Example

<div id="gamityWidgetRoot"></div>
 
<script>
    function initGamityWidget() {
        window.GamityWidget.mount({
            integrationRef: "[PROVIDED_BY_CODEMODITY]",
            token: "[YOUR_SERVER_GENERATED_JWT_TOKEN]",
            language: 'en',
            plainJsIntegration: true,
            openOnRightSide: true,
            hostElementSelector: '#gamityWidgetRoot',
        });
    }
</script>
 
<script
  async
  src="https://cdn-qa.gamity.io/apps/in-game-widget/generic/in-game-widget.js"
  onload="initGamityWidget()"
></script>

Mounting and Unmounting

If you are using a multi-page app without a JavaScript framework (e.g., React, Angular, or Vue), or the widget is placed in an iframe game layer, calling only the mount() function is usually sufficient. If you need an unmounting logic because you are using an SPA and cannot use any JavaScript framework wrappers, an unmount() function is available. Ensure you call it to properly clean up the widget. If any parameters change (e.g., language), unmount and remount the widget.

window.GamityWidget.unmount()

Below is a simplified example of a React wrapper that dynamically creates the script element and calls mount once the script loads.

const HOST_ELEMENT_ID = 'gamityWidgetRoot'
 
// If you are using TypeScript:
declare global {
    interface Window {
        GamityWidget: {
            hostElement: HTMLElement | null,
            mount(mountParams: WidgetParameters): void,
            unmount(): void,
        }
    }
}
 
export function Widget(widgetParameters: WidgetParameters) {
    const mount = useCallback(() => {
        log('Mounting...')
        window.GamityWidget.mount({
            ...widgetParameters,
            hostElementSelector: widgetParameters.hostElementSelector || `#${HOST_ELEMENT_ID}`,
        })
    }, [widgetParameters])
 
    const unmount = () => {
        if (window.GamityWidget) {
            log('Unmounting...')
            window.GamityWidget.unmount()
        }
    }
 
    useEffect(() => {
        if (!window.GamityWidget && !document.getElementById('gamityWidgetScript')) {
            if (!widgetParameters.isTestMode && !widgetParameters.token) {
                log('Missing required parameter: token')
                return
            }
 
            log('Loading the Widget script...')
            const script = document.createElement('script')
            script.id = 'gamityWidgetScript'
            script.type = 'module'
            script.src = `https://cdn-qa.gamity.io/apps/in-game-widget/generic/in-game-widget.js`
            script.onload = mount
            document.head.appendChild(script)
        } else if (window.GamityWidget) {
            mount()
        }
 
        return unmount
    }, [mount, widgetParameters.isTestMode, widgetParameters.token, widgetParameters.environment])
 
    return <div id={HOST_ELEMENT_ID}></div>
}

Alternatively, instead of using the script.onload event, the script also emits a custom event called GamityWidgetScriptLoaded:

<script>
    ... addEventListener('GamityWidgetScriptLoaded', function (){' '}
    {window.GamityWidget.mount({
        integrationRef: '[PROVIDED_BY_CODEMODITY]',
        token: '[YOUR_SERVER_GENERATED_JWT_TOKEN]',
        language: 'en',
        plainJsIntegration: true,
        openOnRightSide: true,
        hostElementSelector: '#gamityWidgetRoot',
    })}
    )
</script>

JavaScript URLs

Positioning

Please see Widget Positioning

Parameters

parameter	type	required	default	description
`isTestMode`	boolean	no	false	If true, the widget will render test data without connecting to the backend API. Useful for testing the UI only.
`token`	string/JWT	only if testMode is false		A JWT token that contains parameters for player and game identification. The exact parameters within the token are described in the next section. The token should be generated on server side using the private signing key provided by Codemodity, to prevent players from tampering with it from the browser.
`language`	string	no	’en’	This can be either a culture-neutral language code, such as `en` or `fr`, or a specific culture variant, such as `en-GB`, `en-US`, `fr-FR`, or `fr-CA`. If the specified culture is not supported, the fallback ‘en’ will be used.
`isDraggable`	boolean	no	true	if true, the players will be able to drag the compact widget anywhere on the screen.
`isCollapsibleOnDesktop`	boolean	no	true	if true, on desktop, the widget will act like on mobile, as a small, at-a-glance widget that can be expanded into full view upon clicking on it. If false, the expanded full view will be the default, that cannot be closed.
`openOnRightSide`	boolean	no	true	if true, the expanded leaderboard will open on the right side of the screen.

Token parameters

Some parameters are passed as a JWT token so that those data cannot be tampered with. The signing algorithm is HS256. The signing key is provided by Codemodity separately, in a secure way. The token must be generated on the server side for security reasons. You may use one of the JWT libraries listed here: https://jwt.io/libraries

parameter	type	required	description
`brandId`	string	yes	The unique Id of a brand the player belongs to (e.g. HAPPYLUKE). `brandId` and `playerId` together should be unique.
`playerId`	string	yes	The Id of the player in the brand/EC system. `brandId` and `playerId` together must be unique.
`playerAlias`	string	no	The nickname of the player that the leaderboard displays. e.g “casinoking82”.
`gameId`	string	yes	Unique Id of the Game that the player launched.
`currency`	string	yes	Currency of the player.
`segmentation`	object	no	Optional array for player segmentation, determined by the client system. See an example in the Segmentation section below.
`exp`	seconds since Epoch	yes	Standard JWT expiration time. It is up to the discretion of the JWT token generator to pick a proper expiration date. This token will be used only once per widget launch, at the time the launch happens, thus it can be very short lived.

Segmentation

Example segmentation object:

"segmentation": {
    "codes": [
      "Tier-2",
      "VIP",
	  "Gold"
    ]
  }

React Positioning