@looplay/sdk 0.4.0 → 0.5.0

package/README.md

@@ -41,6 +41,51 @@ looplayAuth.subscribe((state) => { /* re-render when auth arrives/clears */ });
 await looplayAuth.trackPlay(playTimeSeconds);
 await looplayAuth.trackMatch(matchId, { durationSeconds, isWin: true });
 await looplayAuth.emitGameEvent('CUSTOM_ACTION', { value: 1 });
+await looplayAuth.requestAds();
+```
+
+### Rewarded ads via parent window
+
+When the game runs inside an iframe, you can ask the parent page to open a
+rewarded ad by sending `LOOPLAY_REQUEST_ADS`. This is the right pattern for a
+Telegram Mini App shell: the game stays inside the iframe, and the parent page
+owns the Adsgram integration. The parent should bridge that message to Adsgram
+(or any other rewarded-ad SDK) and then reply with `LOOPLAY_ADS_WATCHED` using
+the same `requestId` after the ad finishes.
+
+If there is no ad available, the parent should reply with
+`LOOPLAY_ADS_UNAVAILABLE` for the same `requestId`. The SDK will resolve the
+request as `false` and continue normally.
+
+If the parent never answers, `requestAds()` times out after 5 seconds by
+default and resolves `false`.
+
+```ts
+window.addEventListener('message', async (event) => {
+  const data = event.data;
+  if (!data || data.type !== 'LOOPLAY_REQUEST_ADS') return;
+
+  try {
+    // Replace this with your Adsgram integration.
+    await showRewardedAd(data.gameId);
+
+    event.source?.postMessage(
+      {
+        type: 'LOOPLAY_ADS_WATCHED',
+        requestId: data.requestId,
+      },
+      event.origin
+    );
+  } catch {
+    event.source?.postMessage(
+      {
+        type: 'LOOPLAY_ADS_UNAVAILABLE',
+        requestId: data.requestId,
+      },
+      event.origin
+    );
+  }
+});
 ```
 
 ### Drop-in `<script>` tag (no build step required)
@@ -85,4 +130,4 @@ session (including the refresh token) in `localStorage`, which is convenient
 but readable by any script on the page (XSS exposure). Prefer it only for
 games where that tradeoff is acceptable; for higher-security needs, keep the
 default in-memory storage or implement an `AuthStorage` backed by a more
-restrictive mechanism.
+restrictive mechanism.

package/dist/looplay-sdk.cjs.js

@@ -740,6 +740,7 @@ var TelegramAuthProvider = class {
 // src/iframe/iframe-auth.ts
 var DEFAULT_ANON_ID_STORAGE_KEY = "looplay:anon-id";
 var DEFAULT_ANONYMOUS_FALLBACK_TIMEOUT_MS = 4e3;
+var DEFAULT_REQUEST_ADS_TIMEOUT_MS = 5e3;
 var INITIAL_STATE = {
   jwt: null,
   gameId: null,
@@ -789,6 +790,12 @@ var LooplayIframeAuth = class {
   options;
   messageListener = null;
   anonymousFallbackTimer = null;
+  pendingAdsRequests = /* @__PURE__ */ new Map();
+  requestAdsSequence = 0;
+  adsRequestInFlight = false;
+  adsRequestsSent = 0;
+  lastAdsRequestAt = 0;
+  autoAdsActionCount = 0;
   constructor(options = {}) {
     this.options = options;
   }
@@ -823,8 +830,57 @@ var LooplayIframeAuth = class {
       this.debug("standalone mode detected; auth request skipped");
       return;
     }
-    this.debug("requesting auth from parent", { targetOrigin: this.resolveParentOrigin() ?? "*" });
-    window.parent.postMessage({ type: "LOOPLAY_AUTH_REQUEST" }, this.resolveParentOrigin() ?? "*");
+    this.debug("requesting auth from parent", {
+      targetOrigin: this.resolveParentOrigin() ?? "*"
+    });
+    window.parent.postMessage(
+      { type: "LOOPLAY_AUTH_REQUEST" },
+      this.resolveParentOrigin() ?? "*"
+    );
+  }
+  /**
+   * Requests the parent host to show a rewarded ad.
+   * In a Telegram Mini App setup, the game sends this request from the iframe
+   * and the parent page (the Mini App shell) bridges it to Adsgram, then
+   * responds with `LOOPLAY_ADS_WATCHED` after the ad finishes.
+   */
+  requestAds(options = {}) {
+    if (typeof window === "undefined" || window.parent === window) {
+      this.debug("requestAds skipped; standalone mode detected");
+      return Promise.resolve(false);
+    }
+    if (this.adsRequestInFlight) {
+      this.debug("requestAds skipped; another ad request is already in flight");
+      return Promise.resolve(false);
+    }
+    const parentOrigin = this.resolveParentOrigin() ?? "*";
+    const requestId = `ads-${Date.now()}-${++this.requestAdsSequence}`;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_REQUEST_ADS_TIMEOUT_MS;
+    this.adsRequestInFlight = true;
+    this.adsRequestsSent += 1;
+    this.lastAdsRequestAt = Date.now();
+    this.debug("requesting rewarded ad from parent", {
+      requestId,
+      targetOrigin: parentOrigin,
+      gameId: this.getGameId()
+    });
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        this.pendingAdsRequests.delete(requestId);
+        this.adsRequestInFlight = false;
+        this.debug("requestAds timed out", { requestId, timeoutMs });
+        resolve(false);
+      }, timeoutMs);
+      this.pendingAdsRequests.set(requestId, { resolve, timer });
+      window.parent.postMessage(
+        {
+          type: "LOOPLAY_REQUEST_ADS",
+          requestId,
+          gameId: this.getGameId()
+        },
+        parentOrigin
+      );
+    });
   }
   /** Idempotent; attaches the postMessage listener (if embedded) and arms the anonymous fallback. */
   init() {
@@ -848,14 +904,13 @@ var LooplayIframeAuth = class {
     this.messageListener = (event) => {
       if (event.source !== window.parent) return;
       if (parentOrigin && event.origin !== parentOrigin) {
-        this.debug("ignored auth message from unexpected origin", {
+        this.debug("ignored message from unexpected origin", {
           expectedOrigin: parentOrigin,
           receivedOrigin: event.origin
         });
         return;
       }
-      if (!isRecord(event.data) || event.data.type !== "LOOPLAY_AUTH") return;
-      this.handleAuthMessage(event.data, event.origin);
+      this.handleIncomingMessage(event.data, event.origin);
     };
     window.addEventListener("message", this.messageListener);
     this.anonymousFallbackTimer = setTimeout(() => {
@@ -872,6 +927,11 @@ var LooplayIframeAuth = class {
     if (this.anonymousFallbackTimer !== null) {
       clearTimeout(this.anonymousFallbackTimer);
     }
+    for (const pending of this.pendingAdsRequests.values()) {
+      if (pending.timer !== null) clearTimeout(pending.timer);
+      pending.resolve(false);
+    }
+    this.pendingAdsRequests.clear();
     this.messageListener = null;
     this.anonymousFallbackTimer = null;
     this.initialized = false;
@@ -894,7 +954,9 @@ var LooplayIframeAuth = class {
   trackView() {
     const gameId = this.getGameId();
     if (!this.canTrack() || !gameId) {
-      this.debug("trackView skipped; auth is not ready", { hasGameId: Boolean(gameId) });
+      this.debug("trackView skipped; auth is not ready", {
+        hasGameId: Boolean(gameId)
+      });
       return Promise.resolve(false);
     }
     this.debug("trackView dispatched", { gameId });
@@ -907,11 +969,17 @@ var LooplayIframeAuth = class {
   trackPlay(playTimeSeconds) {
     const gameId = this.getGameId();
     if (!this.canTrack() || !gameId) {
-      this.debug("trackPlay skipped; auth is not ready", { hasGameId: Boolean(gameId) });
+      this.debug("trackPlay skipped; auth is not ready", {
+        hasGameId: Boolean(gameId)
+      });
       return Promise.resolve(false);
     }
     this.debug("trackPlay dispatched", { gameId, playTimeSeconds });
-    return this.getClient().trackPlay(gameId, playTimeSeconds);
+    const result = this.getClient().trackPlay(gameId, playTimeSeconds);
+    void result.then((ok) => {
+      if (ok) this.recordAutoRequestAdsActivity();
+    }).catch(() => void 0);
+    return result;
   }
   trackMatch(matchId, opts) {
     const gameId = this.getGameId();
@@ -920,12 +988,16 @@ var LooplayIframeAuth = class {
       return Promise.resolve(false);
     }
     this.debug("trackMatch dispatched", { gameId, matchId, ...opts });
-    return this.getClient().trackMatch(gameId, {
+    const result = this.getClient().trackMatch(gameId, {
       matchId,
       matchDurationSeconds: opts.durationSeconds,
       isCompleted: opts.isCompleted,
       isWin: opts.isWin
     });
+    void result.then((ok) => {
+      if (ok) this.recordAutoRequestAdsActivity();
+    }).catch(() => void 0);
+    return result;
   }
   emitGameEvent(actionCode, opts) {
     const gameId = this.getGameId();
@@ -938,7 +1010,8 @@ var LooplayIframeAuth = class {
   }
   /** Idempotent; auto-emits GAME_STARTED exactly once per distinct auth session (bearer or anonymous). */
   initLifecycleTracking() {
-    if (this.lifecycleTrackingInitialized || typeof window === "undefined") return;
+    if (this.lifecycleTrackingInitialized || typeof window === "undefined")
+      return;
     this.lifecycleTrackingInitialized = true;
     this.debug("lifecycle tracking initialized");
     this.subscribe(() => {
@@ -988,7 +1061,9 @@ ${identity}`;
         origin,
         receivedAt: Date.now()
       });
