Back to Details

game-distribution-js-sdk

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

GameDistribution JavaScript SDK

GameDistribution JavaScript SDK

Overview

概述

GameDistribution exposes a single browser SDK (
window.gdsdk
) configured via a global 
window.GD_OPTIONS
object. The SDK loads, fires lifecycle events through a single 
onEvent
callback, and exposes promise-returning methods to preload and show ads. The native SDK supports:
  • Initialization with a 
    gameId
    and a single 
    onEvent
    callback
  • Interstitial ads (
    gdsdk.showAd()
    )
  • Rewarded ads (
    gdsdk.preloadAd('rewarded')
    + 
    gdsdk.showAd('rewarded')
    )
  • Display banners (
    gdsdk.showAd('display', { containerId })
    )
  • Lifecycle pause/resume signals via 
    SDK_GAME_PAUSE
    / 
    SDK_GAME_START
    events
No player auth, storage, payments, leaderboards, or social APIs. External-link navigation should also be avoided on this platform.
GameDistribution 提供统一的浏览器 SDK（
window.gdsdk
），通过全局 
window.GD_OPTIONS
对象进行配置。该 SDK 加载后会通过单个 
onEvent
回调触发生命周期事件，并提供返回 Promise 的方法来预加载和展示广告。原生 SDK 支持：
  • 使用 
    gameId
    和单个 
    onEvent
    回调进行初始化
  • 插屏广告（
    gdsdk.showAd()
    ）
  • 激励广告（
    gdsdk.preloadAd('rewarded')
    + 
    gdsdk.showAd('rewarded')
    ）
  • 展示横幅广告（
    gdsdk.showAd('display', { containerId })
    ）
  • 通过 
    SDK_GAME_PAUSE
    / 
    SDK_GAME_START
    事件提供暂停/恢复信号
该平台不提供玩家身份验证、存储、支付、排行榜或社交 API。此外，应避免在此平台上使用外部链接导航。

Installation

安装

Append the SDK script to the page after defining 
window.GD_OPTIONS
. The script URL is fixed:
js
const SDK_URL = 'https://html5.api.gamedistribution.com/main.min.js';

function loadScript(src) {
    return new Promise((resolve, reject) => {
        const script = document.createElement('script');
        script.src = src;
        script.onload = resolve;
        script.onerror = reject;
        document.head.appendChild(script);
    });
}
The SDK exposes itself as 
window.gdsdk
once the 
SDK_READY
event fires.
在定义 
window.GD_OPTIONS
后，将 SDK 脚本追加到页面。脚本 URL 固定：
js
const SDK_URL = 'https://html5.api.gamedistribution.com/main.min.js';

function loadScript(src) {
    return new Promise((resolve, reject) => {
        const script = document.createElement('script');
        script.src = src;
        script.onload = resolve;
        script.onerror = reject;
        document.head.appendChild(script);
    });
}
SDK_READY
事件触发后，SDK 会以 
window.gdsdk
的形式暴露。

Initialization

初始化

GameDistribution is configured by assigning 
window.GD_OPTIONS
BEFORE the SDK script is appended. The only required field is 
gameId
— your GameDistribution game GUID. All lifecycle and ad events arrive through the single 
onEvent(event)
callback.
js
const options = {
    gameId: 'YOUR_GAME_ID'
};

let platformSdk = null;
let isInitialized = false;
let currentAdvertisementIsRewarded = false;

const listeners = {
    interstitialStateChanged: [],
    rewardedStateChanged: [],
    bannerStateChanged: [],
    pauseStateChanged: [],
    audioStateChanged: []
};

function emit(name, payload) {
    listeners[name].forEach((cb) => cb(payload));
}

