Requirements
Full integration does not require same-origin hosting. The real requirement is that you can modify the game source code. The game may live on this site, OSS, R2, S3, Cloudflare Pages, or any other cross-origin static host, as long as it can be loaded in an iframe and execute JavaScript.
If the game is only available as a third-party iframe and you cannot modify its source, you usually cannot reliably access internal scores, level data, or game-over state. That is a browser cross-origin limitation, not a Webman-specific limitation.
The current SDK does not require the game page to send gameId or post_id manually. Those identifiers come from the host content page, while the game page only needs to send correct lifecycle events and its own version info.
Integration Flow
- Load the versioned SDK script inside the game page so CDN and browser caches do not keep serving an old file.
- Call ready, start, score, heartbeat, gameOver, and other hooks at the real gameplay checkpoints.
- Enable debug: true or add ?sdk_debug=1 to the game page URL first so you can verify both the outbound event and the host-page feedback.
- Play the game on the front end, then confirm the SDK status, event counters, and leaderboard updates in admin.
When editing a game in admin, the “SDK integration” panel shows the recommended script URL, example event hooks, and version query. Copy that script URL directly and do not strip the version parameter.
<script src="https://bwlot.com/game-sdk/v1/webman-game-sdk.js?version=1794860378"></script>
<script>
const gameSdk = WebmanGame.init({
parentOrigin: 'https://your-domain.com',
debug: true
});
WebmanGame.on('debug', function (entry) {
console.log('[game-sdk-debug]', entry.code, entry.detail || {});
});
gameSdk.ready();
function onFirstPlayerAction() {
gameSdk.start();
}
function onScoreChanged(currentScore, currentLevel) {
gameSdk.score(currentScore, { level: currentLevel });
}
function onGameOver(finalScore, currentLevel) {
gameSdk.gameOver({
score: finalScore,
level: currentLevel,
reason: 'completed'
});
}
function shareRun(finalScore, currentLevel) {
// Call directly from the player's click handler.
return gameSdk.share({
title: 'Webman SDK Demo',
text: 'I scored ' + finalScore + ' at level ' + currentLevel + '.',
challenge: { score: finalScore }
});
}
function finishOrContinue(finalScore, currentLevel) {
// Call only after the player chooses the continue option.
return gameSdk.showAd({ type: 'rewarded', placement: 'continue' }).then(function (result) {
if (result.rewarded) {
resumeRun();
return;
}
onGameOver(finalScore, currentLevel);
});
}
function resumeRun() {
// Restore the game's saved life / checkpoint here.
}
setInterval(function () {
gameSdk.heartbeat();
}, 30000);
</script>
Recommended Events
ready()
Game assets are loaded and the game can accept player input.
start()
Call when the player actually starts interacting, not just when the page loads.
heartbeat()
Call every 15-30 seconds for more accurate active play time.
score(score, payload)
Call when the score changes. Leaderboards depend on this event and payload may include level.
levelStart(payload)
Level-start hook that may include level and score.
levelComplete(payload)
Level-complete hook for multi-level games.
requestCapabilities() / on("capabilities", fn)
Query or retry host capability discovery. The SDK emits a capabilities event when they change; canShowAd() queries when needed.
share(payload)
Ask the host to share the canonical Webman game page. The promise returns shared, cancelled, copied, manual, or failed; challenge.score becomes a ?challenge= value. Without a host bridge, set init({ shareUrl }) to choose the canonical page to share.
canShowAd({ type: 'rewarded', placement: 'continue' })
Preflight only. It returns available and mayNoFill; availability does not guarantee inventory when showAd runs.
showAd({ type: 'rewarded', placement: 'continue' })
Request a continuation reward only. The promise always settles; continue only when result.rewarded is true, otherwise report gameOver. It returns unavailable until a host ad provider is registered.
gameOver(payload)
Call only when the round is truly over; completion stats and leaderboard refreshes depend on it. It is reported once per run; call start({ reset: true }) for a new run. The host no longer interrupts the player on game over.
pause(payload) / resume(payload)
Lifecycle hooks for backgrounding, pause menus, and host flows.
error(payload)
Call when the game detects an internal error or resource failure.
share() and showAd() are host requests, not leaderboard or gameplay analytics events. The host always shares the canonical Webman game page; challenge.score becomes a ?challenge= value and a caller-supplied URL cannot replace the site link. PNG, JPEG, and WebP images are limited to 3 MB. status is one of shared, cancelled, copied, manual, or failed (for example invalid files, with a reason); the attachment result is none, included, dropped, or unsupported; attachmentReason explains why a file was omitted. If file sharing is unavailable, the host falls back to a text link, clipboard, execCommand copy, and finally a manual result containing the Webman URL.
Use requestCapabilities() to retry capability discovery; on("capabilities", fn) receives updates. canShowAd() is a side-effect-free preflight, and available does not guarantee that the provider will still have inventory when showAd() runs.
A host ad adapter may implement its own canShowAd(); it must only inspect availability and must not display an ad or consume frequency quota. A true result still does not guarantee later inventory.
No ad provider is registered in the current deployment, so showAd() safely returns unavailable and never loads a third-party ad by itself. Host integrations must register an explicit allowedPostIds list. The provider receives type, placement, postId, sdkSessionId, signal, and onShown, and returns a Promise. Call onShown() when the ad actually starts; return rewarded: true only after the reward condition is met. The provider must honor signal so it cannot start displaying after a load timeout. The host counts at most one shown ad per postId and SDK session. Loading has a 15-second watchdog and a shown ad has a 120-second watchdog. The host pauses the game only while the ad is shown, and resumes it after timeout or failure.
WebmanGameHost.registerAdAdapter(adapter, { allowedPostIds: [123] }) is the host-side registration signature. If an ad closes without a reward, return { status: "dismissed", shown: true }; for no fill, return { status: "unavailable", reason: "no_fill", shown: false }. The interstitial, preroll, and payments capabilities are currently false; keep those monetization placements disabled until the provider, platform traffic authorization/revenue share, and frequency rules are confirmed.
Ad statuses are normalized to rewarded, dismissed, unavailable, timeout, or failed; only rewarded grants continuation. Common reasons include no_fill, provider_not_ready, host_not_authorized, ad_in_progress, frequency_capped, provider_load_timeout, provider_timeout, and provider_error. The Promise settles even when there is no fill, the provider fails, or a watchdog fires, so gameplay cannot remain stuck.
Do not treat pause, backgrounding, menus, level completion, or ad breaks as game_over. For rewarded continuation, wait for showAd(): continue only when rewarded is true; report gameOver after dismissal, no fill, error, or timeout. Use levelComplete for level clears and gameOver for the true end of the full run.
Testing
For local integration, you can place the game source under public/games/{slug}/ and set game_url to /games/{slug}/index.html in the admin panel. In production, game_url may also point to a cross-origin OSS / R2 / CDN URL. That is a supported deployment model.
SDK Demo https://bwlot.com/games/sdk-demo/index.htmlVerification
- After playtesting on the front end, return to the admin panel and review the SDK status counters.
- If ready, score, or game_over counters increase, events are reaching the site.
- If integration fails, use debug mode first to separate in-game SDK issues from host bridge or backend API issues.
- Opening the raw game HTML only verifies the in-game SDK sender. To verify the host-page receiver, open the game through the actual content page.
Debug Mode
Available Tools
debug: true
Enable debug output directly in init().
?sdk_debug=1
Add ?sdk_debug=1 to the game page URL (inside the iframe) to enable the SDK debug output; host bridge debug is controlled server-side by app.debug and cannot be enabled from a URL.
WebmanGame.debugState()
Inspect hostReady, capabilities, pending events and RPCs, recent message_id values, and the last host feedback. debugEvents() keeps up to 120 entries.
WebmanGame.on('debug', fn)
Pipe debug events into your own in-game debug panel.
enableDebug() / disableDebug()
Toggle debug mode at runtime without reloading the whole game; disabling debug also revokes a debug-only wildcard parentOrigin, so re-run init() to use it again.
Common Debug Phases
post_message
The in-game SDK sent the event.
received
The host-page bridge accepted the event.
rejected
The host page rejected the event, usually with a reason.
session_created
The backend created a play session for the run.
flush_ok
The event was persisted successfully.
api_error
The bridge failed while calling the backend API and needs network/response inspection.
Use on() to listen for host_ready (post_id, sdk_session_id, capabilities), capabilities updates, and pause / resume (with a reason), and off(name, fn) to detach a listener. The host recursively strips known fields such as email, phone, real_name, full_name, display_name, identity documents, address, birth date, and credentials from event payloads. This key-based filter is incomplete, so games must never send personal data.
Host RPCs verify the iframe’s actual origin. If sandboxing gives messages an origin of null, gameplay events can still be reported but sharing and ad requests are rejected. Use a sandbox mode that preserves the source origin only for game hosts you trust.
A real success path should look roughly like: post_message -> received -> session_created -> flush_ok. If session_created still carries game_session_id = 0 or flush_ok shows recorded = null, treat it as a backend failure rather than a frontend success.
Troubleshooting
You see post_message but never received
The in-game SDK sent the event but the host-page bridge never accepted it. Open the game through the actual detail page instead of opening the raw game HTML directly, then confirm the parent page loaded /assets/game-host-bridge.js.
You see received but never session_created / flush_ok
The host page accepted the event but the backend session or event API did not complete successfully. Inspect api_error, the Network response, and the server logs next.
session_created has game_session_id = 0 or flush_ok has recorded = null
Do not treat that as success. It usually means the backend returned a non-200 business code, commonly because game_sessions / game_events / game_scores are missing or out of sync.
A same-origin game keeps showing This game may not load correctly
That is a host-page auto-detection false positive, not necessarily an SDK postMessage failure. Confirm the latest bridge and detail-player scripts are deployed.
You updated the SDK but debugState() or new debug phases are still missing
That usually means an old cached asset is still being served. Make sure the script URL includes a version query and that the release bumped the version value.
Advice for Third-Party Game Developers
If you want your game to be embedded reliably on this site or partner sites, treat embeddability, analytics, and testability as part of the release standard.
Allow safe embedding
Use HTTPS, do not block partner sites with X-Frame-Options or CSP frame-ancestors, and make sure OSS / R2 / CDN delivery is not blocked by hotlink or signature rules.
Define scoring clearly
Call score only when the score truly changes and keep one consistent score unit per run.
Be strict about gameOver
Do not treat blur, pause, ad breaks, level transitions, or menus as the end of a run.
Support mobile devices
Provide responsive layout, touch controls, and orientation guidance, and mark portrait/landscape limits in admin when needed.
Version and regression-test
The SDK exposes WebmanGame.version and sends it as sdk_version automatically; only custom builds need to override init({ version }). Regression-test ready, start, score, gameOver, and debug events.
Respect data boundaries
Do not send player names, emails, or other personal data through the SDK.
- For each release, update the SDK script version query on the game page; init({ version }) is optional because the SDK sends its built-in version automatically.
- When enabling the SDK in a new environment, confirm the backend game SDK table migration has already run.
- During verification, run at least one full ready -> start -> score -> gameOver flow and confirm both the leaderboard and player summary change.
- Call share and rewarded ads directly from a player click handler; do not await image downloads or unrelated work first.
The SDK only sends events to the parent page through postMessage. Identity enrichment, validation, and persistence still happen on the host page and backend. Do not place admin tokens or management APIs inside the game, and do not design the game to call Webman APIs directly.