-      this.debug("auth message missing game identity; falling back to anonymous tracking");
+      this.debug(
+        "auth message missing game identity; falling back to anonymous tracking"
+      );
       this.activateAnonymousMode();
       return;
     }
@@ -1002,10 +1077,13 @@ ${identity}`;
         origin,
         receivedAt: Date.now()
       });
-      this.debug("auth message missing jwt; falling back to anonymous tracking", {
-        gameId: resolvedGameId,
-        apiUrl: resolvedApiUrl
-      });
+      this.debug(
+        "auth message missing jwt; falling back to anonymous tracking",
+        {
+          gameId: resolvedGameId,
+          apiUrl: resolvedApiUrl
+        }
+      );
       this.activateAnonymousMode();
       return;
     }
@@ -1019,6 +1097,45 @@ ${identity}`;
       receivedAt: Date.now()
     });
   }
+  handleRequestAdsResult(data) {
+    if (data.type !== "LOOPLAY_ADS_WATCHED") return;
+    const requestId = toOptionalString(data.requestId);
+    if (!requestId) return;
+    const pending = this.pendingAdsRequests.get(requestId);
+    if (!pending) return;
+    this.pendingAdsRequests.delete(requestId);
+    if (pending.timer !== null) clearTimeout(pending.timer);
+    this.adsRequestInFlight = false;
+    this.debug("requestAds watched message received", { requestId });
+    pending.resolve(true);
+  }
+  handleRequestAdsUnavailable(data) {
+    if (data.type !== "LOOPLAY_ADS_UNAVAILABLE") return;
+    const requestId = toOptionalString(data.requestId);
+    if (!requestId) return;
+    const pending = this.pendingAdsRequests.get(requestId);
+    if (!pending) return;
+    this.pendingAdsRequests.delete(requestId);
+    if (pending.timer !== null) clearTimeout(pending.timer);
+    this.adsRequestInFlight = false;
+    this.debug("requestAds unavailable message received", { requestId });
+    pending.resolve(false);
+  }
+  handleIncomingMessage(data, origin) {
+    if (!isRecord(data)) return;
+    if (data.type === "LOOPLAY_AUTH") {
+      this.handleAuthMessage(data, origin);
+      return;
+    }
+    if (data.type === "LOOPLAY_ADS_WATCHED") {
+      this.handleRequestAdsResult(data);
+      return;
+    }
+    if (data.type === "LOOPLAY_ADS_UNAVAILABLE") {
+      this.handleRequestAdsUnavailable(data);
+      return;
+    }
+  }
   setState(next) {
     this.state = next;
     this.client = null;
@@ -1043,6 +1160,35 @@ ${identity}`;
   debug(message, details) {
     this.options.onDebug?.(message, details);
   }
+  recordAutoRequestAdsActivity() {
+    this.autoAdsActionCount += 1;
+    const config = this.options.autoRequestAds;
+    if (!config?.enabled) return;
+    if (this.adsRequestInFlight) return;
+    if (!this.canTrack()) return;
+    const now = Date.now();
+    if (config.cooldownMs && now - this.lastAdsRequestAt < config.cooldownMs) {
+      return;
+    }
+    if (config.maxRequestsPerSession && this.adsRequestsSent >= config.maxRequestsPerSession) {
+      return;
+    }
+    const threshold = config.afterActionCount ?? 0;
+    const shouldRequest = threshold > 0 && this.autoAdsActionCount % threshold === 0;
+    if (!shouldRequest) return;
+    const chance = config.chance ?? 1;
+    if (chance <= 0 || Math.random() > chance) {
+      this.debug("auto requestAds skipped by chance", {
+        actionCount: this.autoAdsActionCount,
+        chance
+      });
+      return;
+    }
+    this.debug("auto requestAds triggered", {
+      actionCount: this.autoAdsActionCount
+    });
+    void this.requestAds();
+  }
 };
 
 exports.ApiClient = ApiClient;