@orbit-software/sdk

Browser SDK for Orbit/Portal games running in Telegram Mini Apps and regular browsers. It provides authentication-aware API access, profile and balance data, game storage, ads, shop/payments, wages, and the Portal overlay.

Use

import PortalSDK from '@orbit-software/sdk';

await PortalSDK.initialize('BOT_ID', {
  disable_startup_ads: false,
});

PortalSDK.initializeOverlay({
  variant: 'translucent',
  visible: true,
});
PortalSDK.gameReady();

const profile = await PortalSDK.getProfile();
const completed = await PortalSDK.requestRewardAd({
  placementId: 'level-complete',
});

The SDK also exposes the same object as window.PortalSDK and window.CryptoSteamSDK in the UMD build. A browser launch without a Portal session runs in guest mode; call PortalSDK.requestLogin() when sign-in is needed.

Authentication and storage

PortalSDK.getAuthState() returns one of:

• telegram — Telegram initData is used automatically.
• web — a Portal launch code is exchanged for SDK-scoped tokens.
• guest — no account is available; profile, shop, and purchase calls are unavailable.

Guest game progress is kept locally and can be migrated to the account after a Portal login. Use getValue, setValue, removeValue, and getAllKeyValues for game saves. telegramCloudStorage is intended for Telegram-only storage.

Ads

Ads are delivered by the external Orbit ad SDK. Use requestAd() for interstitials and requestRewardAd() for reward flows; both return Promise<boolean>. Startup ads are enabled by default and can be disabled with disable_startup_ads: true in initialize().

When a game runs in an iframe, each ad request sends { type: 'orbit-sdk:ad-start' } to its immediate parent, then { type: 'orbit-sdk:ad-end', result: boolean } when the request finishes. These events bracket the request, including requests that skip showing an ad. The launcher should check both event.source === gameIframe.contentWindow and event.origin against the expected game origin before changing its UI. Hiding the game iframe itself can also hide an ad rendered inside that iframe.

The old direct ad-network controllers are no longer owned by this SDK. isAdEnabled() and getAdsgramController() remain only for backwards compatibility.

Development

pnpm install
pnpm dev              # ESM development build
pnpm dev:confirm      # payment-confirmation app
pnpm test
pnpm typecheck
pnpm lint
pnpm format:fix
pnpm build

pnpm build generates:

• dist/esm — ES module and TypeScript declarations;
• dist/umd — UMD build;
• dist/umd_react — UMD build with the React runtime;
• dist_confirm — single-file payment-confirmation app;
• dist/assets — copied runtime assets.

The source entry point is src/sdk.ts. The public API types are in src/types/sdk.ts.

Build-time configuration

Environment variables are injected during the build, not read from the consumer at runtime:

| Variable | Purpose | Default | | --- | --- | --- | | BASE_URL | SDK API base URL | https://app.portalgames.com/sdk | | ADS_SCRIPT_URL | Orbit ad SDK script URL | none; required for ads | | ASSETS_BASE_URL | Base URL for SDK assets | configure for deployed assets | | IDENTITY_URL | Web-auth identity service | https://id.portalgames.com | | PORTAL_URL | Portal and default login URL | https://portalgames.com | | PORT | Local Vite server port | 3000 |

CI deploys production builds from pushed version tags. Manual deployment targets production only. Do not edit dist; it is generated output.

Launcher-selected dev environment

The production browser bundle can use the dev backend when the game is opened from the dev launcher. Browser launches carry __portal_env=dev in the game URL. Web tutorial launches carry __portal_source=tutorial in both environments for the tutorial ad placement and SDK game analytics. Telegram launches carry a base64url-encoded startapp value: a plain source such as tutorial becomes ?__portal_env=dev&__portal_source=tutorial, while a /games/{id} start path gains the marker and keeps its route and attribution parameters. The SDK reads the marker from tgWebAppStartParam or Telegram init data before authentication, analytics, or API requests and selects the dev Portal, identity, and SDK API URLs together. The Orbit ads script and SDK static assets keep the production bundle's configured URLs. Web auth tokens are stored separately for dev and prod.

The marker only selects a destination; the destination backend still authenticates every request. Dev launches do not emit to the production Google Analytics property; Sentry events carry the selected environment. The launcher-to-SDK format is documented in the workspace CONTRACTS.md.

Release the production SDK bundle before deploying the launcher change. Existing game pages load that production bundle; an older bundle ignores the marker and still calls production.