@hyve-sdk/js 2.11.2 → 2.13.0-canary.0

package/dist/index.mjs

@@ -158,17 +158,26 @@ var NativeMessageType = /* @__PURE__ */ ((NativeMessageType2) => {
   NativeMessageType2["REQUEST_NOTIFICATION_PERMISSION"] = "REQUEST_NOTIFICATION_PERMISSION";
   NativeMessageType2["GET_PRODUCTS"] = "GET_PRODUCTS";
   NativeMessageType2["PURCHASE"] = "PURCHASE";
+  NativeMessageType2["SHOW_REWARDED_AD"] = "SHOW_REWARDED_AD";
+  NativeMessageType2["SHOW_INTERSTITIAL_AD"] = "SHOW_INTERSTITIAL_AD";
   NativeMessageType2["IAP_AVAILABILITY_RESULT"] = "IAP_AVAILABILITY_RESULT";
   NativeMessageType2["PUSH_PERMISSION_GRANTED"] = "PUSH_PERMISSION_GRANTED";
   NativeMessageType2["PUSH_PERMISSION_DENIED"] = "PUSH_PERMISSION_DENIED";
   NativeMessageType2["PRODUCTS_RESULT"] = "PRODUCTS_RESULT";
   NativeMessageType2["PURCHASE_COMPLETE"] = "PURCHASE_COMPLETE";
   NativeMessageType2["PURCHASE_ERROR"] = "PURCHASE_ERROR";
+  NativeMessageType2["AD_RESULT"] = "AD_RESULT";
   return NativeMessageType2;
 })(NativeMessageType || {});
 var NativeBridge = class {
   static handlers = /* @__PURE__ */ new Map();
   static isInitialized = false;
+  /**
+   * 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.
+   */
+  static adResultResolvers = /* @__PURE__ */ new Map();
   /**
    * Checks if the app is running inside a React Native WebView
    */
@@ -221,16 +230,20 @@ var NativeBridge = class {
         "PUSH_PERMISSION_DENIED" /* PUSH_PERMISSION_DENIED */,
         "PRODUCTS_RESULT" /* PRODUCTS_RESULT */,
         "PURCHASE_COMPLETE" /* PURCHASE_COMPLETE */,
-        "PURCHASE_ERROR" /* PURCHASE_ERROR */
+        "PURCHASE_ERROR" /* PURCHASE_ERROR */,
+        "AD_RESULT" /* AD_RESULT */
       ];
       if (!nativeResponseTypes.includes(data.type)) {
         return;
       }
+      if (data.type === "AD_RESULT" /* AD_RESULT */) {
+        this.resolveAdResult(data.payload);
+      }
       const handler = this.handlers.get(data.type);
       if (handler) {
         logger.debug(`[NativeBridge] Handling message: ${data.type}`);
         handler(data.payload);
-      } else {
+      } else if (data.type !== "AD_RESULT" /* AD_RESULT */) {
         logger.warn(`[NativeBridge] No handler registered for: ${data.type}`);
       }
     } catch (error) {
@@ -356,6 +369,81 @@ var NativeBridge = class {
   static purchase(productId, userId) {
     this.send("PURCHASE" /* PURCHASE */, { productId, userId });
   }
+  /**
+   * 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, payload, timeoutMs = 12e4) {
+    const expectedType = messageType === "SHOW_REWARDED_AD" /* SHOW_REWARDED_AD */ ? "rewarded" : "interstitial";
+    return new Promise((resolve) => {
+      if (!this.isNativeContext()) {
+        resolve({ type: expectedType, success: false, error: "no_native_context" });
+        return;
+      }
+      this.initialize();
+      const existing = this.adResultResolvers.get(expectedType);
+      if (existing) {
+        logger.warn(`[NativeBridge] Superseding in-flight ${expectedType} ad request`);
+        existing({ type: expectedType, success: false, error: "superseded" });
+      }
+      let settled = false;
+      const timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        this.adResultResolvers.delete(expectedType);
+        logger.warn(`[NativeBridge] Ad request timed out: ${expectedType}`);
+        resolve({ type: expectedType, success: false, error: "timeout" });
+      }, timeoutMs);
+      this.adResultResolvers.set(expectedType, (result) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        this.adResultResolvers.delete(expectedType);
+        resolve(result);
+      });
+      this.send(messageType, payload);
+    });
+  }
+  /**
+   * 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) {
+    this.on("AD_RESULT" /* AD_RESULT */, handler);
+  }
+  /**
+   * 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).
+   */
+  static resolveAdResult(payload) {
+    if (!payload?.type) {
+      logger.warn("[NativeBridge] AD_RESULT received without a type");
+      return;
+    }
+    const resolver = this.adResultResolvers.get(payload.type);
+    if (resolver) {
+      resolver(payload);
+    } else {
+      logger.debug(`[NativeBridge] No pending ad request for: ${payload.type}`);
+    }
+  }
 };
 
 // src/utils/jwt.ts