function initialize() {
    return new Promise((resolve, reject) => {
        if (isInitialized) {
            resolve();
            return;
        }

        if (typeof options.gameId !== 'string') {
            reject(new Error('Game params are not found'));
            return;
        }

        window.GD_OPTIONS = {
            gameId: options.gameId,
            onEvent(event) {
                switch (event.name) {
                    case 'SDK_READY':
                        platformSdk = window.gdsdk;
                        isInitialized = true;

                        // Optional: show an interstitial immediately once the SDK is ready
                        showInterstitial();
                        resolve();
                        break;
                    case 'SDK_GAME_START':
                        // Ad finished — game should resume
                        if (currentAdvertisementIsRewarded) {
                            emit('rewardedStateChanged', 'closed');
                            // Preload the next rewarded ad right away
                            platformSdk.preloadAd('rewarded');
                        } else {
                            emit('interstitialStateChanged', 'closed');
                        }
                        emit('pauseStateChanged', false);
                        emit('audioStateChanged', true);
                        break;
                    case 'SDK_GAME_PAUSE':
                        // Ad started — game should pause
                        if (currentAdvertisementIsRewarded) {
                            emit('rewardedStateChanged', 'opened');
                        } else {
                            emit('interstitialStateChanged', 'opened');
                        }
                        emit('pauseStateChanged', true);
                        emit('audioStateChanged', false);
                        break;
                    case 'SDK_REWARDED_WATCH_COMPLETE':
                        // Reward must be granted here
                        emit('rewardedStateChanged', 'rewarded');
                        break;
                    case 'SDK_GDPR_TRACKING':
                    case 'SDK_GDPR_TARGETING':
                    default:
                        break;
                }
            }
        };

        loadScript(SDK_URL).catch(reject);
    });
}
Key event names emitted by the SDK through 
onEvent
:
  • SDK_READY
    — SDK is ready, 
    window.gdsdk
    is available.
  • SDK_GAME_PAUSE
    — an ad is starting; pause gameplay and mute audio.
  • SDK_GAME_START
    — an ad has ended (or none was shown); resume gameplay and unmute audio.
  • SDK_REWARDED_WATCH_COMPLETE
    — the user completed a rewarded ad; grant the reward.
  • SDK_GDPR_TRACKING
    , 
    SDK_GDPR_TARGETING
    — GDPR consent signals (no action usually required).
配置 GameDistribution 时，必须在追加 SDK 脚本之前为 
window.GD_OPTIONS
赋值。唯一必填字段是 
gameId
，即你的 GameDistribution 游戏 GUID。所有生命周期和广告事件都通过单个 
onEvent(event)
回调传递。
js
const options = {
    gameId: 'YOUR_GAME_ID'
};

let platformSdk = null;
let isInitialized = false;
let currentAdvertisementIsRewarded = false;

const listeners = {
    interstitialStateChanged: [],
    rewardedStateChanged: [],
    bannerStateChanged: [],
    pauseStateChanged: [],
    audioStateChanged: []
};

function emit(name, payload) {
    listeners[name].forEach((cb) => cb(payload));
}

function initialize() {
    return new Promise((resolve, reject) => {
        if (isInitialized) {
            resolve();
            return;
        }

        if (typeof options.gameId !== 'string') {
            reject(new Error('Game params are not found'));
            return;
        }

        window.GD_OPTIONS = {
            gameId: options.gameId,
            onEvent(event) {
                switch (event.name) {
                    case 'SDK_READY':
                        platformSdk = window.gdsdk;
                        isInitialized = true;

                        // Optional: show an interstitial immediately once the SDK is ready
                        showInterstitial();
                        resolve();
                        break;
                    case 'SDK_GAME_START':
                        // Ad finished — game should resume
                        if (currentAdvertisementIsRewarded) {
                            emit('rewardedStateChanged', 'closed');
                            // Preload the next rewarded ad right away
                            platformSdk.preloadAd('rewarded');
                        } else {
                            emit('interstitialStateChanged', 'closed');
                        }
                        emit('pauseStateChanged', false);
                        emit('audioStateChanged', true);
                        break;
                    case 'SDK_GAME_PAUSE':
                        // Ad started — game should pause
                        if (currentAdvertisementIsRewarded) {
                            emit('rewardedStateChanged', 'opened');
                        } else {
                            emit('interstitialStateChanged', 'opened');
                        }
                        emit('pauseStateChanged', true);
                        emit('audioStateChanged', false);
                        break;
                    case 'SDK_REWARDED_WATCH_COMPLETE':
                        // Reward must be granted here
                        emit('rewardedStateChanged', 'rewarded');
                        break;
                    case 'SDK_GDPR_TRACKING':
                    case 'SDK_GDPR_TARGETING':
                    default:
                        break;
                }
            }
        };

        loadScript(SDK_URL).catch(reject);
    });
}
SDK 通过 
onEvent
发出的关键事件名称：
  • SDK_READY
    ——SDK 已就绪，可以使用 
    window.gdsdk
    。
  • SDK_GAME_PAUSE
    ——广告即将开始；应暂停游戏并静音。
  • SDK_GAME_START
    ——广告已结束或未展示广告；应恢复游戏并取消静音。
  • SDK_REWARDED_WATCH_COMPLETE
    ——用户已完成激励广告；应发放奖励。
  • SDK_GDPR_TRACKING
    、
    SDK_GDPR_TARGETING
    ——GDPR 同意信号，通常无需采取额外操作。

