DFC Game Widget Integration Guide & Playground

This page serves as a live documentation and testing environment for the DFC Game Widget.

Current API URL: Loading...

[0.9.2] - Текущая версия

Дата: 04.08.2026 | Тип: patch

Нововведения

Миграция

Миграция не требуется.

Breaking Changes

Отсутствуют.

Полная история изменений доступна в versions.md

1. How to Use

To embed the widget on your site, include resource hints in your HTML <head> and scripts at the end of the <body> tag. These URLs point to the staging environment.

<!-- DFC Widget Scripts -->
<link rel="preconnect" href="https://staging.widget.game.dapp.expert" crossorigin>
<link rel="preconnect" href="https://staging.api.game.dapp.expert" crossorigin>
<link rel="dns-prefetch" href="//staging.widget.game.dapp.expert">
<link rel="dns-prefetch" href="//staging.api.game.dapp.expert">
<script src="https://staging.widget.game.dapp.expert/runtime.js?v=BUILD_VERSION"></script>
<script src="https://staging.widget.game.dapp.expert/polyfills.js?v=BUILD_VERSION"></script>
<script src="https://staging.widget.game.dapp.expert/main.js?v=BUILD_VERSION"></script>

Widget API

The scripts expose a global window.dfcGame object with the following API:

Core Methods

Screen Navigation

Properties

Runtime Debug Methods

These methods are intended for local runtime diagnostics in the lobby timed reward flow. They do not require reinitializing the widget, they reset automatically after window.dfcGame.restart(), window.dfcGame.destroy(), or a full page reload, and they do not change the widget's regular init configuration.

window.dfcGame.enableTimedRewardDebugLoop();
window.dfcGame.getTimedRewardDebugLoopState(); // true
window.dfcGame.disableTimedRewardDebugLoop();

2. Configuration Options

The init function accepts a configuration object with the following optional properties:

Property Type Description Default
hostElementSelector string CSS selector for the HTML element where the widget will be rendered. 'body' (appended)
userCookieName string Name of the cookie that stores the authenticated user's token. 'user_token_dev'
guestCookieName string Name of the cookie that stores the guest user's token. 'guest_token_dev'
wikiUrl Record<string, string> Map of wiki URLs per language (e.g., { ru: '...', en: '...' }). If omitted or empty, the link is hidden. undefined
logoUrl string URL for the logo in the widget's footer. If provided, the logo becomes a clickable link. undefined
settingsUrl string URL for the host site's account settings page opened from the header avatar. 'https://devf.dapp.expert/settings'
onLoginClick function A callback function to be executed when the user clicks the "Login" button. Overrides the default `window.dapp.openLogin` behavior. undefined
onSignupClick function A callback function to be executed when the user clicks the "Sign Up" button. Overrides the default `window.dapp.openRegistration` behavior. undefined
onNavigate function Host callback invoked by Meme Locator before its default navigation. Return false after your site handles the destination with its SPA router; otherwise the widget calls window.location.assign(url) in the current tab. undefined
defightLink Record<string, string> URLs of the DeFight landing page by locale. The widget renders the URL matching its current locale; invalid, missing, or incomplete values use the canonical DeFight landing page. 'https://dapp.expert/dfc/widget-landing'
dappApiUrl string Base URL for Dapp (site) API, used by the Meme Locator. If omitted, apiUrl is used. undefined
referralLinkPattern string Referral link URL template. Must include {referralId} placeholder. undefined
bugReportRecaptchaSiteKey string Google reCAPTCHA v2 Checkbox site key for bug report form. undefined
svgSpritePath string Path to a custom SVG sprite file. (Internal path)
locale string Preferred locale for internationalization (e.g., 'en'). Browser's default
appLangs string[] Array of available languages for the application. (e.g., 'en, ru') ['en', 'ru']

Note: runtime debug helpers such as window.dfcGame.enableTimedRewardDebugLoop() are not part of the init(config) payload. They are temporary console-driven switches for local animation debugging only.

3. Host Site Integration (Authentication)

The widget integrates with your site's authentication system by passing callback functions in the initialization configuration. You must provide `onLoginClick` and `onSignupClick` functions in the config object passed to `window.dfcGame.init()`.

window.dfcGame.init({
  // ... other config options
  onLoginClick: () => {
    console.log('Host site: onLoginClick triggered');
    alert('Host site: Login modal would open here.');
  },
  onSignupClick: () => {
    console.log('Host site: onSignupClick triggered');
    alert('Host site: Registration modal would open here.');
  }
});

