DFC Widget Integration Guide & Playground

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

1. How to Use

To embed the widget on your site, include the following scripts in your HTML file, preferably at the end of the <body> tag. These URLs point to the staging environment.

<!-- DFC Widget Scripts -->
<script src="https://staging.widget.game.dapp.expert/runtime.js"></script>
<script src="https://staging.widget.game.dapp.expert/polyfills.js"></script>
<script src="https://staging.widget.game.dapp.expert/main.js"></script>

Widget API

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

Core Methods

window.dfcGame.init(config): Promise<void>: Initializes and renders the widget on the page. It takes an optional configuration object.
window.dfcGame.destroy(): void: Destroys the widget instance and removes it from the DOM.
window.dfcGame.restart(config): Promise<void>: Restarts the widget with the same or updated configuration.
window.dfcGame.waitForReady(timeout): Promise<void>: Waits for the widget API to be fully ready. Timeout in milliseconds (optional).

Screen Navigation

window.dfcGame.openPlayerScreen(): void: Opens the player profile screen within the widget.
window.dfcGame.openCharacterScreen(): void: Opens the character management screen within the widget.
window.dfcGame.openStorageScreen(): void: Opens the storage/inventory screen within the widget.
window.dfcGame.openQuestsScreen(): void: Opens the quests screen within the widget.
window.dfcGame.close(): void: Closes the widget if it's currently open.

Properties

window.dfcGame.initialized: boolean: A read-only property that indicates if the widget has been successfully initialized.
window.dfcGame.isReady: boolean: A read-only property that indicates if the widget API is ready for use.
window.dfcGame.apiUrl: string: The current API URL being used by the widget (read-only).
window.dfcGame.setLocale(locale: string): void: Sets the locale of the widget.
window.dfcGame.locale: string | undefined: The current locale of the widget (read-only).
window.dfcGame.appLangs: string[]: The available languages for the widget (read-only).

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`	string	URL for the "WIKI" link in the widget's footer. If not provided, 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
`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
`defightLink`	string	URL for the "DeFight" link in the widget's mobile toolbar. If provided, the "DeFight" icon becomes a clickable link.	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']

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.

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.

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:

Always check window.dfcGame.isReady or use await window.dfcGame.waitForReady() before calling init()
Never call init() immediately after script load - this causes NG0908 errors
Implement retry logic for better user experience
Use proper error handling to catch initialization failures

DFC Game Widget Integration Guide & Playground

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

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

Миграция

Breaking Changes