@wg-igaming/iframe-embed
v0.2.1
Published
Public client SDK to embed the sportsbook iframe with auth, theming, and events
Maintainers
Readme
@wg-igaming/iframe-embed
Public client SDK for embedding the WG-IGAMING sportsbook iframe on any host site.
| Who | What they can do |
|---|---|
| Anyone | Install and use the package (npm install, CDN) by passing required attributes |
| Authorized maintainers only | Edit source, merge PRs, publish new versions |
Runtime access control for embeds is still enforced by the Gateway (apiKey + domain whitelist). Pair with the private @wg-igaming/iframe-core package inside sportsbook repos.
Source: WG-IGAMING/igaming-core
Setting up on a client site? See SETUP.md for a step-by-step guide (HTML, React, Vue, Next.js, auth, events, and troubleshooting).
Access model
Use (public)
No auth token or private registry. Anyone may install and call SportsBook.init({ apiKey, containerId, gatewayUrl, ... }).
Publish / edit / modify (restricted)
Only people with explicit access can change or release this package:
- Source (GitHub) — push/PR rights on
WG-IGAMING/igaming-core(org members/teams you grant) - Registry (npm) — membership on the
@wg-igamingnpm org with publish permission
Unauthorized users cannot overwrite published versions or push package updates. Revoke GitHub and npm org access to remove a maintainer.
Install
No auth token or private registry required for consumers.
npm / yarn / pnpm
npm install @wg-igaming/iframe-embedimport { SportsBook } from "@wg-igaming/iframe-embed";
await SportsBook.init({
apiKey: "client_pk_abc123",
containerId: "sportsbook-container",
gatewayUrl: "https://gateway.yourdomain.com",
});CDN (plain HTML)
After publish, load from unpkg / jsDelivr, or host embed.js yourself:
<div id="sportsbook-container"></div>
<script src="https://unpkg.com/@wg-igaming/iframe-embed/dist/embed.js"></script>
<script>
SportsBook.init({
apiKey: "client_pk_abc123",
containerId: "sportsbook-container",
gatewayUrl: "https://gateway.yourdomain.com",
language: "en",
theme: "dark",
userToken: "jwt_from_client_auth",
onBetPlaced: (bet) => console.log(bet),
onSessionExpired: () => console.log("re-login"),
onError: (err) => console.error(err),
});
</script>Required attributes
| Attribute | Why required |
|---|---|
| apiKey | Identifies the client; Gateway checks it is active |
| containerId | DOM node where the iframe is mounted |
| gatewayUrl | Where to call /api/v1/embed/init |
Everything else (language, theme, userToken, callbacks, …) is optional. The host domain (window.location.origin) is sent automatically and must be whitelisted for that API key or init fails.
1. How to Use
Initialization flow
- Reads
window.location.origin(host domain) POST {gatewayUrl}/api/v1/embed/initwith{ apiKey, domain, language, theme }- Gateway validates API key + domain whitelist → returns
{ iframeUrl, sessionToken, config } - Creates a sandboxed
<iframe>incontainerId - Opens a strict-origin postMessage bridge
- Sends theme / language / userToken; receives bet, resize, error, session events
SportsBook.init(config)
Bootstrap the iframe. Must be called once before other methods.
import { SportsBook } from "@wg-igaming/iframe-embed";
await SportsBook.init({
apiKey: "client_pk_abc123",
containerId: "sportsbook-container",
gatewayUrl: "https://gateway.yourdomain.com",
language: "en",
theme: "dark", // or full ThemeConfig
userToken: "jwt_from_client_auth",
route: "/soccer",
onBetPlaced: (bet) => console.log(bet),
onSessionExpired: () => { /* redirect to login */ },
onError: (err) => console.error(err),
});| Option | Type | Required | Description |
|---|---|---|---|
| apiKey | string | Yes | Client public key (client_pk_…) |
| containerId | string | Yes | Host element id for the iframe |
| gatewayUrl | string | Yes* | Gateway base URL (*or set SPORTSBOOK_GATEWAY_URL) |
| language | string | No | Initial locale |
| theme | ThemeMode \| ThemeConfig | No | Initial theme |
| userToken | string \| null | No | Host-site user JWT |
| route | string | No | Initial deep-link inside sportsbook |
| height | number \| string | No | Fixed height (disables auto-resize apply) |
| query | Record<string, string> | No | Extra iframe query params |
| onReady | () => void | No | Iframe ready |
| onBetPlaced | (bet) => void | No | Bet placed |
| onSessionExpired | () => void | No | Session expired — re-init required |
| onError | (err) => void | No | Error from iframe or init |
| onResize | ({ height }) => void | No | Content height changed |
| onNavigate | (route) => void | No | In-iframe navigation |
SportsBook.updateTheme(theme)
Live theme switch without reload. Accepts "light" | "dark" | "system" or a full ThemeConfig.
SportsBook.updateTheme("light");
SportsBook.updateTheme({ mode: "dark", primaryColor: "#0f0" });SportsBook.updateLanguage(lang)
Live locale switch (e.g. "en", "ar", "fr").
SportsBook.updateLanguage("ar");SportsBook.setUserToken(token)
Pass or refresh the end-user JWT. Pass null to clear.
SportsBook.setUserToken(newJwt);
SportsBook.setUserToken(null);SportsBook.navigate(route)
Deep-link into a sportsbook route.
SportsBook.navigate("/tennis/live");SportsBook.on(event, callback) / SportsBook.off(event, callback)
Subscribe to events from the sportsbook. on returns an unsubscribe function.
| Event | Payload | Description |
|---|---|---|
| ready | — | Sportsbook loaded and bridge ready |
| resize | { height: number } | Content height changed |
| betPlaced | BetData | User placed a bet |
| navigate | string | Route changed inside iframe |
| error | { code, message } | Error inside sportsbook / protocol |
| sessionExpired | — | Session invalid — call init again after re-auth |
const stop = SportsBook.on("betPlaced", (bet) => {
console.log(bet.betId, bet.stake);
});
// later:
stop();
// or:
SportsBook.off("betPlaced", handler);SportsBook.destroy()
Tear down the iframe, remove listeners, and reset SDK state.
SportsBook.destroy();Helpers
| Method | Description |
|---|---|
| SportsBook.isInitialized() | true after a successful init |
| SportsBook.getConfig() | Gateway config object from /embed/init, if any |
Types
ThemeConfig, ThemeMode, ThemeInput, BetData, ErrorPayload, SportsBookInitConfig, SportsBookEvent, SportsBookEventMap, PROTOCOL_VERSION
2. How to Collaborate
This package is the public client half of the iframe protocol. @wg-igaming/iframe-core is the private sportsbook half. Keep their postMessage contracts aligned.
What counts as a public API change
Anything exported from src/index.ts / src/cdn.ts, plus message types in src/types.ts.
Why be careful
| Change | Risk |
|---|---|
| Add method/event | Low — opt-in for clients |
| Update signature / payload | High — breaks host sites and may break iframe-core |
| Delete method/event | High — breaks every integration |
| Change wire protocol | Critical — must ship with a matching @wg-igaming/iframe-core release |
Because this package is public, every published version is permanently downloadable. Prefer additive changes; use major bumps for breaks.
How — add
- Implement in
src/sdk.ts(and bridge/gateway as needed). - Export from
src/index.tsandsrc/cdn.ts. - Document in §1.
- Bump minor version.
- PR → merge →
npm run publish:npm. - Clients upgrade with a normal
npm install @wg-igaming/iframe-embed@latest.
How — update
- Prefer additive / optional fields.
- Breaking changes → major bump + migration notes.
- If postMessage types change, bump
PROTOCOL_VERSIONand release iframe-core in the same window. - Update §1 docs.
How — delete
- Deprecate in README for one minor release when possible.
- Remove exports + docs.
- Major bump + migration note in the PR.
- Publish and announce.
Collaboration checklist
- [ ] Protocol types still match
@wg-igaming/iframe-core - [ ] CDN (
embed.js) and npm entry both expose the change - [ ] README §1 updated
- [ ] Semver bump correct
- [ ]
npm run typecheck && npm run buildpasses
Publish (maintainers only)
Requires:
- Write access to
WG-IGAMING/igaming-core - An npmjs.com account invited to the
@wg-igamingorg with publish rights
cd iframe-embed
npm login
npm run publish:npmAfter publish, anyone can install; only org publishers can release the next version:
npm install @wg-igaming/iframe-embedGranting / revoking maintainers
| Action | Where |
|---|---|
| Allow code changes | GitHub org → team/repo write access on igaming-core |
| Allow npm publish | npm → Organization @wg-igaming → Members → set role with publish |
| Remove access | Remove from GitHub team and npm org |