Advertisement

广告

GameDistribution supports interstitial, rewarded, and display banner ads. All ad methods on 
gdsdk
return promises and reject when an ad cannot be served.
You must remember which ad type is currently in flight (interstitial vs rewarded) so the shared 
SDK_GAME_PAUSE
/ 
SDK_GAME_START
events can be routed to the right state.
GameDistribution 支持插屏广告、激励广告和展示横幅广告。
gdsdk
上的所有广告方法都会返回 Promise；当无法投放广告时，对应的 Promise 会被拒绝。
必须记录当前正在进行的广告类型（插屏广告或激励广告），以便将共享的 
SDK_GAME_PAUSE
/ 
SDK_GAME_START
事件分发到正确的状态。

Interstitial

插屏广告

js
function showInterstitial() {
    currentAdvertisementIsRewarded = false;

    if (!platformSdk) {
        emit('interstitialStateChanged', 'failed');
        return;
    }

    platformSdk.showAd().catch(() => {
        emit('interstitialStateChanged', 'failed');
    });
}
GameDistribution does not enforce a minimum delay between interstitials at the SDK level — call 
showAd()
whenever your game logic requires.
js
function showInterstitial() {
    currentAdvertisementIsRewarded = false;

    if (!platformSdk) {
        emit('interstitialStateChanged', 'failed');
        return;
    }

    platformSdk.showAd().catch(() => {
        emit('interstitialStateChanged', 'failed');
    });
}
在 SDK 层面，GameDistribution 不强制规定插屏广告之间的最短间隔——应在游戏逻辑需要时调用 
showAd()
。

Rewarded

激励广告

Rewarded ads must be preloaded before they can be shown. After every rewarded ad completes (
SDK_GAME_START
), preload the next one.
js
function preloadRewarded() {
    if (platformSdk) {
        platformSdk.preloadAd('rewarded');
    }
}

function showRewarded() {
    currentAdvertisementIsRewarded = true;

    if (!platformSdk) {
        emit('rewardedStateChanged', 'failed');
        return;
    }

    platformSdk.showAd('rewarded').catch(() => {
        emit('rewardedStateChanged', 'failed');
    });
}
激励广告必须先预加载，才能展示。每次激励广告完成（
SDK_GAME_START
）后，都要预加载下一个广告。
js
function preloadRewarded() {
    if (platformSdk) {
        platformSdk.preloadAd('rewarded');
    }
}

function showRewarded() {
    currentAdvertisementIsRewarded = true;

    if (!platformSdk) {
        emit('rewardedStateChanged', 'failed');
        return;
    }

    platformSdk.showAd('rewarded').catch(() => {
        emit('rewardedStateChanged', 'failed');
    });
}

Banner

横幅广告

Display banners are rendered into a DOM container whose id is passed to 
gdsdk.showAd('display', { containerId })
. The example below uses the fixed id 
'banner-container'
.
js
const BANNER_CONTAINER_ID = 'banner-container';

function createBannerContainer(position) {
    const container = document.createElement('div');
    container.id = BANNER_CONTAINER_ID;
    container.style.position = 'fixed';
    container.style.left = '0';
    container.style.right = '0';
    container.style.zIndex = '9999';

    if (position === 'top') {
        container.style.top = '0';
    } else {
        container.style.bottom = '0';
    }

    document.body.appendChild(container);
    return container;
}

function showBanner(position) {
    let container = document.getElementById(BANNER_CONTAINER_ID);
    if (!container) {
        container = createBannerContainer(position);
    }

    container.style.display = 'block';

    platformSdk
        .showAd('display', { containerId: BANNER_CONTAINER_ID })
        .then(() => {
            emit('bannerStateChanged', 'shown');
        })
        .catch(() => {
            emit('bannerStateChanged', 'failed');
            container.style.display = 'none';
        });
}