The widget will call these functions when the user clicks on the "Log In" or "Sign Up" buttons within the widget.

Host Navigation Callback

Provide onNavigate when the host site must handle a Meme Locator "Visit" request with its own SPA router. The callback receives the destination URL and context. Return false only after the host has handled the navigation; this prevents the default window.location.assign(url) fallback in the current tab.

The configuration property has the following TypeScript contract:

onNavigate?: (payload: {
  url: string;
  source: 'meme-locator';
  title?: string;
  type?: string;
  itemSlug?: string;
  targetName?: string;
  targetGroup?: string;
}) => boolean | void;
window.dfcGame.init({
  // ... other config options
  onNavigate: ({ url, source }) => {
    const target = new URL(url, window.location.origin);

    if (source === 'meme-locator' && target.origin === window.location.origin) {
      // Replace with the host site's SPA router API.
      hostRouter.navigate(`${target.pathname}${target.search}${target.hash}`);
      return false; // Host handled navigation; prevent the widget fallback.
    }
  }
});

When the callback does not return false, the widget uses window.location.assign(url). Use that fallback for destinations that the host router does not own.

Widget Loaded Event

The DFC Game Widget dispatches a custom widgetLoaded event to the host page once it has been fully initialized and is ready for interaction. This event is a reliable signal that the widget's internal services are operational, initial data is loaded, and the UI is fully rendered.

This event is particularly useful for controlling host-site elements, such as hiding a splash screen or preloader, that are displayed while the widget is loading.

document.addEventListener('widgetLoaded', () => {
  console.log('DFC Widget is fully loaded!');
  // Add your logic here to hide a splash screen, enable buttons, etc.
  // For example:
  // document.getElementById('my-splash-screen').style.display = 'none';
});

The event is a standard CustomEvent with bubbles: true and composed: true, meaning it will propagate up the DOM tree and traverse Shadow DOM boundaries, making it accessible from the main document.

4. Live Playground

Use the controls below to configure and initialize the widget in the container at the bottom of the page.

Initial Configuration

Authentication State

Current Status: Checking...

Note: After changing auth state, you must Restart the widget to see the effect.

Actions





Widget not loaded yet

Quest Test Tools (DEV)

Uses Auth Token from Authentication State.

Quest tools idle

5. IMPORTANT: Safe Integration for Production

To prevent NG0908 errors on first load, always wait for the widget API to be ready:

Recommended Integration Code:

<script>
  document.addEventListener('DOMContentLoaded', async function() {
    // Wait for widget API to be ready (recommended for production)
    if (window.dfcGame && window.dfcGame.waitForReady) {
      try {
        await window.dfcGame.waitForReady(10000); // 10 second timeout
        
        const widget = await window.dfcGame.init({
          hostElementSelector: '#your-widget-container',
          onLoginClick: () => {
            // Your login logic here
            console.log('Login clicked');
          },
          onSignupClick: () => {
            // Your signup logic here  
            console.log('Signup clicked');
          }
        });
        
        console.log('DFC Widget initialized successfully');
      } catch (error) {
        console.error('Failed to initialize DFC Widget:', error);
        
        // Retry logic (optional)
        setTimeout(async () => {
          try {
            await window.dfcGame.init();
            console.log('DFC Widget initialized on retry');
          } catch (retryError) {
            console.error('Widget initialization failed on retry:', retryError);
          }
        }, 1000);
      }
    } else {
      console.error('DFC Widget not available');
    }
  });
</script>

Alternative: Polling Method (for older browsers)

<script>
  document.addEventListener('DOMContentLoaded', function() {
    function initDfcWidget() {
      if (window.dfcGame && window.dfcGame.isReady) {
        // Widget API is ready, safe to initialize
        window.dfcGame.init({
          hostElementSelector: '#your-widget-container',
          onLoginClick: function() {
            console.log('Login clicked');
          },
          onSignupClick: function() {
            console.log('Signup clicked');
          }
        }).then(function() {
          console.log('DFC Widget initialized successfully');
        }).catch(function(error) {
          console.error('Failed to initialize DFC Widget:', error);
        });
      } else {
        // Widget not ready yet, wait and retry
        setTimeout(initDfcWidget, 100);
      }
    }
    
    // Start checking for widget readiness
    initDfcWidget();
  });
</script>

Key Points: