Widget Widget

Embeddable widget for end-users: view points, tier, achievements, redeem rewards. Floating icon + modal; embed in your website.

Two modes:

• API Key: Pass apiBaseUrl, apiKey, externalId (or userId). Widget calls API with Bearer + X-User-Id. Prefer loading apiKey from backend/session.
• Token (Verify URL): Pass tenantSlug + getUserToken(). Widget sends X-User-Token; Engine backend calls tenant verify URL to get external_id.

Widget UI

Click an image to view full size

Widget Points Tier Achievements Leaderboard Rewards Notifications Campaign Spin

Token verification — Enable to integrate Widget (Token mode)

When using the Widget without exposing the API Key in the browser (e.g. users log in with your session/JWT), you must enable Token verification and configure it correctly. This is the required mode to embed the Widget on your site securely.

What token verify is and why it’s needed

Token verification means: the Widget in the browser sends a token issued by your system (session id, JWT, etc.) in every request to GamifyEngine via the X-User-Token header. The GamifyEngine backend does not store an API Key per user; instead it calls your verify URL (configured in Client Admin), sending that token. Your backend validates the token and returns external_id (the user id in your system). The Engine uses external_id to find or create the user in Gamify and serve the widget request. As a result:

• The API Key never appears on the frontend — more secure.
• Users are authenticated by your system (session/JWT you control).
• The Widget only needs a getUserToken() function that returns the current token (e.g. from localStorage/session after login).

You must enable Token verification in Client Admin (Settings → Widget & Auth) and set the Verify URL, method, header to send the token, and the path to external_id in the response. If disabled or misconfigured, the Widget in token mode will get errors (401, TENANT_VERIFICATION_NOT_CONFIGURED, TOKEN_VERIFICATION_FAILED).

How to integrate (summary)

1. Client Admin: Go to Settings → Widget & Auth → enable “Enable token verification for widget” → set Verify URL (your backend, e.g. https://api.tenant.com/auth/verify), Method (GET/POST), header to send token (e.g. Authorization: Bearer {{token}}), Timeout, and Path to external_id in JSON response (e.g. user_id if response is {"user_id":"usr_123"}). Save.
2. Your backend: Implement the verify endpoint: receive the request with the token (in the header per config), validate the token (session/JWT), return JSON with the field that contains external_id (or the field you set in “Path to external_id”, e.g. user_id). Return 4xx/5xx if the token is invalid.
3. Frontend (client): After login, store the token (localStorage, sessionStorage, or in-memory). When mounting the Widget, pass apiBaseUrl, tenantSlug, and getUserToken (function that returns the current token). The Widget will send this token in the X-User-Token header on each API call.

Widget & Auth — Token verification in Client Admin.

Flow: Client → Gamify → Your backend (verify)

When the Widget uses token mode, the flow is:

sequenceDiagram
  participant C as 1. Client (Browser)
getUserToken()
  participant G as 2. GamifyEngine
/v1/widget/:tenantSlug
  participant B as 3. Your backend
(Verify URL)
  C->>G: ① Request + X-User-Token
  G->>B: ② Call Verify URL + token
  B->>G: ③ 200 + JSON (external_id)
  Note over G: ④ Identify user, fetch Widget data
  G->>C: ⑤ Return Widget data
            

Flow: Widget sends token → Engine calls your Verify URL → Backend returns external_id → Engine Identifies user → returns data to Client.

Sample client code (store token, get token, mount Widget)

After the user logs in, store the token (e.g. JWT or session id) in localStorage, sessionStorage, or app state. Provide a getUserToken() function to the Widget; the Widget calls it when it needs to send a request and puts the value in the X-User-Token header.

// ─── After successful login (e.g. from API /auth/login) ───
var token = response.accessToken;  // or response.sessionId, ...
localStorage.setItem('my_app_token', token);

// ─── Function to get token for Widget (can return Promise) ───
function getUserToken() {
  return localStorage.getItem('my_app_token') || null;
}

// ─── Mount Widget in Token mode (no apiKey) ───
GamifyWidget.mount({
  apiBaseUrl:  'https://api.gamifyengine.com',
  tenantSlug:  'my-tenant',
  getUserToken: getUserToken,
  theme:       'cyberpunk',
  fabPosition: 'right-bottom',
  container:   '#gamify-widget-root',
});

// On logout: clear token and optionally unmount widget
// localStorage.removeItem('my_app_token');

If the token is in an HttpOnly cookie, the frontend cannot read it; your backend must then expose an endpoint that returns the token/session for the page, or use a proxy. For token in memory/state (e.g. React): pass getUserToken: () => authState.token.

CDN: https://gamify-widget.pages.dev/gamify-widget.umd.js and gamify-widget.css.

GamifyWidget.mount({
  apiBaseUrl: 'https://api.gamifyengine.com',
  apiKey: 'YOUR_API_KEY',
  externalId: 'USER_ID_CLIENT',
  container: '#gamify-widget-root'
});

Quick embed steps

1. Add <div id="gamify-widget-root"></div> to your page (e.g. after user login).
2. Load React 18 (production) and widget files from CDN: gamify-widget.umd.js, gamify-widget.css.
3. Call GamifyWidget.mount({ apiBaseUrl, apiKey, externalId, container: '#gamify-widget-root' }). externalId is your system’s user id; the widget will call Identify to get or create the user.

Step-by-step demo code

Follow the steps below (or copy the code blocks) to embed the Widget the same way as the demo-app. Once you have apiBaseUrl, apiKey, and externalId (your user id), you only need two steps: load the script → call mount.

Step 1 — Prepare HTML (load scripts)

In <head> or before </body>: add the widget polyfill, widget CSS, React 18, then the UMD script. The widget signals readiness via the gamify:ready event.

<!-- Widget polyfill (production) -->
<script>globalThis.process = { env: { NODE_ENV: 'production' } };</script>
<link rel="stylesheet" href="https://gamify-widget.pages.dev/gamify-widget.css" />
<script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
<script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
<script
  src="https://gamify-widget.pages.dev/gamify-widget.umd.js"
  onload="(function(){
    var gw = globalThis.GamifyWidget;
    if (gw && typeof gw.mount !== 'function' && gw.default && typeof gw.default.mount === 'function') {
      globalThis.GamifyWidget = gw.default;
    }
    globalThis.dispatchEvent(new Event('gamify:ready'));
  })()"