@@ -712,10 +800,12 @@ function getAttributionData() {
 }
 
 // src/services/ads.ts
+var FALLBACK_ERROR_CODES = ["not_configured", "config_fetch_failed"];
 var AdsService = class {
   config = {
     sound: "on",
     debug: false,
+    useNativeAds: false,
     onBeforeAd: () => {
     },
     onAfterAd: () => {
@@ -726,6 +816,16 @@ var AdsService = class {
   // Cached init promise — ensures adConfig() is only called once
   initPromise = null;
   ready = false;
+  // Game this SDK instance serves — sent to native so it can resolve unit IDs.
+  // The SDK never stores or resolves unit IDs itself (Decision 7).
+  gameId = null;
+  /**
+   * 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) {
+    this.gameId = gameId;
+  }
   /**
    * Optionally configure the ads service.
    * Not required — ads work without calling this.
@@ -739,7 +839,10 @@ var AdsService = class {
       onRewardEarned: config.onRewardEarned ?? this.config.onRewardEarned
     };
     if (this.config.debug) {
-      logger.debug("[AdsService] Configuration updated:", { sound: this.config.sound });
+      logger.debug("[AdsService] Configuration updated:", {
+        sound: this.config.sound,
+        useNativeAds: this.config.useNativeAds
+      });
     }
   }
   /**
@@ -776,10 +879,93 @@ var AdsService = class {
   }
   /**
    * 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).
    */
-  async show(type) {
+  async show(type, placement) {
     const requestedAt = Date.now();
+    if (this.isNativeAdsContext()) {
+      const nativeResult = await this.showNative(type, placement, requestedAt);
+      if (nativeResult) return nativeResult;
+    }
+    return this.showWeb(type, requestedAt, true);
+  }
+  /**
+   * True when running inside the Hyve mobile shell with native ads enabled.
+   */
+  isNativeAdsContext() {
+    return NativeBridge.isNativeContext() && this.config.useNativeAds === true;
+  }
+  /**
+   * 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.
+   */
+  async showNative(type, placement, requestedAt) {
+    if (!this.gameId) {
+      if (this.config.debug) {
+        logger.debug("[AdsService] Native ads enabled but no gameId set \u2014 using web path");
+      }
+      return null;
+    }
+    const format = type === "rewarded" ? "rewarded" : "interstitial";
+    const messageType = type === "rewarded" ? "SHOW_REWARDED_AD" /* SHOW_REWARDED_AD */ : "SHOW_INTERSTITIAL_AD" /* SHOW_INTERSTITIAL_AD */;
+    if (this.config.debug) {
+      logger.debug(`[AdsService] Requesting native ${type} ad (format: ${format})`, {
+        gameId: this.gameId,
+        placement
+      });
+    }
+    this.config.onBeforeAd(type);
+    const result = await NativeBridge.sendAdRequest(messageType, {
+      gameId: this.gameId,
+      format,
+      placement
+    });
+    const completedAt = Date.now();
+    if (result.error && FALLBACK_ERROR_CODES.includes(result.error)) {
+      if (this.config.debug) {
+        logger.debug(`[AdsService] Native ad ${result.error} \u2014 falling back to web path`);
+      }
+      return this.showWeb(type, requestedAt, false);
+    }
+    this.config.onAfterAd(type);
+    if (type === "rewarded" && result.success) {
+      this.config.onRewardEarned();
+    }
+    if (this.config.debug) {
+      logger.debug("[AdsService] Native ad result:", {
+        type,
+        success: result.success,
+        error: result.error
+      });
+    }
+    return {
+      success: result.success,
+      type,
+      error: result.error ? new Error(result.error) : void 0,
+      requestedAt,
+      completedAt
+    };
+  }
+  /**
+   * 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).
+   */
+  async showWeb(type, requestedAt, fireBeforeAd) {
     const ready = await this.initialize();
     if (!ready || !window.adBreak) {
       return {
@@ -790,12 +976,15 @@ var AdsService = class {
         completedAt: Date.now()
       };
     }
-    return this.showAdBreak(type);
+    return this.showAdBreak(type, fireBeforeAd);
   }
   /**
    * 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).
    */
-  async showAdBreak(type) {
+  async showAdBreak(type, fireBeforeAd = true) {
     const requestedAt = Date.now();
     return new Promise((resolve) => {
       const googleType = type === "rewarded" ? "reward" : type === "preroll" ? "start" : "next";
@@ -803,7 +992,9 @@ var AdsService = class {
       if (this.config.debug) {
         logger.debug(`[AdsService] Showing ${type} ad`);
       }
-      this.config.onBeforeAd(type);
+      if (fireBeforeAd) {
+        this.config.onBeforeAd(type);
+      }
       const adBreakConfig = {
         type: googleType,
         name: adName,
@@ -1977,6 +2168,7 @@ var HyveClient = class {
         this.gameId = params.gameId;
         logger.info("Game ID extracted from game-id parameter:", this.gameId);
       }
+      this.adsService.setGameId(this.gameId);
       if (this.jwtToken) {
         logger.info("Authentication successful via JWT");
       } else {
@@ -2082,6 +2274,93 @@ var HyveClient = class {
       return false;
     }
   }
+  /**
+   * Required lifecycle telemetry — Session start.
+   * See https://docs.hyve.gg/docs/telemetry#required-lifecycle-events
+   */
+  async sessionStart() {
+    return this.sendTelemetry("game", "session", "start");
+  }
+  /**
+   * Required lifecycle telemetry — Session end.
+   */
+  async sessionEnd() {
+    return this.sendTelemetry("game", "session", "end");
+  }
+  /**
+   * Required lifecycle telemetry — Lobby loading start.
+   */
+  async lobbyLoadingStart() {
+    return this.sendTelemetry("game", "loading", "start");
+  }
+  /**
+   * Required lifecycle telemetry — Lobby loading end.
+   */
+  async lobbyLoadingEnd() {
+    return this.sendTelemetry("game", "loading", "end");
+  }
+  /**
+   * Required lifecycle telemetry — Game loading start.
+   */
+  async gameLoadingStart() {
+    return this.sendTelemetry("game", "game_loading", "start");
+  }
+  /**
+   * Required lifecycle telemetry — Game loading end.
+   */
+  async gameLoadingEnd() {
+    return this.sendTelemetry("game", "game_loading", "end");
+  }
+  /**
+   * Required lifecycle telemetry — Lobby initialization.
+   */
+  async lobbyInit() {
+    return this.sendTelemetry("game", "lobby", "init");
+  }
+  /**
+   * Required lifecycle telemetry — Gameplay end.
+   * Also notifies CrazyGames that gameplay has stopped.
+   */
+  async gameplayEnd() {
+    if (this.crazyGamesService) {
+      if (this.crazyGamesInitPromise) await this.crazyGamesInitPromise;
+      this.crazyGamesService.gameplayStop();
+    }
+    return this.sendTelemetry("game", "gameplay", "end");
+  }
+  /**
+   * Required lifecycle telemetry — Store opened.
+   */
+  async storeOpen() {
+    return this.sendTelemetry("game", "store", "start");
+  }
+  /**
+   * Required lifecycle telemetry — Purchase complete.
+   * @param itemName Name of the purchased item (required by the platform)
+   */
+  async purchaseComplete(itemName) {
+    return this.sendTelemetry("game", "purchase", "complete", null, null, {
+      item_name: itemName
+    });
+  }
+  /**
+   * Required lifecycle telemetry — Purchase failed.
+   * @param itemName Name of the item the purchase was for
+   */
+  async purchaseFail(itemName) {
+    return this.sendTelemetry("game", "purchase", "fail", null, null, {
+      item_name: itemName
+    });
+  }
+  /**
+   * Required lifecycle telemetry — Purchase cancelled.
+   * @param itemName Name of the item the purchase was for
+   */
+  async purchaseCancel(itemName) {
+    return this.sendTelemetry("game", "purchase", "cancel", null, null, {
+      item_name: itemName
+    });
+  }
   /**
    * Makes an authenticated API call using the JWT token
    * @param endpoint API endpoint path (will be appended to base URL)
@@ -2203,6 +2482,7 @@ var HyveClient = class {
     this.userId = null;
     this.jwtToken = null;
     this.gameId = null;
+    this.adsService.setGameId(null);
     logger.info("User logged out");
   }
   /**
@@ -2377,9 +2657,11 @@ var HyveClient = class {
   /**
    * 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
    */
-  async showAd(type) {
+  async showAd(type, placement) {
     if (this.crazyGamesService) {
       if (this.crazyGamesInitPromise) {
         await this.crazyGamesInitPromise;
@@ -2418,17 +2700,18 @@ var HyveClient = class {
         });
       }
     }
-    return this.adsService.show(type);
+    return this.adsService.show(type, placement);
   }
   /**
-   * Notifies CrazyGames that gameplay has started.
-   * No-op on other platforms.
+   * Required lifecycle telemetry — Gameplay start.
+   * Also notifies CrazyGames that gameplay has started.
    */
   async gameplayStart() {
     if (this.crazyGamesService) {
       if (this.crazyGamesInitPromise) await this.crazyGamesInitPromise;
       this.crazyGamesService.gameplayStart();
     }
+    return this.sendTelemetry("game", "gameplay", "start");
   }
   /**
    * Notifies CrazyGames that gameplay has stopped.

package/dist/react.d.mts

@@ -138,6 +138,10 @@ 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';
 interface AdResult {
     success: boolean;
@@ -149,6 +153,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;
@@ -282,6 +299,59 @@ declare class HyveClient {
      * @returns Promise resolving to boolean indicating success
      */
     sendTelemetry(eventLocation: string, eventCategory: string, eventAction: string, eventSubCategory?: string | null, eventSubAction?: string | null, eventDetails?: Record<string, any> | string | null, platformId?: string | null): Promise<boolean>;
+    /**
+     * Required lifecycle telemetry — Session start.
+     * See https://docs.hyve.gg/docs/telemetry#required-lifecycle-events
+     */
+    sessionStart(): Promise<boolean>;
+    /**
+     * Required lifecycle telemetry — Session end.
+     */
+    sessionEnd(): Promise<boolean>;
+    /**
+     * Required lifecycle telemetry — Lobby loading start.
+     */
+    lobbyLoadingStart(): Promise<boolean>;
+    /**
+     * Required lifecycle telemetry — Lobby loading end.
+     */
+    lobbyLoadingEnd(): Promise<boolean>;
+    /**
+     * Required lifecycle telemetry — Game loading start.
+     */
+    gameLoadingStart(): Promise<boolean>;
+    /**
+     * Required lifecycle telemetry — Game loading end.
+     */
+    gameLoadingEnd(): Promise<boolean>;
+    /**
+     * Required lifecycle telemetry — Lobby initialization.
+     */
+    lobbyInit(): Promise<boolean>;
+    /**
+     * Required lifecycle telemetry — Gameplay end.
+     * Also notifies CrazyGames that gameplay has stopped.
+     */
+    gameplayEnd(): Promise<boolean>;
+    /**
+     * Required lifecycle telemetry — Store opened.
+     */
+    storeOpen(): Promise<boolean>;
+    /**
+     * Required lifecycle telemetry — Purchase complete.
+     * @param itemName Name of the purchased item (required by the platform)
+     */
+    purchaseComplete(itemName: string): Promise<boolean>;
+    /**
+     * Required lifecycle telemetry — Purchase failed.
+     * @param itemName Name of the item the purchase was for
+     */
+    purchaseFail(itemName: string): Promise<boolean>;
+    /**
+     * Required lifecycle telemetry — Purchase cancelled.
+     * @param itemName Name of the item the purchase was for
+     */
+    purchaseCancel(itemName: string): Promise<boolean>;
     /**
      * Makes an authenticated API call using the JWT token
      * @param endpoint API endpoint path (will be appended to base URL)
@@ -427,14 +497,16 @@ 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>;
     /**
-     * Notifies CrazyGames that gameplay has started.
-     * No-op on other platforms.
+     * Required lifecycle telemetry — Gameplay start.
+     * Also notifies CrazyGames that gameplay has started.
      */
-    gameplayStart(): Promise<void>;
+    gameplayStart(): Promise<boolean>;
     /**
      * Notifies CrazyGames that gameplay has stopped.
      * No-op on other platforms.

package/dist/react.d.ts

@@ -138,6 +138,10 @@ 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';
 interface AdResult {
     success: boolean;
@@ -149,6 +153,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;
@@ -282,6 +299,59 @@ declare class HyveClient {
      * @returns Promise resolving to boolean indicating success
      */
     sendTelemetry(eventLocation: string, eventCategory: string, eventAction: string, eventSubCategory?: string | null, eventSubAction?: string | null, eventDetails?: Record<string, any> | string | null, platformId?: string | null): Promise<boolean>;
+    /**
+     * Required lifecycle telemetry — Session start.
+     * See https://docs.hyve.gg/docs/telemetry#required-lifecycle-events
+     */
+    sessionStart(): Promise<boolean>;
+    /**
+     * Required lifecycle telemetry — Session end.
+     */
+    sessionEnd(): Promise<boolean>;
+    /**
+     * Required lifecycle telemetry — Lobby loading start.
+     */
+    lobbyLoadingStart(): Promise<boolean>;
+    /**
+     * Required lifecycle telemetry — Lobby loading end.
+     */
+    lobbyLoadingEnd(): Promise<boolean>;
+    /**
+     * Required lifecycle telemetry — Game loading start.
+     */
+    gameLoadingStart(): Promise<boolean>;
+    /**
+     * Required lifecycle telemetry — Game loading end.
+     */
+    gameLoadingEnd(): Promise<boolean>;
+    /**
+     * Required lifecycle telemetry — Lobby initialization.
+     */
+    lobbyInit(): Promise<boolean>;
+    /**
+     * Required lifecycle telemetry — Gameplay end.
+     * Also notifies CrazyGames that gameplay has stopped.
+     */
+    gameplayEnd(): Promise<boolean>;
+    /**
+     * Required lifecycle telemetry — Store opened.
+     */
+    storeOpen(): Promise<boolean>;
+    /**
+     * Required lifecycle telemetry — Purchase complete.
+     * @param itemName Name of the purchased item (required by the platform)
+     */
+    purchaseComplete(itemName: string): Promise<boolean>;
+    /**
+     * Required lifecycle telemetry — Purchase failed.
+     * @param itemName Name of the item the purchase was for
+     */
+    purchaseFail(itemName: string): Promise<boolean>;
+    /**
+     * Required lifecycle telemetry — Purchase cancelled.
+     * @param itemName Name of the item the purchase was for
+     */
+    purchaseCancel(itemName: string): Promise<boolean>;
     /**
      * Makes an authenticated API call using the JWT token
      * @param endpoint API endpoint path (will be appended to base URL)
@@ -427,14 +497,16 @@ 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>;
     /**
-     * Notifies CrazyGames that gameplay has started.
-     * No-op on other platforms.
+     * Required lifecycle telemetry — Gameplay start.
+     * Also notifies CrazyGames that gameplay has started.
      */
-    gameplayStart(): Promise<void>;
+    gameplayStart(): Promise<boolean>;
     /**
      * Notifies CrazyGames that gameplay has stopped.
      * No-op on other platforms.