@looplay/sdk 0.8.2 → 0.8.4

package/README.md

@@ -1,7 +1,7 @@
 # @looplay/sdk
 
 Client SDK for games integrating with Looplay: player tracking (views, play
-attempts, matches, custom actions), the game's coin store (read-only), and
+sessions, matches, custom actions), the game's coin store (read-only), and
 authentication.
 
 API Reference: https://docs.looplay.gg/build-on-loopplay/looplay-sdk
@@ -63,29 +63,54 @@ backward compatibility, but you should set one regardless).
 ```ts
 import { LooplayIframeAuth } from '@looplay/sdk';
 
+// 1. Initialize the SDK
 export const looplayAuth = new LooplayIframeAuth({
   appId: 'YOUR_APP_ID', // from your creator dashboard
   apiUrl: 'https://api.looplay.gg', // required for standalone builds; optional inside the iframe
   parentOrigin: import.meta.env.VITE_PARENT_ORIGIN, // restrict the accepted postMessage origin
+  
+  // Optional: Auto-request rewarded ads after match activity
+  autoRequestAds: {
+    enabled: true,
+    afterActionCount: 3, // show ad every 3 actions/matches
+    chance: 0.5, // 50% chance to show ad
+    cooldownMs: 60000, // min 1 minute between requests
+    maxRequestsPerSession: 5,
+  }
 });
 
+// 2. Start listening for auth and lifecycle events
 looplayAuth.init();
 looplayAuth.initLifecycleTracking(); // auto-emits GAME_STARTED once per session
 
-// Anywhere in the game — identical code whether hosted on Looplay or not:
+// 3. Anywhere in the game — identical code whether hosted on Looplay or not:
 looplayAuth.canTrack();
 looplayAuth.subscribe((state) => { /* re-render when auth arrives/clears */ });
+
 await looplayAuth.trackView();
-looplayAuth.startAttempt(); // call once when the user presses Play
+
+// Call once when the user presses Play
+looplayAuth.startPlaySession(); 
+
+// Periodically track play time
 await looplayAuth.trackPlay(playTimeSeconds);
+
+// Track when a match/level ends
 await looplayAuth.trackMatch(matchId, { durationSeconds, isWin: true });
+
+// Emit custom actions for quests/analytics
 await looplayAuth.emitGameEvent('CUSTOM_ACTION', { value: 1 });
-await looplayAuth.requestAds();
+
+// Manually request rewarded ads (returns true if watched)
+const adWatched = await looplayAuth.requestAds();
+if (adWatched) {
+  // Give reward to the player
+}
 ```
 
-Every play attempt is backed by a short-lived, server-signed token — the SDK
+Every play session is backed by a short-lived, server-signed token — the SDK
 fetches and caches it automatically the first time `trackPlay`/`trackMatch`/
-`emitGameEvent` needs it after `startAttempt()`. You never see or manage
+`emitGameEvent` needs it after `startPlaySession()`. You never see or manage
 this token directly.
 
 ### Tracking call reference
@@ -93,8 +118,8 @@ this token directly.
 | Call | When |
 | --- | --- |
 | `trackView()` | Once when the game view opens, before any play/match tracking |
-| `startAttempt()` | Once when the user presses Play. Synchronous — returns an id immediately |
-| `trackPlay(playTimeSeconds?)` | Periodically / on pause, to report accumulated play time for the current attempt |
+| `startPlaySession()` | Once when the user presses Play. Synchronous — returns an id immediately |
+| `trackPlay(playTimeSeconds?)` | Periodically / on pause, to report accumulated play time for the current play session |
 | `trackMatch(matchId, { durationSeconds, isCompleted?, isWin? })` | Once per round/match end. `matchId` is the idempotency anchor — safe to call twice |
 | `emitGameEvent(actionCode, { value?, refId?, payload? })` | For quest/task progress and custom analytics — e.g. `'LEVEL_UP'`, `'ITEM_COLLECTED'` |
 
@@ -115,7 +140,7 @@ await sdk.init({ gameId: 'YOUR_APP_ID', verifyMode: 'strict' });
 // `gameId` here is the game's public appId (same as `x-game-key`/`appId` above).
 
 await sdk.trackView();
-sdk.startAttempt();
+sdk.startPlaySession();
 await sdk.trackPlay(playTimeSeconds);
 await sdk.trackMatch(matchId, { durationSeconds, isWin: true });
 await sdk.emit('CUSTOM_ACTION', { value: 1 });