></script>

Step 2 — Call mount when script is loaded

Option A — Vanilla HTML: when the DOM is ready, wait for gamify:ready (or check that GamifyWidget exists), then call GamifyWidget.mount(...). If you omit container, the widget renders as a floating icon + modal.

<script>
(function() {
  var apiBaseUrl = 'https://api.gamifyengine.com';
  var apiKey     = 'YOUR_API_KEY';
  var externalId = 'user-123';

  function doMount() {
    globalThis.GamifyWidget.mount({
      apiBaseUrl:  apiBaseUrl,
      apiKey:     apiKey,
      externalId:  externalId,
      theme:      'cyberpunk',
      fabPosition: 'right-bottom',
    });
  }

  if (globalThis.GamifyWidget && typeof globalThis.GamifyWidget.mount === 'function') {
    doMount();
  } else {
    globalThis.addEventListener('gamify:ready', doMount, { once: true });
  }
})();
</script>

Option B — Inside React (as in demo-app): in a component that has config (apiBaseUrl, apiKey) and user (id), use useEffect to mount when user/config change; in cleanup call instance.unmount().

useEffect(function() {
  if (!config || !user) return;
  var instance = null;

  function doMount() {
    instance = globalThis.GamifyWidget.mount({
      apiBaseUrl:  config.gamifyApiUrl,
      apiKey:     config.gamifyApiKey,
      externalId:  user.id,
      tenant:      config.gamifyTenant || undefined,
      theme:      'cyberpunk',
      fabPosition: 'right-bottom',
      showToasts:  true,
    });
  }

  if (globalThis.GamifyWidget) {
    doMount();
  } else {
    globalThis.addEventListener('gamify:ready', doMount, { once: true });
  }

  return function cleanup() {
    globalThis.removeEventListener('gamify:ready', doMount);
    if (instance && typeof instance.unmount === 'function') instance.unmount();
  };
}, [user?.id, config?.gamifyApiUrl, config?.gamifyApiKey, config?.gamifyTenant]);

Step 3 — Verify

Open the page → log in (or set externalId correctly) → the widget icon appears at bottom-right → click to open the modal (points, tier, rewards). You can download demo-app.zip to run the full app (React + Node backend) and use the "Widget Demo" tab.

Mount parameters

apiBaseUrl (required), apiKey or tenantSlug+getUserToken (token mode), externalId or userId, container (selector). Optional: metadata (displayName, ...), fabPosition (e.g. right-bottom).