@playruo/embed 1.3.3 → 1.5.0

package/README.md

@@ -2,6 +2,12 @@
 
 React SDK to embed Playruo via iframe + postMessage.
 
+## Documentation
+
+- Integrator overview and React/vanilla guides: [`docs/`](./docs/)
+- Protocol reference for webapp ↔ SDK changes: [`DOCUMENTATION.md`](./DOCUMENTATION.md)
+- Customer Notion pages are generated from `docs/` via `npm run docs:notion:dry-run` / `npm run docs:notion:publish`
+
 ## Windowed launch
 
 `PlayruoEmbed` requests browser fullscreen on the iframe when the user starts a
@@ -17,6 +23,92 @@ start the experience inside the current iframe bounds:
 />
 ```
 
+## Campaigns with several operations
+
+`operation` is the campaign path. When the campaign holds more than one
+operation, name the one to open with `operationKey`, sent as `?op=`:
+
+```tsx
+<PlayruoEmbed
+  operation="crypticalpath"
+  operationKey="crypticalpath-fr"
+/>
+```
+
+Passing it inside `operation` (`"crypticalpath?op=..."`) still works and warns:
+it was the only way before this prop existed. `operationKey` wins over it. Other
+query parameters in `operation` are kept as they are.
+
+## Host-owned visitor identity
+
+By default the SDK stores a UUID in `localStorage["playruo_uuid"]` and answers
+`playruo_uuid_request` with it. Pass `clientFingerprint` when the host already
+has a stable visitor id (account id, CRM id, …): that value is answered as
+`uuid` instead, and localStorage is left alone. Playruo derives the session
+fingerprint from it.
+
+```tsx
+<PlayruoEmbed
+  operation="crypticalpath"
+  clientFingerprint={visitorId}
+/>
+```
+
+A vanilla host answers the same way, with no React:
+
+```js
+iframe.contentWindow.postMessage(
+  {
+    type: "playruo_uuid_response",
+    requestId,
+    uuid: visitorId,
+  },
+  "https://playruo.live",
+);
+```
+
+`resolveVisitorUuid(visitorId)` from this package is the shared helper both
+paths use. A blank or whitespace-only value is ignored and the SDK-managed UUID
+is used.
+
+## Password protected operations
+
+A protected operation renders no form of its own: it announces the gate and the
+host collects the password. Read the gate from `renderState` and answer with the
+actions:
+
+```tsx
+<PlayruoEmbed
+  operation="crypticalpath"
+  onPasswordRequired={() => setAsking(true)}
+  onPasswordResult={({ success }) => setAsking(!success)}
+  renderState={({ password, actions }) =>
+    password.required && !password.unlocked ? (
+      <PasswordForm error={password.error} onSubmit={actions.submitPassword} />
+    ) : null
+  }
+/>
+```
+
+The announce is emitted once, when the operation's configuration is loaded, so a
+host that mounts later misses it: call `actions.requestPassword()` to have it
+sent again. `password.checked` tells the two silences apart — an operation that
+has not answered yet, and one that answered it is not protected.
+
+`password.required` stays true after a successful unlock, so read
+`password.unlocked` for the gate itself. A refusal carries a code in
+`password.error`, typed as `PlayruoPasswordErrorCode`.
+
+## Message origin
+
+Messages are only accepted from the iframe's own window **and** from the origin
+`operation`/`baseUrl` point at, and every message sent to the iframe is
+addressed to that same origin rather than to `"*"`. A playable served from an
+origin other than the one the embed URL was built with is therefore ignored.
+
+Events forwarded one level up, to the host page's own parent, still go to `"*"`:
+that origin is not something this package can know.
+
 ## Event forwarding
 
 When the embedded Playruo iframe sends `{ type: "playruo_event", data }`, the

package/dist/index.cjs

@@ -31,10 +31,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   EmbedTester: () => EmbedTester,
+  PLAYRUO_UUID_STORAGE_KEY: () => PLAYRUO_UUID_STORAGE_KEY,
   PlayruoEmbed: () => PlayruoEmbed,
   buildEmbedUrl: () => buildEmbedUrl,
   isPlayruoEmbedMessage: () => isPlayruoEmbedMessage,
-  isPlayruoInternalMessage: () => isPlayruoInternalMessage
+  isPlayruoInternalMessage: () => isPlayruoInternalMessage,
+  resolveVisitorUuid: () => resolveVisitorUuid
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -48,27 +50,72 @@ var normalizeOperation = (operation) => {
   if (trimmedOperation === "") {
     throw new Error("`operation` is required to build a Playruo embed URL.");
   }
+  const operationQuery = trimmedOperation.split("?")[1];
+  if (operationQuery != null && new URLSearchParams(operationQuery).has("op")) {
+    console.warn(
+      "[PlayruoEmbed] `?op=` inside `operation` is deprecated: pass it as the `operationKey` prop."
+    );
+  }
   return trimmedOperation.startsWith("/") ? trimmedOperation.slice(1) : trimmedOperation;
 };
-var buildEmbedUrl = ({ operation, storeUrl }) => {
-  return buildEmbedUrlWithOrigin(PLAYRUO_ORIGIN, { operation, storeUrl });
+var buildEmbedUrl = ({
+  operation,
+  operationKey,
+  storeUrl
+}) => {
+  return buildEmbedUrlWithOrigin(PLAYRUO_ORIGIN, {
+    operation,
+    operationKey,
+    storeUrl
+  });
 };
-var buildEmbedUrlWithOrigin = (origin, { operation, storeUrl }) => {
+var buildEmbedUrlWithOrigin = (origin, { operation, operationKey, storeUrl }) => {
   const operationPath = normalizeOperation(operation);
   const url = new URL(`/${operationPath}`, origin);
   url.searchParams.set("iframe", "true");
+  const trimmedOperationKey = operationKey?.trim();
+  if (trimmedOperationKey) {
+    url.searchParams.set("op", trimmedOperationKey);
+  }
   if (storeUrl) {
     url.searchParams.set("storeUrl", storeUrl);
   }
   return url.toString();
 };
 
+// src/visitor-uuid.ts
+var PLAYRUO_UUID_STORAGE_KEY = "playruo_uuid";
+var generateUUID = () => {
+  if (self.crypto.randomUUID) return self.crypto.randomUUID();
+  const bytes = new Uint8Array(16);
+  self.crypto.getRandomValues(bytes);
+  bytes[6] = bytes[6] & 15 | 64;
+  bytes[8] = bytes[8] & 63 | 128;
+  return [...bytes].map(
+    (b, i) => ([4, 6, 8, 10].includes(i) ? "-" : "") + b.toString(16).padStart(2, "0")
+  ).join("");
+};
+var resolveVisitorUuid = (clientFingerprint) => {
+  const provided = clientFingerprint?.trim();
+  if (provided) {
+    return provided;
+  }
+  let uuid = localStorage.getItem(PLAYRUO_UUID_STORAGE_KEY);
+  if (!uuid) {
+    uuid = generateUUID();
+    localStorage.setItem(PLAYRUO_UUID_STORAGE_KEY, uuid);
+  }
+  return uuid;
+};
+
 // src/react/playruo-embed.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
 var PlayruoEmbed = ({
   baseUrl,
   operation,
+  operationKey,
   storeUrl,
+  clientFingerprint,
   showIframe = false,
   className,
   onReady,
@@ -77,6 +124,8 @@ var PlayruoEmbed = ({
   onEvent,
   onPurchaseRequest,
   onError,
+  onPasswordRequired,
+  onPasswordResult,
   enableWindowedLaunch = false,
   forwardEventsToParent = true,
   renderState,
@@ -94,12 +143,24 @@ var PlayruoEmbed = ({
   const [isValidChromium, setIsValidChromium] = (0, import_react.useState)(true);
   const [errorMessage, setErrorMessage] = (0, import_react.useState)(null);
   const [iframeState, setIframeState] = (0, import_react.useState)(null);
+  const [passwordRequired, setPasswordRequired] = (0, import_react.useState)(false);
+  const [passwordChecked, setPasswordChecked] = (0, import_react.useState)(false);
+  const [passwordUnlocked, setPasswordUnlocked] = (0, import_react.useState)(false);
+  const [passwordError, setPasswordError] = (0, import_react.useState)(
+    void 0
+  );
   const src = (0, import_react.useMemo)(
-    () => baseUrl != null && baseUrl !== "" ? buildEmbedUrlWithOrigin(baseUrl, { operation, storeUrl }) : buildEmbedUrl({ operation, storeUrl }),
-    [baseUrl, operation, storeUrl]
+    () => baseUrl != null && baseUrl !== "" ? buildEmbedUrlWithOrigin(baseUrl, { operation, operationKey, storeUrl }) : buildEmbedUrl({ operation, operationKey, storeUrl }),
+    [baseUrl, operation, operationKey, storeUrl]
   );
+  const embedOrigin = (0, import_react.useMemo)(() => new URL(src).origin, [src]);
+  (0, import_react.useEffect)(() => {
+    setPasswordRequired(false);
+    setPasswordChecked(false);
+    setPasswordUnlocked(false);
+    setPasswordError(void 0);
+  }, [src]);
   (0, import_react.useEffect)(() => {
-    if (typeof window === "undefined") return;
     const detectMobile = () => {
       const userAgent = navigator.userAgent || navigator.vendor || window.opera;
       return /android|iPad|iPhone|iPod/i.test(userAgent);
@@ -137,15 +198,14 @@ var PlayruoEmbed = ({
       tryNow: {
         ...currentState.tryNow,
         available: hasIframeConfirmed,
-        status: currentState.tryNow.status ?? (hasIframeConfirmed ? "Ready" : isCompatible ? "Checking availability\u2026" : "Browser not compatible")
+        // A missing status means the state came from the iframe, which only loads on
+        // compatible browsers — the incompatible copy is supplied by currentState.
+        status: currentState.tryNow.status ?? (hasIframeConfirmed ? "Ready" : "Checking availability\u2026")
       }
     }),
-    [currentState, hasIframeConfirmed, isCompatible]
+    [currentState, hasIframeConfirmed]
   );
   const getKeyboardApi = (0, import_react.useCallback)(() => {
-    if (typeof navigator === "undefined") {
-      return void 0;
-    }
     return navigator.keyboard;
   }, []);
   const releaseEscapeKeyLock = (0, import_react.useCallback)(() => {
@@ -175,6 +235,23 @@ var PlayruoEmbed = ({
     },
     [onDemoCompleted, storeUrl]
   );
+  const postPasswordAction = (0, import_react.useCallback)(
+    (message) => {
+      const contentWindow = iframeRef.current?.contentWindow;
+      if (!contentWindow) {
+        return;
+      }
+      try {
+        contentWindow.postMessage(
+          { type: "playruo", fromEmbed: true, ...message },
+          embedOrigin
+        );
+      } catch {
+        console.error("[PlayruoEmbed] Failed to send the password action");
+      }
+    },
+    [embedOrigin, iframeRef]
+  );
   const postExitFullscreenToIframe = (0, import_react.useCallback)(() => {
     const iframe = iframeRef.current;
     if (!iframe) {
@@ -187,22 +264,22 @@ var PlayruoEmbed = ({
         fromEmbed: true,
         isFullscreen: false,
         parentWillHandleFullscreen: true
-      }, "*");
+      }, embedOrigin);
     } catch {
       console.error("[PlayruoEmbed] Failed to exit fullscreen");
     }
-  }, [iframeRef]);
+  }, [embedOrigin, iframeRef]);
   const postExitFullscreenAckToIframe = (0, import_react.useCallback)(() => {
     const iframe = iframeRef.current;
     if (!iframe) {
       return;
     }
     try {
-      iframe.contentWindow?.postMessage({ type: "ACK_EXIT_FULLSCREEN" }, "*");
+      iframe.contentWindow?.postMessage({ type: "ACK_EXIT_FULLSCREEN" }, embedOrigin);
     } catch {
       console.error("[PlayruoEmbed] Failed to acknowledge fullscreen exit");
     }
-  }, [iframeRef]);
+  }, [embedOrigin, iframeRef]);
   const exitEmbedFullscreen = (0, import_react.useCallback)(
     async ({
       reason = "cleanup",
@@ -288,7 +365,7 @@ var PlayruoEmbed = ({
   }, []);
   const forwardEventToParent = (0, import_react.useCallback)(
     (message) => {
-      if (!forwardEventsToParent || typeof window === "undefined" || window.parent === window) {
+      if (!forwardEventsToParent || window.parent === window) {
         return;
       }
       try {
@@ -357,7 +434,7 @@ var PlayruoEmbed = ({
         isFullscreen: isParentFullscreen,
         parentWillHandleFullscreen: isParentFullscreen,
         isReplay: hasPlayedOnce
-      }, "*");
+      }, embedOrigin);
       console.log("[PlayruoEmbed] Sent tryNowClick to game", hasPlayedOnce ? "(replay)" : "(first time)");
       iframe.focus();
       requestAnimationFrame(() => {
@@ -404,6 +481,9 @@ var PlayruoEmbed = ({
       if (!iframe || event.source !== iframe.contentWindow) {
         return;
       }
+      if (event.origin !== embedOrigin) {
+        return;
+      }
       console.log("\u{1F537} [Embed] Message received from iframe:", { type, data });
       if (type === "playruo_ready") {
         console.log("\u{1F537} [Embed] playruo_ready received");
@@ -472,6 +552,24 @@ var PlayruoEmbed = ({
         const eventPayload = message.payload;
         onEvent?.(eventPayload);
         forwardEventToParent({ type: "playruo_event", data: eventPayload });
+      } else if (type === "playruo_password_required") {
+        console.log("\u{1F537} [Embed] playruo_password_required received");
+        setPasswordRequired(true);
+        setPasswordChecked(true);
+        setPasswordUnlocked(false);
+        setPasswordError(void 0);
+        onPasswordRequired?.();
+      } else if (type === "playruo_password_not_required") {
+        console.log("\u{1F537} [Embed] playruo_password_not_required received");
+        setPasswordRequired(false);
+        setPasswordChecked(true);
+      } else if (type === "playruo_password_result" && data) {
+        const result = data;
+        const success = result.success === true;
+        console.log("\u{1F537} [Embed] playruo_password_result received:", result);
+        setPasswordUnlocked(success);
+        setPasswordError(success ? void 0 : result.error ?? "unknown");
+        onPasswordResult?.({ success, error: result.error });
       }
       if (type === "error" || type === "closeForBuy" || type === "goToStore") {
         console.log("\u{1F537} [Embed] Legacy message received:", type);
@@ -487,6 +585,7 @@ var PlayruoEmbed = ({
     return () => window.removeEventListener("message", handleGameMessage);
   }, [
     cleanupEmbedSession,
+    embedOrigin,
     exitEmbedFullscreen,
     forwardEventToParent,
     hasPlayedOnce,
@@ -494,70 +593,53 @@ var PlayruoEmbed = ({
     markStreamActive,
     onEvent,
     onError,
+    onPasswordRequired,
+    onPasswordResult,
     onPurchaseRequest,
     onReady,
     onStateChange,
     postExitFullscreenAckToIframe,
     storeUrl
   ]);
-  const generateUUID = () => {
-    if (self.crypto.randomUUID) return self.crypto.randomUUID();
-    const bytes = new Uint8Array(16);
-    self.crypto.getRandomValues(bytes);
-    bytes[6] = bytes[6] & 15 | 64;
-    bytes[8] = bytes[8] & 63 | 128;
-    return [...bytes].map(
-      (b, i) => ([4, 6, 8, 10].includes(i) ? "-" : "") + b.toString(16).padStart(2, "0")
-    ).join("");
-  };
   (0, import_react.useEffect)(() => {
     const handleUUIDMessage = (event) => {
       const iframe = iframeRef.current;
       if (!iframe || event.source !== iframe.contentWindow) {
         return;
       }
+      if (event.origin !== embedOrigin) {
+        return;
+      }
       const { type, requestId } = event.data || {};
       if (type === "playruo_uuid_request") {
         try {
-          let storedUUID = localStorage.getItem("playruo_uuid");
-          if (!storedUUID) {
-            storedUUID = generateUUID();
-            localStorage.setItem("playruo_uuid", storedUUID);
-          }
           iframe.contentWindow?.postMessage(
             {
               type: "playruo_uuid_response",
               requestId,
-              uuid: storedUUID
+              uuid: resolveVisitorUuid(clientFingerprint)
             },
-            "*"
+            embedOrigin
           );
         } catch (e) {
         }
-      } else if (type === "playruo_uuid_remove") {
-        try {
-          localStorage.removeItem("playruo_uuid");
-        } catch (e) {
-        }
       }
     };
     window.addEventListener("message", handleUUIDMessage);
     return () => window.removeEventListener("message", handleUUIDMessage);
-  }, [iframeRef]);
+  }, [clientFingerprint, embedOrigin, iframeRef]);
   (0, import_react.useEffect)(() => {
     const handleFullscreenChange = () => {
       const iframe = iframeRef.current;
       const fullscreenElement = getFullscreenElement();
       const isEmbedFullscreen = Boolean(iframe && fullscreenElement === iframe);
-      if (isEmbedFullscreen) {
+      if (isEmbedFullscreen && iframe) {
         wasEmbedFullscreenRef.current = true;
         void lockEscapeKey();
-        if (iframe) {
-          setTimeout(() => {
-            iframe.focus();
-            iframe.contentWindow?.focus();
-          }, 200);
-        }
+        setTimeout(() => {
+          iframe.focus();
+          iframe.contentWindow?.focus();
+        }, 200);
         return;
       }
       if (fullscreenElement) {
@@ -602,17 +684,16 @@ var PlayruoEmbed = ({
     const logCrossOriginStatus = () => {
       const isIsolated = self.crossOriginIsolated;
       const hasSharedArrayBuffer = typeof SharedArrayBuffer !== "undefined";
-      const hasHighResTime = typeof performance !== "undefined" && typeof performance.now === "function";
       console.group("[PlayruoEmbed] \u{1F512} Cross-Origin Isolation Status");
       if (isIsolated) {
         console.log("\u2705 Cross-origin isolation: ENABLED");
         console.log("\u2705 SharedArrayBuffer support:", hasSharedArrayBuffer ? "Available" : "Not available");
-        console.log("\u2705 High-resolution timers:", hasHighResTime ? "Available" : "Not available");
+        console.log("\u2705 High-resolution timers: Full precision");
         console.log("\u{1F3AE} Game performance: Optimal");
       } else {
         console.warn("\u26A0\uFE0F Cross-origin isolation: DISABLED");
         console.warn("\u26A0\uFE0F SharedArrayBuffer support:", hasSharedArrayBuffer ? "Available" : "Not available");
-        console.warn("\u26A0\uFE0F High-resolution timers:", hasHighResTime ? "Available" : "Not available");
+        console.warn("\u26A0\uFE0F High-resolution timers: Reduced precision");
         console.warn("\u{1F3AE} Game performance: May be degraded");
         console.group("\u{1F4CB} Setup Instructions:");
         console.log("Add these headers to your server:");
@@ -656,7 +737,7 @@ var PlayruoEmbed = ({
         console.log("User agent:", navigator.userAgent);
         console.log("Available APIs:", {
           SharedArrayBuffer: hasSharedArrayBuffer,
-          Performance: hasHighResTime,
+          Performance: true,
           WebGL: !!document.createElement("canvas").getContext("webgl"),
           WebGL2: !!document.createElement("canvas").getContext("webgl2"),
           WebAssembly: typeof WebAssembly !== "undefined"
@@ -688,22 +769,44 @@ var PlayruoEmbed = ({
       tryNow: handleTryNow,
       buyNow: handleBuyNow,
       canTryNow,
-      canBuyNow: Boolean(isReady)
+      canBuyNow: Boolean(isReady),
+      submitPassword: (password2) => {
+        if (!password2) {
+          return;
+        }
+        postPasswordAction({ action: "submitPassword", password: password2 });
+      },
+      requestPassword: () => postPasswordAction({ action: "requestPassword" })
+    };
+    const password = {
+      required: passwordRequired,
+      checked: passwordChecked,
+      unlocked: passwordUnlocked,
+      error: passwordError
     };
     if (errorMessage) {
-      return renderState({ status: "error", message: errorMessage, actions });
+      return renderState({ status: "error", message: errorMessage, actions, password });
+    }
+    if (password.required && !password.unlocked) {
+      return renderState({
+        status: "loading",
+        message: "Password required",
+        actions,
+        password
+      });
     }
     if (!isReady) {
-      return renderState({ status: "loading", message: "Loading\u2026", actions });
+      return renderState({ status: "loading", message: "Loading\u2026", actions, password });
     }
     if (isCompatible && !iframeState) {
-      return renderState({ status: "loading", message: "Checking availability\u2026", actions });
+      return renderState({ status: "loading", message: "Checking availability\u2026", actions, password });
     }
     const message = !isAvailable ? currentState.tryNow.status ?? exposedState.tryNow.status : void 0;
     return renderState({
       status: isAvailable ? "available" : "unavailable",
       message,
-      actions
+      actions,
+      password
     });
   };
   return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className, children: [
@@ -749,12 +852,6 @@ var PlayruoEmbed = ({
         },
         onLoad: () => {
           setIsIframeLoaded(true);
-          setTimeout(() => {
-            if (iframeRef.current) {
-              iframeRef.current.focus();
-              iframeRef.current.contentWindow?.focus();
-            }
-          }, 500);
         },
         onError: () => {
           console.error("[PlayruoEmbed] Iframe failed to load");
@@ -930,20 +1027,11 @@ var EmbedTester = (props = {}) => {
     addEvent(message);
   }, [addEvent]);
   const handleApply = (0, import_react2.useCallback)(() => {
-    if (!hasPendingConfigChanges) {
-      return;
-    }
     setAppliedOperation(operationDraft);
     setAppliedStoreUrl(storeUrlDraft);
     setAppliedEnableWindowedLaunch(enableWindowedLaunchDraft);
     resetEmbedSession("Applied updated embed settings");
-  }, [
-    enableWindowedLaunchDraft,
-    hasPendingConfigChanges,
-    operationDraft,
-    resetEmbedSession,
-    storeUrlDraft
-  ]);
+  }, [enableWindowedLaunchDraft, operationDraft, resetEmbedSession, storeUrlDraft]);
   const handleRestartSession = (0, import_react2.useCallback)(() => {
     resetEmbedSession("Embed restarted with applied settings");
   }, [resetEmbedSession]);
@@ -2047,18 +2135,20 @@ var isPlayruoEmbedMessage = (data) => {
   if (!data || typeof data !== "object") return false;
   const msg = data;
   if (typeof msg.type !== "string") return false;
-  return msg.type === "playruo_ready" || msg.type === "playruo_state_update" || msg.type === "playruo_purchase_request" || msg.type === "playruo_demo_completed" || msg.type === "playruo_error" || msg.type === "playruo_session_over" || msg.type === "playruo_stream_start" || msg.type === "playruo_stream_stop" || msg.type === "REQUEST_EXIT_FULLSCREEN" || msg.type === "playruo_event";
+  return msg.type === "playruo_ready" || msg.type === "playruo_state_update" || msg.type === "playruo_purchase_request" || msg.type === "playruo_demo_completed" || msg.type === "playruo_error" || msg.type === "playruo_session_over" || msg.type === "playruo_stream_start" || msg.type === "playruo_stream_stop" || msg.type === "REQUEST_EXIT_FULLSCREEN" || msg.type === "playruo_event" || msg.type === "playruo_password_required" || msg.type === "playruo_password_not_required" || msg.type === "playruo_password_result";
 };
 var isPlayruoInternalMessage = (data) => {
   if (!data || typeof data !== "object") return false;
   const msg = data;
-  return msg.type === "playruo" && typeof msg.action === "string" && (msg.action === "tryNowClick" || msg.action === "exitFullscreen" || msg.action === "mute" || msg.action === "unmute") && msg.fromEmbed === true;
+  return msg.type === "playruo" && typeof msg.action === "string" && (msg.action === "tryNowClick" || msg.action === "exitFullscreen" || msg.action === "mute" || msg.action === "unmute" || msg.action === "submitPassword" || msg.action === "requestPassword") && msg.fromEmbed === true;
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   EmbedTester,
+  PLAYRUO_UUID_STORAGE_KEY,
   PlayruoEmbed,
   buildEmbedUrl,
   isPlayruoEmbedMessage,
-  isPlayruoInternalMessage
+  isPlayruoInternalMessage,
+  resolveVisitorUuid
 });