@@ -145,7 +170,7 @@ const result = await sdk.api!.purchaseStoreOffer(gameId, 'starter_pack', { quant
 ```
 
 `purchaseStoreOffer` signs a short-lived checkout token and redeems it in
-one call — the same safety mechanism as the play-attempt token used for
+one call — the same safety mechanism as the play-session token used for
 tracking, not a static secret. This is enough for creators with no backend
 of their own.
 
@@ -238,6 +263,13 @@ request as `false` and continue normally.
 If the parent never answers, `requestAds()` times out after 5 seconds by
 default and resolves `false`.
 
+```ts
+const isWatched = await looplayAuth.requestAds();
+if (isWatched) {
+  // Grant reward to player
+}
+```
+
 ```ts
 window.addEventListener('message', async (event) => {
   const data = event.data;
@@ -282,7 +314,7 @@ directly, no bundler needed:
   looplayAuth.init();
   looplayAuth.initLifecycleTracking();
 
-  // call looplayAuth.trackView() / startAttempt() / trackPlay(...) /
+  // call looplayAuth.trackView() / startPlaySession() / trackPlay(...) /
   // trackMatch(...) / emitGameEvent(...) from your game code
 </script>
 ```

package/dist/looplay-sdk.cjs.js

@@ -261,16 +261,16 @@ var ServiceClient = class {
     });
     return true;
   }
-  /** Signs a fresh `attemptToken` — required by `completeGameplayAttempt`/`completeGameplayMatch`/`recordGameplayAction`. */
-  async startGameplayAttempt(gameKey, auth = {}, body = {}) {
-    return this.http.request("POST", "/sdk/games/attempts/start", {
+  /** Signs a fresh `playSessionToken` — required by `completePlaySession`/`completeGameplayMatch`/`recordGameplayAction`. */
+  async startPlaySession(gameKey, auth = {}, body = {}) {
+    return this.http.request("POST", "/sdk/games/play-sessions/start", {
       ...auth,
       headers: { "x-game-key": gameKey, ...this.trackingHeaders(auth) },
       body
     });
   }
-  async completeGameplayAttempt(gameKey, auth, body) {
-    await this.http.request("POST", "/sdk/games/attempts/complete", {
+  async completePlaySession(gameKey, auth, body) {
+    await this.http.request("POST", "/sdk/games/play-sessions/complete", {
       ...auth,
       headers: { "x-game-key": gameKey, ...this.trackingHeaders(auth) },
       body
@@ -302,6 +302,16 @@ var ServiceClient = class {
       headers: { "x-looplay-anon-id": anonId }
     });
   }
+  /**
+   * Lightweight integration heartbeat for review/liveops. This intentionally
+   * does not record a view/play metric.
+   */
+  async detectGameIntegration(gameKey) {
+    await this.http.request("POST", "/sdk/games/integration/detect", {
+      headers: { "x-game-key": gameKey }
+    });
+    return true;
+  }
   trackingHeaders(auth) {
     return {
       "x-game-tracking-session-id": auth.trackingSessionId,
@@ -339,7 +349,7 @@ var ServiceClient = class {
   // `x-game-key` + the purchasing player's own bearer token, no backend or
   // secret pair required. Safe to call directly from client/browser code —
   // `checkoutToken` (short-lived, server-signed) plays the same role as
-  // `attemptToken` on the tracking routes. `ApiClient.purchaseStoreOffer`
+  // `playSessionToken` on the tracking routes. `ApiClient.purchaseStoreOffer`
   // wraps this pair for you.
   // ─────────────────────────────────────────────────────────────────────────────
   /** Signs a `checkoutToken` for one purchase — required by `purchaseMyStoreOffer`. */
@@ -410,30 +420,6 @@ var ServiceClient = class {
   async getMyBalance(bearerToken) {
     return this.http.request("GET", "/sdk/user/balance", { bearerToken });
   }
-  // ─────────────────────────────────────────────────────────────────────────────
-  // Referrals
-  // ─────────────────────────────────────────────────────────────────────────────
-  async listReferrals(bearerToken, query) {
-    return this.http.request("GET", "/sdk/referrals", { bearerToken, query });
-  }
-  async setReferral(bearerToken, body) {
-    return this.http.request("POST", "/sdk/referrals/set", { bearerToken, body });
-  }
-  // ─────────────────────────────────────────────────────────────────────────────
-  // Tasks
-  // ─────────────────────────────────────────────────────────────────────────────
-  async listTasks(bearerToken, query) {
-    return this.http.request("GET", "/sdk/task", { bearerToken, query: { ...query } });
-  }
-  async listFinishedTasks(bearerToken, query) {
-    return this.http.request("GET", "/sdk/task/finished", { bearerToken, query: { ...query } });
-  }
-  async startTask(bearerToken, body) {
-    return this.http.request("POST", "/sdk/task/start", { bearerToken, body });
-  }
-  async claimTask(bearerToken, body) {
-    return this.http.request("POST", "/sdk/task/claim", { bearerToken, body });
-  }
 };
 
 // src/apps/api-client.ts
@@ -453,9 +439,9 @@ var ApiClient = class {
   getAnonymousId;
   trackingSession;
   trackingSessionPromise;
-  currentAttemptId;
-  gameplayAttempt;
-  gameplayAttemptPromise;
+  currentPlaySessionId;
+  playSession;
+  playSessionPromise;
   constructor(options) {
     if (!options.baseUrl) throw new MissingBaseUrlError();
     this.raw = new ServiceClient({
@@ -470,6 +456,9 @@ var ApiClient = class {
   unsafeRaw() {
     return this.raw;
   }
+  async detectIntegration(gameKey) {
+    return this.raw.detectGameIntegration(gameKey);
+  }
   // Real-time (balance_change / store_purchase_completed WebSocket events)
   // deliberately lives outside this class — import `WsClient` from
   // '@looplay/sdk/realtime' and construct it with the same `getAccessToken`
@@ -525,30 +514,30 @@ var ApiClient = class {
     return this.trackingSessionPromise;
   }
   /**
-   * Signs (and caches until near expiry) the `attemptToken` required by
-   * `trackPlay`/`trackMatch`/`emit` for the current attempt — does not
+   * Signs (and caches until near expiry) the `playSessionToken` required by
+   * `trackPlay`/`trackMatch`/`emit` for the current play session — does not
    * swallow failures, unlike `ensureTrackingSession`, since these calls
    * are rejected outright without a valid token.
    */
-  async ensureGameplayAttempt(gameKey, auth, attemptId) {
+  async ensurePlaySession(gameKey, auth, playSessionId) {
     const now = Date.now();
-    if (this.gameplayAttempt && this.gameplayAttempt.gameKey === gameKey && this.gameplayAttempt.attemptId === attemptId && this.gameplayAttempt.expiresAtMs > now + 1e4) {
-      return this.gameplayAttempt;
+    if (this.playSession && this.playSession.gameKey === gameKey && this.playSession.playSessionId === playSessionId && this.playSession.expiresAtMs > now + 1e4) {
+      return this.playSession;
     }
-    if (!this.gameplayAttemptPromise) {
-      this.gameplayAttemptPromise = this.raw.startGameplayAttempt(gameKey, auth, { attemptId }).then((dto) => {
-        this.gameplayAttempt = {
+    if (!this.playSessionPromise) {
+      this.playSessionPromise = this.raw.startPlaySession(gameKey, auth, { playSessionId }).then((dto) => {
+        this.playSession = {
           gameKey,
-          attemptId: dto.attemptId,
-          attemptToken: dto.attemptToken,
+          playSessionId: dto.playSessionId,
+          playSessionToken: dto.playSessionToken,
           expiresAtMs: new Date(dto.expiresAt).getTime()
         };
-        return this.gameplayAttempt;
+        return this.playSession;
       }).finally(() => {
-        this.gameplayAttemptPromise = void 0;
+        this.playSessionPromise = void 0;
       });
     }
-    return this.gameplayAttemptPromise;
+    return this.playSessionPromise;
   }
   /**
    * Call once when the game view opens, before any play/match tracking.
@@ -559,35 +548,35 @@ var ApiClient = class {
     return this.raw.recordGameView(gameKey, auth);
   }
   /**
-   * Starts a new play attempt and returns its id. Call when the user
+   * Starts a new play session and returns its id. Call when the user
    * presses Play; `trackPlay`/`trackMatch`/`emit` reuse this id (and the
-   * signed `attemptToken` backing it) across calls until the next
-   * `startAttempt()`, auto-starting one on first use if none was started.
+   * signed `playSessionToken` backing it) across calls until the next
+   * `startPlaySession()`, auto-starting one on first use if none was started.
    */
-  startAttempt() {
-    this.currentAttemptId = generateId();
-    this.gameplayAttempt = void 0;
-    return this.currentAttemptId;
+  startPlaySession() {
+    this.currentPlaySessionId = generateId();
+    this.playSession = void 0;
+    return this.currentPlaySessionId;
   }
   async trackPlay(gameKey, playTimeSeconds) {
     const auth = await this.resolveTrackingAuth();
-    const attemptId = this.currentAttemptId ?? this.startAttempt();
-    const { attemptToken } = await this.ensureGameplayAttempt(gameKey, auth, attemptId);
-    return this.raw.completeGameplayAttempt(gameKey, auth, { playTimeSeconds, attemptId, attemptToken });
+    const playSessionId = this.currentPlaySessionId ?? this.startPlaySession();
+    const { playSessionToken } = await this.ensurePlaySession(gameKey, auth, playSessionId);
+    return this.raw.completePlaySession(gameKey, auth, { playTimeSeconds, playSessionId, playSessionToken });
   }
   async trackMatch(gameKey, body) {
     const auth = await this.resolveTrackingAuth();
-    const attemptId = this.currentAttemptId ?? this.startAttempt();
-    const { attemptToken } = await this.ensureGameplayAttempt(gameKey, auth, attemptId);
-    return this.raw.completeGameplayMatch(gameKey, auth, { ...body, attemptId, attemptToken });
+    const playSessionId = this.currentPlaySessionId ?? this.startPlaySession();
+    const { playSessionToken } = await this.ensurePlaySession(gameKey, auth, playSessionId);
+    return this.raw.completeGameplayMatch(gameKey, auth, { ...body, playSessionId, playSessionToken });
   }
   async emit(gameKey, actionCode, opts) {
     const auth = await this.resolveTrackingAuth();
-    const attemptId = this.currentAttemptId ?? this.startAttempt();
-    const { attemptToken } = await this.ensureGameplayAttempt(gameKey, auth, attemptId);
+    const playSessionId = this.currentPlaySessionId ?? this.startPlaySession();
+    const { playSessionToken } = await this.ensurePlaySession(gameKey, auth, playSessionId);
     const body = {
-      attemptId,
-      attemptToken,
+      playSessionId,
+      playSessionToken,
       actionCode,
       value: opts?.value,
       refId: opts?.refId,
@@ -615,7 +604,7 @@ var ApiClient = class {
   }
   /**
    * Spends coin balance to purchase a store offer — signs a checkout intent
-   * first, then redeems it, mirroring the gameplay attempt flow above.
+   * first, then redeems it, mirroring the play session flow above.
    * Self-serve: only the player's own access token is used, no secret pair
    * required, safe to call directly from the game client. Also see
    * `onStorePurchase` to react to the result in real time from any tab.
@@ -650,30 +639,6 @@ var ApiClient = class {
     const token = await this.requireToken();
     return this.raw.getBalanceHistory(token, query);
   }
-  async listReferrals(query) {
-    const token = await this.requireToken();
-    return this.raw.listReferrals(token, query);
-  }
-  async setReferral(body) {
-    const token = await this.requireToken();
-    return this.raw.setReferral(token, body);
-  }
-  async listTasks(query) {
-    const token = await this.requireToken();
-    return this.raw.listTasks(token, query);
-  }
-  async listFinishedTasks(query) {
-    const token = await this.requireToken();
-    return this.raw.listFinishedTasks(token, query);
-  }
-  async startTask(body) {
-    const token = await this.requireToken();
-    return this.raw.startTask(token, body);
-  }
-  async claimTask(body) {
-    const token = await this.requireToken();
-    return this.raw.claimTask(token, body);
-  }
 };
 
 // src/looplay-sdk.ts
@@ -699,6 +664,7 @@ var LooplaySDK = class {
   async init(params) {
     this.gameId = params.gameId;
     await this.auth?.init();
+    await this.detectIntegration(params);
     await this.verifyGameId(params);
     this.initialized = true;
   }
@@ -720,11 +686,11 @@ var LooplaySDK = class {
     if (!this.gameId) throw new NotInitializedError();
     return this.api.trackView(this.gameId);
   }
-  /** Starts a new play attempt; call when the user presses Play. Returns the attempt id. */
-  startAttempt() {
+  /** Starts a new play session; call when the user presses Play. Returns the play session id. */
+  startPlaySession() {
     this.assertInitialized();
     if (!this.api) throw new MissingBaseUrlError();
-    return this.api.startAttempt();
+    return this.api.startPlaySession();
   }
   async trackPlay(playTimeSeconds) {
     this.assertInitialized();
@@ -767,6 +733,10 @@ var LooplaySDK = class {
     if (!this.api) throw new MissingBaseUrlError();
     await this.api.listGameAssets(params.gameId);
   }
+  async detectIntegration(params) {
+    if (!this.api) return;
+    await this.api.detectIntegration(params.gameId);
+  }
 };
 
 // src/auth/jwt.ts
@@ -1092,9 +1062,9 @@ var LooplayIframeAuth = class {
     this.debug("trackView dispatched", { gameId });
     return this.getClient().trackView(gameId);
   }
-  /** Starts a new play attempt; call when the user presses Play. Returns the attempt id. */
-  startAttempt() {
-    return this.getClient().startAttempt();
+  /** Starts a new play session; call when the user presses Play. Returns the play session id. */
+  startPlaySession() {
+    return this.getClient().startPlaySession();
   }
   trackPlay(playTimeSeconds) {
     const gameId = this.getGameId();