@playruo/embed 1.4.0 → 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
@@ -33,6 +39,38 @@ 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

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);
 
@@ -81,6 +83,31 @@ var buildEmbedUrlWithOrigin = (origin, { operation, operationKey, 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 = ({
@@ -88,6 +115,7 @@ var PlayruoEmbed = ({
   operation,
   operationKey,
   storeUrl,
+  clientFingerprint,
   showIframe = false,
   className,
   onReady,
@@ -573,16 +601,6 @@ var PlayruoEmbed = ({
     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;
@@ -595,16 +613,11 @@ var PlayruoEmbed = ({
       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
           );
@@ -614,7 +627,7 @@ var PlayruoEmbed = ({
     };
     window.addEventListener("message", handleUUIDMessage);
     return () => window.removeEventListener("message", handleUUIDMessage);
-  }, [embedOrigin, iframeRef]);
+  }, [clientFingerprint, embedOrigin, iframeRef]);
   (0, import_react.useEffect)(() => {
     const handleFullscreenChange = () => {
       const iframe = iframeRef.current;
@@ -839,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");
@@ -2138,8 +2145,10 @@ var isPlayruoInternalMessage = (data) => {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   EmbedTester,
+  PLAYRUO_UUID_STORAGE_KEY,
   PlayruoEmbed,
   buildEmbedUrl,
   isPlayruoEmbedMessage,
-  isPlayruoInternalMessage
+  isPlayruoInternalMessage,
+  resolveVisitorUuid
 });

package/dist/index.d.cts

@@ -180,6 +180,13 @@ interface PlayruoEmbedProps {
      */
     operationKey?: string;
     storeUrl?: string;
+    /**
+     * Stable visitor identity the host already owns (account id, CRM id, …).
+     * When set, answers `playruo_uuid_request` with this value and skips
+     * `localStorage["playruo_uuid"]`. Omit to keep the SDK-managed UUID.
+     * Playruo derives the session fingerprint from the answered `uuid`.
+     */
+    clientFingerprint?: string;
     showIframe?: boolean;
     className?: string;
     onReady?: () => void;
@@ -250,4 +257,12 @@ interface BuildUrlParams {
  */
 declare const buildEmbedUrl: ({ operation, operationKey, storeUrl, }: BuildUrlParams) => string;
 
-export { type DemoCompletedPayload, EmbedTester, type EmbedTesterProps, type PlayruoDemoCompletedMessage, PlayruoEmbed, type PlayruoEmbedActions, type PlayruoEmbedMessage, type PlayruoEmbedPasswordState, type PlayruoEmbedProps, type PlayruoEmbedRenderState, type PlayruoEmbedState, type PlayruoErrorMessage, type PlayruoEventMessage, type PlayruoEventPayload, type PlayruoInternalMessage, type PlayruoPasswordError, type PlayruoPasswordErrorCode, type PlayruoPasswordNotRequiredMessage, type PlayruoPasswordRequiredMessage, type PlayruoPasswordResultMessage, type PlayruoPurchaseRequestMessage, type PlayruoReadyMessage, type PlayruoRequestExitFullscreenMessage, type PlayruoSessionOverMessage, type PlayruoStateUpdateMessage, type PlayruoStreamStartMessage, type PlayruoStreamStopMessage, buildEmbedUrl, isPlayruoEmbedMessage, isPlayruoInternalMessage };
+declare const PLAYRUO_UUID_STORAGE_KEY = "playruo_uuid";
+/**
+ * Visitor identity the host answers on `playruo_uuid_request`.
+ * Same rule as PlayruoEmbed `clientFingerprint`: a non-empty value is used as-is
+ * and is not written to localStorage. Otherwise the SDK-managed UUID is used.
+ */
+declare const resolveVisitorUuid: (clientFingerprint?: string) => string;
+
+export { type DemoCompletedPayload, EmbedTester, type EmbedTesterProps, PLAYRUO_UUID_STORAGE_KEY, type PlayruoDemoCompletedMessage, PlayruoEmbed, type PlayruoEmbedActions, type PlayruoEmbedMessage, type PlayruoEmbedPasswordState, type PlayruoEmbedProps, type PlayruoEmbedRenderState, type PlayruoEmbedState, type PlayruoErrorMessage, type PlayruoEventMessage, type PlayruoEventPayload, type PlayruoInternalMessage, type PlayruoPasswordError, type PlayruoPasswordErrorCode, type PlayruoPasswordNotRequiredMessage, type PlayruoPasswordRequiredMessage, type PlayruoPasswordResultMessage, type PlayruoPurchaseRequestMessage, type PlayruoReadyMessage, type PlayruoRequestExitFullscreenMessage, type PlayruoSessionOverMessage, type PlayruoStateUpdateMessage, type PlayruoStreamStartMessage, type PlayruoStreamStopMessage, buildEmbedUrl, isPlayruoEmbedMessage, isPlayruoInternalMessage, resolveVisitorUuid };

package/dist/index.d.ts

@@ -180,6 +180,13 @@ interface PlayruoEmbedProps {
      */
     operationKey?: string;
     storeUrl?: string;
+    /**
+     * Stable visitor identity the host already owns (account id, CRM id, …).
+     * When set, answers `playruo_uuid_request` with this value and skips
+     * `localStorage["playruo_uuid"]`. Omit to keep the SDK-managed UUID.
+     * Playruo derives the session fingerprint from the answered `uuid`.
+     */
+    clientFingerprint?: string;
     showIframe?: boolean;
     className?: string;
     onReady?: () => void;
@@ -250,4 +257,12 @@ interface BuildUrlParams {
  */
 declare const buildEmbedUrl: ({ operation, operationKey, storeUrl, }: BuildUrlParams) => string;
 
-export { type DemoCompletedPayload, EmbedTester, type EmbedTesterProps, type PlayruoDemoCompletedMessage, PlayruoEmbed, type PlayruoEmbedActions, type PlayruoEmbedMessage, type PlayruoEmbedPasswordState, type PlayruoEmbedProps, type PlayruoEmbedRenderState, type PlayruoEmbedState, type PlayruoErrorMessage, type PlayruoEventMessage, type PlayruoEventPayload, type PlayruoInternalMessage, type PlayruoPasswordError, type PlayruoPasswordErrorCode, type PlayruoPasswordNotRequiredMessage, type PlayruoPasswordRequiredMessage, type PlayruoPasswordResultMessage, type PlayruoPurchaseRequestMessage, type PlayruoReadyMessage, type PlayruoRequestExitFullscreenMessage, type PlayruoSessionOverMessage, type PlayruoStateUpdateMessage, type PlayruoStreamStartMessage, type PlayruoStreamStopMessage, buildEmbedUrl, isPlayruoEmbedMessage, isPlayruoInternalMessage };
+declare const PLAYRUO_UUID_STORAGE_KEY = "playruo_uuid";
+/**
+ * Visitor identity the host answers on `playruo_uuid_request`.
+ * Same rule as PlayruoEmbed `clientFingerprint`: a non-empty value is used as-is
+ * and is not written to localStorage. Otherwise the SDK-managed UUID is used.
+ */
+declare const resolveVisitorUuid: (clientFingerprint?: string) => string;
+
+export { type DemoCompletedPayload, EmbedTester, type EmbedTesterProps, PLAYRUO_UUID_STORAGE_KEY, type PlayruoDemoCompletedMessage, PlayruoEmbed, type PlayruoEmbedActions, type PlayruoEmbedMessage, type PlayruoEmbedPasswordState, type PlayruoEmbedProps, type PlayruoEmbedRenderState, type PlayruoEmbedState, type PlayruoErrorMessage, type PlayruoEventMessage, type PlayruoEventPayload, type PlayruoInternalMessage, type PlayruoPasswordError, type PlayruoPasswordErrorCode, type PlayruoPasswordNotRequiredMessage, type PlayruoPasswordRequiredMessage, type PlayruoPasswordResultMessage, type PlayruoPurchaseRequestMessage, type PlayruoReadyMessage, type PlayruoRequestExitFullscreenMessage, type PlayruoSessionOverMessage, type PlayruoStateUpdateMessage, type PlayruoStreamStartMessage, type PlayruoStreamStopMessage, buildEmbedUrl, isPlayruoEmbedMessage, isPlayruoInternalMessage, resolveVisitorUuid };

package/dist/index.js

@@ -41,6 +41,31 @@ var buildEmbedUrlWithOrigin = (origin, { operation, operationKey, 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
 import { jsx, jsxs } from "react/jsx-runtime";
 var PlayruoEmbed = ({
@@ -48,6 +73,7 @@ var PlayruoEmbed = ({
   operation,
   operationKey,
   storeUrl,
+  clientFingerprint,
   showIframe = false,
   className,
   onReady,
@@ -533,16 +559,6 @@ var PlayruoEmbed = ({
     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("");
-  };
   useEffect(() => {
     const handleUUIDMessage = (event) => {
       const iframe = iframeRef.current;
@@ -555,16 +571,11 @@ var PlayruoEmbed = ({
       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
           );
@@ -574,7 +585,7 @@ var PlayruoEmbed = ({
     };
     window.addEventListener("message", handleUUIDMessage);
     return () => window.removeEventListener("message", handleUUIDMessage);
-  }, [embedOrigin, iframeRef]);
+  }, [clientFingerprint, embedOrigin, iframeRef]);
   useEffect(() => {
     const handleFullscreenChange = () => {
       const iframe = iframeRef.current;
@@ -799,12 +810,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");
@@ -2097,8 +2102,10 @@ var isPlayruoInternalMessage = (data) => {
 };
 export {
   EmbedTester,
+  PLAYRUO_UUID_STORAGE_KEY,
   PlayruoEmbed,
   buildEmbedUrl,
   isPlayruoEmbedMessage,
-  isPlayruoInternalMessage
+  isPlayruoInternalMessage,
+  resolveVisitorUuid
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playruo/embed",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "React SDK to embed Playruo with postMessage API.",
   "license": "MIT",
   "type": "module",
@@ -53,6 +53,8 @@
     "check:exports": "attw --pack .",
     "test": "npm run build && vitest run --coverage",
     "test:browser": "vitest run --config vitest.browser.config.ts",
-    "test:watch": "npm run build && vitest"
+    "test:watch": "npm run build && vitest",
+    "docs:notion:dry-run": "node scripts/sync-notion-docs.mjs",
+    "docs:notion:publish": "node scripts/sync-notion-docs.mjs --publish"
   }
 }