@hyve-sdk/js 2.12.0 → 2.13.0

package/README.md

@@ -201,6 +201,10 @@ if (result.success) {
 
 await hyve.showAd("interstitial");  // between levels
 await hyve.showAd("preroll");       // game start
+
+// Optional placement key, used by native AdMob to resolve a per-placement
+// ad unit. Ignored on the web path.
+await hyve.showAd("rewarded", "level_end");
 ```
 
 | Ad Type | Use Case |
@@ -211,6 +215,16 @@ await hyve.showAd("preroll");       // game start
 
 The SDK automatically routes ad calls through the appropriate platform SDK (CrazyGames, Playgama, or the default Google H5 Ads SDK) based on the current domain.
 
+### Native AdMob
+
+Inside the Hyve mobile shell, set `useNativeAds: true` to serve ads via native
+AdMob instead of Google H5. Routing is decided per call: when
+`window.ReactNativeWebView` is present and `useNativeAds` is enabled, ad
+requests go to native AdMob (`preroll` maps to a native interstitial);
+otherwise the H5 web path is used. The game-facing API is unchanged, and any
+`not_configured` / `config_fetch_failed` response from native falls back to H5
+for that call. See [docs/ads.md](./docs/ads.md) for details.
+
 ## Platform Integrations
 
 ### CrazyGames
@@ -406,8 +420,8 @@ new HyveClient(config?: {
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `configureAds(config)` | `void` | Configure the ads service |
-| `showAd(type)` | `Promise<AdResult>` | Show an ad |
+| `configureAds(config)` | `void` | Configure the ads service (incl. `useNativeAds`) |
+| `showAd(type, placement?)` | `Promise<AdResult>` | Show an ad; `placement` forwarded to native AdMob |
 | `areAdsReady()` | `boolean` | Check if ads have initialized |
 | `gameplayStart()` | `Promise<void>` | Notify gameplay started (CrazyGames) |
 | `gameplayStop()` | `Promise<void>` | Notify gameplay stopped (CrazyGames) |

package/dist/index.d.mts

@@ -182,7 +182,17 @@ interface GetGameDataLeaderboardParams {
  *
  * @packageDocumentation
  */
+/**
+ * Ad types the SDK's `show()` accepts. Limited to formats with a working
+ * native path; `'preroll'` maps to a native interstitial (Decision 2).
+ */
 type AdType = 'rewarded' | 'interstitial' | 'preroll';
+/**
+ * AdMob format strings understood by the storage layer and native resolver.
+ * Broader than {@link AdType} — the extra formats are storage-only until a
+ * native show path is wired up for them (see docs/admob-migration.md).
+ */
+type AdMobFormat = 'rewarded' | 'interstitial' | 'rewarded_interstitial' | 'banner' | 'native_advanced' | 'app_open';
 interface AdResult {
     success: boolean;
     type: AdType;
@@ -193,6 +203,19 @@ interface AdResult {
 interface AdConfig {
     sound?: 'on' | 'off';
     debug?: boolean;
+    /**
+     * Route ad requests through the native AdMob bridge when running inside the
+     * Hyve mobile shell (`window.ReactNativeWebView` present).
+     *
+     * Phase 0 rollout flag: defaults to `false`, where ads always use the
+     * existing H5 / Playgama web path. The native path is wired up behind this
+     * flag in a later phase — until then this is an inert toggle that exists so
+     * later releases can flip behavior without an API change. See
+     * `docs/admob-migration.md`.
+     *
+     * @default false
+     */
+    useNativeAds?: boolean;
     onBeforeAd?: (type: AdType) => void;
     onAfterAd?: (type: AdType) => void;
     onRewardEarned?: () => void;
@@ -225,6 +248,12 @@ declare class AdsService {
     private config;
     private initPromise;
     private ready;
+    private gameId;
+    /**
+     * Set the game ID used in native ad requests. Called by the client once the
+     * game ID is known (from URL params or JWT). No-op for the web ad path.
+     */
+    setGameId(gameId: string | null): void;
     /**
      * Optionally configure the ads service.
      * Not required — ads work without calling this.
@@ -237,11 +266,43 @@ declare class AdsService {
     private initialize;
     /**
      * Show an ad. Auto-initializes on the first call.
-     * Returns immediately with success: false if ads are disabled or unavailable.
+     *
+     * Inside the Hyve mobile shell (`window.ReactNativeWebView` present) with
+     * `useNativeAds` enabled, the request is routed to native AdMob via the
+     * bridge. Otherwise — or when native reports the slot is `not_configured` /
+     * `config_fetch_failed` — it falls back to the Google H5 web path.
+     *
+     * Returns `success: false` if ads are disabled or unavailable.
+     *
+     * @param type - Ad type to show
+     * @param placement - Optional placement key, forwarded to native; ignored on
+     *   the web path (H5 has no placement concept).
+     */
+    show(type: AdType, placement?: string): Promise<AdResult>;
+    /**
+     * True when running inside the Hyve mobile shell with native ads enabled.
      */
-    show(type: AdType): Promise<AdResult>;
+    private isNativeAdsContext;
+    /**
+     * Route an ad request to native AdMob via the bridge (Decision 7 — native
+     * owns unit-ID resolution; the SDK only sends `{ gameId, format, placement }`).
+     *
+     * Returns the resolved `AdResult`, or `null` to indicate the caller should
+     * fall back to the web ad path for this single call.
+     */
+    private showNative;
+    /**
+     * Show an ad via the Google H5 web path. Auto-initializes on first call.
+     *
+     * @param fireBeforeAd - When false, `onBeforeAd` is not fired (the native
+     *   fallback path already fired it before delegating here).
+     */
+    private showWeb;
     /**
      * Show an ad break via the Google H5 API.
+     *
+     * @param fireBeforeAd - When false, skips `onBeforeAd` (already fired by the
+     *   native fallback path that delegated here).
      */
     private showAdBreak;
     /**
@@ -705,9 +766,11 @@ declare class HyveClient {
     /**
      * Show an ad
      * @param type Type of ad to show ('rewarded', 'interstitial', or 'preroll')
+     * @param placement Optional placement key, forwarded to the native AdMob path
+     *   to resolve a per-placement unit ID. Ignored on the web (H5/Playgama) path.
      * @returns Promise resolving to ad result
      */
-    showAd(type: AdType): Promise<AdResult>;
+    showAd(type: AdType, placement?: string): Promise<AdResult>;
     /**
      * Required lifecycle telemetry — Gameplay start.
      * Also notifies CrazyGames that gameplay has started.
@@ -1048,6 +1111,10 @@ declare enum NativeMessageType {
     GET_PRODUCTS = "GET_PRODUCTS",
     /** Initiate a purchase */
     PURCHASE = "PURCHASE",
+    /** Request a native AdMob rewarded ad */
+    SHOW_REWARDED_AD = "SHOW_REWARDED_AD",
+    /** Request a native AdMob interstitial ad */
+    SHOW_INTERSTITIAL_AD = "SHOW_INTERSTITIAL_AD",
     /** Response to CHECK_IAP_AVAILABILITY request */
     IAP_AVAILABILITY_RESULT = "IAP_AVAILABILITY_RESULT",
     /** Push notification permission was granted */
@@ -1059,7 +1126,37 @@ declare enum NativeMessageType {
     /** Purchase completed successfully */
     PURCHASE_COMPLETE = "PURCHASE_COMPLETE",
     /** Purchase failed or was cancelled */
-    PURCHASE_ERROR = "PURCHASE_ERROR"
+    PURCHASE_ERROR = "PURCHASE_ERROR",
+    /** Result of a SHOW_REWARDED_AD / SHOW_INTERSTITIAL_AD request */
+    AD_RESULT = "AD_RESULT"
+}
+/**
+ * Payload sent to native for a SHOW_*_AD request.
+ * Native is the sole authority for resolving (format, placement) → ad unit ID,
+ * so the SDK never sends or sees unit IDs (see docs/admob-migration.md).
+ */
+interface AdRequestPayload {
+    /** Game the ad belongs to — native keys its unit-ID lookup on this. */
+    gameId: string;
+    /** AdMob format string, e.g. "rewarded" | "interstitial". */
+    format: string;
+    /** Optional placement key; native falls back to "default" when omitted. */
+    placement?: string;
+}
+/**
+ * Raw `AD_RESULT` payload as received from native.
+ *
+ * `error` is a string code (e.g. "not_configured", "config_fetch_failed"),
+ * not an `Error` object — the SDK inspects it to decide whether to fall back
+ * to the web ad path before converting it for the public `AdResult`.
+ */
+interface NativeAdResult {
+    /** Echoes the resolved ad type ("rewarded" | "interstitial"). */
+    type: string;
+    /** Whether the ad was shown successfully. */
+    success: boolean;
+    /** Error code when the ad did not show. */
+    error?: string;
 }
 /**
  * Message handler function type for receiving messages from native
@@ -1085,6 +1182,12 @@ type NativeMessageHandler<T = any> = (payload: T) => void | Promise<void>;
 declare class NativeBridge {
     private static handlers;
     private static isInitialized;
+    /**
+     * Pending `sendAdRequest()` promises, keyed by the ad type native echoes
+     * back in `AD_RESULT.type` ("rewarded" | "interstitial"). One in-flight
+     * request per type — ads are shown sequentially.
+     */
+    private static adResultResolvers;
     /**
      * Checks if the app is running inside a React Native WebView
      */
@@ -1188,6 +1291,38 @@ declare class NativeBridge {
      * NativeBridge.purchase("product_123", "user_456");
      */
     static purchase(productId: string, userId: string): void;
+    /**
+     * Sends a native ad request and resolves with the `AD_RESULT` native sends
+     * back. Never rejects — a missing native context, timeout, or superseded
+     * request resolves to `{ success: false }` with an error code so callers can
+     * decide whether to fall back to the web ad path.
+     *
+     * @param messageType - `SHOW_REWARDED_AD` or `SHOW_INTERSTITIAL_AD`
+     * @param payload - `{ gameId, format, placement? }`
+     * @param timeoutMs - How long to wait for `AD_RESULT` before giving up
+     *
+     * @example
+     * const result = await NativeBridge.sendAdRequest(
+     *   NativeMessageType.SHOW_REWARDED_AD,
+     *   { gameId: "123", format: "rewarded", placement: "level_end" },
+     * );
+     * if (result.success) grantReward();
+     */
+    static sendAdRequest(messageType: NativeMessageType.SHOW_REWARDED_AD | NativeMessageType.SHOW_INTERSTITIAL_AD, payload: AdRequestPayload, timeoutMs?: number): Promise<NativeAdResult>;
+    /**
+     * Registers a handler invoked for every `AD_RESULT` message from native,
+     * in addition to resolving any pending {@link sendAdRequest} promise.
+     * Useful for diagnostics or availability tracking.
+     *
+     * @param handler - Called with the raw `AD_RESULT` payload
+     */
+    static onAdResult(handler: NativeMessageHandler<NativeAdResult>): void;
+    /**
+     * Resolves the pending {@link sendAdRequest} promise that matches an
+     * incoming `AD_RESULT` payload. No-op when nothing is waiting (e.g. a late
+     * result after a timeout).
+     */
+    private static resolveAdResult;
 }
 
 /**
@@ -1196,4 +1331,4 @@ declare class NativeBridge {
  */
 declare function generateUUID(): string;
 
-export { type AdConfig, type AdResult, type AdType, AdsService, type BatchSaveGameDataResponse, type BatchSaveResultItem, type BillingConfig, BillingPlatform, type BillingProduct, BillingService, CloudStorageAdapter, CrazyGamesService, type DeleteGameDataResponse, type GameDataBatchItem, type GameDataItem, type GameDataLeaderboardEntry, type GameDataLeaderboardResponse, type GameDataLeaderboardUserPosition, type GameDataOperation, type GameDataValue, type GetGameDataBatchResponse, type GetGameDataLeaderboardParams, type GetGameDataResponse, HyveClient, type HyveClientConfig, type Inventory, type InventoryItem, LocalStorageAdapter, Logger, NativeBridge, type NativeMessage, type NativeMessageHandler, NativeMessageType, PlaygamaService, type PurchaseResult, type SaveGameDataResponse, type StorageAdapter, type TelemetryAdditionalData, type TelemetryConfig, type TelemetryEvent, generateUUID, isDomainAllowed, logger, parseUrlParams };
+export { type AdConfig, type AdMobFormat, type AdRequestPayload, type AdResult, type AdType, AdsService, type BatchSaveGameDataResponse, type BatchSaveResultItem, type BillingConfig, BillingPlatform, type BillingProduct, BillingService, CloudStorageAdapter, CrazyGamesService, type DeleteGameDataResponse, type GameDataBatchItem, type GameDataItem, type GameDataLeaderboardEntry, type GameDataLeaderboardResponse, type GameDataLeaderboardUserPosition, type GameDataOperation, type GameDataValue, type GetGameDataBatchResponse, type GetGameDataLeaderboardParams, type GetGameDataResponse, HyveClient, type HyveClientConfig, type Inventory, type InventoryItem, LocalStorageAdapter, Logger, type NativeAdResult, NativeBridge, type NativeMessage, type NativeMessageHandler, NativeMessageType, PlaygamaService, type PurchaseResult, type SaveGameDataResponse, type StorageAdapter, type TelemetryAdditionalData, type TelemetryConfig, type TelemetryEvent, generateUUID, isDomainAllowed, logger, parseUrlParams };

package/dist/index.d.ts

@@ -182,7 +182,17 @@ interface GetGameDataLeaderboardParams {
  *
  * @packageDocumentation
  */
+/**
+ * Ad types the SDK's `show()` accepts. Limited to formats with a working
+ * native path; `'preroll'` maps to a native interstitial (Decision 2).
+ */
 type AdType = 'rewarded' | 'interstitial' | 'preroll';
+/**
+ * AdMob format strings understood by the storage layer and native resolver.
+ * Broader than {@link AdType} — the extra formats are storage-only until a
+ * native show path is wired up for them (see docs/admob-migration.md).
+ */
+type AdMobFormat = 'rewarded' | 'interstitial' | 'rewarded_interstitial' | 'banner' | 'native_advanced' | 'app_open';
 interface AdResult {
     success: boolean;
     type: AdType;
@@ -193,6 +203,19 @@ interface AdResult {
 interface AdConfig {
     sound?: 'on' | 'off';
     debug?: boolean;
+    /**
+     * Route ad requests through the native AdMob bridge when running inside the
+     * Hyve mobile shell (`window.ReactNativeWebView` present).
+     *
+     * Phase 0 rollout flag: defaults to `false`, where ads always use the
+     * existing H5 / Playgama web path. The native path is wired up behind this
+     * flag in a later phase — until then this is an inert toggle that exists so
+     * later releases can flip behavior without an API change. See
+     * `docs/admob-migration.md`.
+     *
+     * @default false
+     */
+    useNativeAds?: boolean;
     onBeforeAd?: (type: AdType) => void;
     onAfterAd?: (type: AdType) => void;
     onRewardEarned?: () => void;
@@ -225,6 +248,12 @@ declare class AdsService {
     private config;
     private initPromise;
     private ready;
+    private gameId;
+    /**
+     * Set the game ID used in native ad requests. Called by the client once the
+     * game ID is known (from URL params or JWT). No-op for the web ad path.
+     */
+    setGameId(gameId: string | null): void;
     /**
      * Optionally configure the ads service.
      * Not required — ads work without calling this.
@@ -237,11 +266,43 @@ declare class AdsService {
     private initialize;
     /**
      * Show an ad. Auto-initializes on the first call.
-     * Returns immediately with success: false if ads are disabled or unavailable.
+     *
+     * Inside the Hyve mobile shell (`window.ReactNativeWebView` present) with
+     * `useNativeAds` enabled, the request is routed to native AdMob via the
+     * bridge. Otherwise — or when native reports the slot is `not_configured` /
+     * `config_fetch_failed` — it falls back to the Google H5 web path.
+     *
+     * Returns `success: false` if ads are disabled or unavailable.
+     *
+     * @param type - Ad type to show
+     * @param placement - Optional placement key, forwarded to native; ignored on
+     *   the web path (H5 has no placement concept).
+     */
+    show(type: AdType, placement?: string): Promise<AdResult>;
+    /**
+     * True when running inside the Hyve mobile shell with native ads enabled.
      */
-    show(type: AdType): Promise<AdResult>;
+    private isNativeAdsContext;
+    /**
+     * Route an ad request to native AdMob via the bridge (Decision 7 — native
+     * owns unit-ID resolution; the SDK only sends `{ gameId, format, placement }`).
+     *
+     * Returns the resolved `AdResult`, or `null` to indicate the caller should
+     * fall back to the web ad path for this single call.
+     */
+    private showNative;
+    /**
+     * Show an ad via the Google H5 web path. Auto-initializes on first call.
+     *
+     * @param fireBeforeAd - When false, `onBeforeAd` is not fired (the native
+     *   fallback path already fired it before delegating here).
+     */
+    private showWeb;
     /**
      * Show an ad break via the Google H5 API.
+     *
+     * @param fireBeforeAd - When false, skips `onBeforeAd` (already fired by the
+     *   native fallback path that delegated here).
      */
     private showAdBreak;
     /**
@@ -705,9 +766,11 @@ declare class HyveClient {
     /**
      * Show an ad
      * @param type Type of ad to show ('rewarded', 'interstitial', or 'preroll')
+     * @param placement Optional placement key, forwarded to the native AdMob path
+     *   to resolve a per-placement unit ID. Ignored on the web (H5/Playgama) path.
      * @returns Promise resolving to ad result
      */
-    showAd(type: AdType): Promise<AdResult>;
+    showAd(type: AdType, placement?: string): Promise<AdResult>;
     /**
      * Required lifecycle telemetry — Gameplay start.
      * Also notifies CrazyGames that gameplay has started.
@@ -1048,6 +1111,10 @@ declare enum NativeMessageType {
     GET_PRODUCTS = "GET_PRODUCTS",
     /** Initiate a purchase */
     PURCHASE = "PURCHASE",
+    /** Request a native AdMob rewarded ad */
+    SHOW_REWARDED_AD = "SHOW_REWARDED_AD",
+    /** Request a native AdMob interstitial ad */
+    SHOW_INTERSTITIAL_AD = "SHOW_INTERSTITIAL_AD",
     /** Response to CHECK_IAP_AVAILABILITY request */
     IAP_AVAILABILITY_RESULT = "IAP_AVAILABILITY_RESULT",
     /** Push notification permission was granted */
@@ -1059,7 +1126,37 @@ declare enum NativeMessageType {
     /** Purchase completed successfully */
     PURCHASE_COMPLETE = "PURCHASE_COMPLETE",
     /** Purchase failed or was cancelled */
-    PURCHASE_ERROR = "PURCHASE_ERROR"
+    PURCHASE_ERROR = "PURCHASE_ERROR",
+    /** Result of a SHOW_REWARDED_AD / SHOW_INTERSTITIAL_AD request */
+    AD_RESULT = "AD_RESULT"
+}
+/**
+ * Payload sent to native for a SHOW_*_AD request.
+ * Native is the sole authority for resolving (format, placement) → ad unit ID,
+ * so the SDK never sends or sees unit IDs (see docs/admob-migration.md).
+ */
+interface AdRequestPayload {
+    /** Game the ad belongs to — native keys its unit-ID lookup on this. */
+    gameId: string;
+    /** AdMob format string, e.g. "rewarded" | "interstitial". */
+    format: string;
+    /** Optional placement key; native falls back to "default" when omitted. */
+    placement?: string;
+}
+/**
+ * Raw `AD_RESULT` payload as received from native.
+ *
+ * `error` is a string code (e.g. "not_configured", "config_fetch_failed"),
+ * not an `Error` object — the SDK inspects it to decide whether to fall back
+ * to the web ad path before converting it for the public `AdResult`.
+ */
+interface NativeAdResult {
+    /** Echoes the resolved ad type ("rewarded" | "interstitial"). */
+    type: string;
+    /** Whether the ad was shown successfully. */
+    success: boolean;
+    /** Error code when the ad did not show. */
+    error?: string;
 }
 /**
  * Message handler function type for receiving messages from native
@@ -1085,6 +1182,12 @@ type NativeMessageHandler<T = any> = (payload: T) => void | Promise<void>;
 declare class NativeBridge {
     private static handlers;
     private static isInitialized;
+    /**
+     * Pending `sendAdRequest()` promises, keyed by the ad type native echoes
+     * back in `AD_RESULT.type` ("rewarded" | "interstitial"). One in-flight
+     * request per type — ads are shown sequentially.
+     */
+    private static adResultResolvers;
     /**
      * Checks if the app is running inside a React Native WebView
      */
@@ -1188,6 +1291,38 @@ declare class NativeBridge {
      * NativeBridge.purchase("product_123", "user_456");
      */
     static purchase(productId: string, userId: string): void;
+    /**
+     * Sends a native ad request and resolves with the `AD_RESULT` native sends
+     * back. Never rejects — a missing native context, timeout, or superseded
+     * request resolves to `{ success: false }` with an error code so callers can
+     * decide whether to fall back to the web ad path.
+     *
+     * @param messageType - `SHOW_REWARDED_AD` or `SHOW_INTERSTITIAL_AD`
+     * @param payload - `{ gameId, format, placement? }`
+     * @param timeoutMs - How long to wait for `AD_RESULT` before giving up
+     *
+     * @example
+     * const result = await NativeBridge.sendAdRequest(
+     *   NativeMessageType.SHOW_REWARDED_AD,
+     *   { gameId: "123", format: "rewarded", placement: "level_end" },
+     * );
+     * if (result.success) grantReward();
+     */
+    static sendAdRequest(messageType: NativeMessageType.SHOW_REWARDED_AD | NativeMessageType.SHOW_INTERSTITIAL_AD, payload: AdRequestPayload, timeoutMs?: number): Promise<NativeAdResult>;
+    /**
+     * Registers a handler invoked for every `AD_RESULT` message from native,
+     * in addition to resolving any pending {@link sendAdRequest} promise.
+     * Useful for diagnostics or availability tracking.
+     *
+     * @param handler - Called with the raw `AD_RESULT` payload
+     */
+    static onAdResult(handler: NativeMessageHandler<NativeAdResult>): void;
+    /**
+     * Resolves the pending {@link sendAdRequest} promise that matches an
+     * incoming `AD_RESULT` payload. No-op when nothing is waiting (e.g. a late
+     * result after a timeout).
+     */
+    private static resolveAdResult;
 }
 
 /**
@@ -1196,4 +1331,4 @@ declare class NativeBridge {
  */
 declare function generateUUID(): string;
 
-export { type AdConfig, type AdResult, type AdType, AdsService, type BatchSaveGameDataResponse, type BatchSaveResultItem, type BillingConfig, BillingPlatform, type BillingProduct, BillingService, CloudStorageAdapter, CrazyGamesService, type DeleteGameDataResponse, type GameDataBatchItem, type GameDataItem, type GameDataLeaderboardEntry, type GameDataLeaderboardResponse, type GameDataLeaderboardUserPosition, type GameDataOperation, type GameDataValue, type GetGameDataBatchResponse, type GetGameDataLeaderboardParams, type GetGameDataResponse, HyveClient, type HyveClientConfig, type Inventory, type InventoryItem, LocalStorageAdapter, Logger, NativeBridge, type NativeMessage, type NativeMessageHandler, NativeMessageType, PlaygamaService, type PurchaseResult, type SaveGameDataResponse, type StorageAdapter, type TelemetryAdditionalData, type TelemetryConfig, type TelemetryEvent, generateUUID, isDomainAllowed, logger, parseUrlParams };
+export { type AdConfig, type AdMobFormat, type AdRequestPayload, type AdResult, type AdType, AdsService, type BatchSaveGameDataResponse, type BatchSaveResultItem, type BillingConfig, BillingPlatform, type BillingProduct, BillingService, CloudStorageAdapter, CrazyGamesService, type DeleteGameDataResponse, type GameDataBatchItem, type GameDataItem, type GameDataLeaderboardEntry, type GameDataLeaderboardResponse, type GameDataLeaderboardUserPosition, type GameDataOperation, type GameDataValue, type GetGameDataBatchResponse, type GetGameDataLeaderboardParams, type GetGameDataResponse, HyveClient, type HyveClientConfig, type Inventory, type InventoryItem, LocalStorageAdapter, Logger, type NativeAdResult, NativeBridge, type NativeMessage, type NativeMessageHandler, NativeMessageType, PlaygamaService, type PurchaseResult, type SaveGameDataResponse, type StorageAdapter, type TelemetryAdditionalData, type TelemetryConfig, type TelemetryEvent, generateUUID, isDomainAllowed, logger, parseUrlParams };