function hideBanner() {
    const container = document.getElementById(BANNER_CONTAINER_ID);
    if (container) {
        container.style.display = 'none';
    }

    emit('bannerStateChanged', 'hidden');
}
position
accepts 
'top'
or 
'bottom'
. Hiding a banner only toggles container visibility — it does not destroy the ad slot.
展示横幅广告会渲染到一个 DOM 容器中，该容器的 id 通过 
gdsdk.showAd('display', { containerId })
传入。以下示例使用固定 id 
'banner-container'
。
js
const BANNER_CONTAINER_ID = 'banner-container';

function createBannerContainer(position) {
    const container = document.createElement('div');
    container.id = BANNER_CONTAINER_ID;
    container.style.position = 'fixed';
    container.style.left = '0';
    container.style.right = '0';
    container.style.zIndex = '9999';

    if (position === 'top') {
        container.style.top = '0';
    } else {
        container.style.bottom = '0';
    }

    document.body.appendChild(container);
    return container;
}

function showBanner(position) {
    let container = document.getElementById(BANNER_CONTAINER_ID);
    if (!container) {
        container = createBannerContainer(position);
    }

    container.style.display = 'block';

    platformSdk
        .showAd('display', { containerId: BANNER_CONTAINER_ID })
        .then(() => {
            emit('bannerStateChanged', 'shown');
        })
        .catch(() => {
            emit('bannerStateChanged', 'failed');
            container.style.display = 'none';
        });
}

function hideBanner() {
    const container = document.getElementById(BANNER_CONTAINER_ID);
    if (container) {
        container.style.display = 'none';
    }

    emit('bannerStateChanged', 'hidden');
}
position
接受 
'top'
或 
'bottom'
。隐藏横幅广告只会切换容器的可见性，不会销毁广告位。

Lifecycle / Audio / Pause

生命周期 / 音频 / 暂停

GameDistribution drives game pause/resume through the same 
SDK_GAME_PAUSE
and 
SDK_GAME_START
events that wrap every ad. There is no separate visibility or audio API — you derive both from these events:
  • On 
    SDK_GAME_PAUSE
    : pause gameplay, mute or duck audio.
  • On 
    SDK_GAME_START
    : resume gameplay, restore audio. This event also fires once after 
    SDK_READY
    if no ad was served.
Combine this with the standard browser visibility events for tab-switch handling, since GameDistribution does not surface those itself:
js
document.addEventListener('visibilitychange', () => {
    const isHidden = document.visibilityState === 'hidden';
    emit('pauseStateChanged', isHidden);
    emit('audioStateChanged', !isHidden);
});

window.addEventListener('blur', () => {
    emit('pauseStateChanged', true);
    emit('audioStateChanged', false);
});

window.addEventListener('focus', () => {
    emit('pauseStateChanged', false);
    emit('audioStateChanged', true);
});
GameDistribution 使用包围每次广告的同一组 
SDK_GAME_PAUSE
和 
SDK_GAME_START
事件来驱动游戏的暂停与恢复。平台不提供独立的可见性或音频 API——两者都需要根据这些事件推导：
  • 收到 
    SDK_GAME_PAUSE
    时：暂停游戏玩法，静音或降低音频音量。
  • 收到 
    SDK_GAME_START
    时：恢复游戏玩法，恢复音频。如果未展示任何广告，该事件也会在 
    SDK_READY
    之后触发一次。
由于 GameDistribution 本身不会提供浏览器可见性事件，应将其与标准浏览器可见性事件结合使用，以处理标签页切换：
js
document.addEventListener('visibilitychange', () => {
    const isHidden = document.visibilityState === 'hidden';
    emit('pauseStateChanged', isHidden);
    emit('audioStateChanged', !isHidden);
});

window.addEventListener('blur', () => {
    emit('pauseStateChanged', true);
    emit('audioStateChanged', false);
});

window.addEventListener('focus', () => {
    emit('pauseStateChanged', false);
    emit('audioStateChanged', true);
});

Storage

存储

GameDistribution does not provide a platform storage API. Use 
window.localStorage
directly for persisting player progress.
GameDistribution 不提供平台存储 API。请直接使用 
window.localStorage
持久化玩家进度。