@playruo/embed

React SDK to embed Playruo via iframe + postMessage.

Documentation

• Integrator overview and React/vanilla guides: docs/
• Protocol reference for webapp ↔ SDK changes: 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 demo. This remains the default behavior.

Set enableWindowedLaunch to true to skip the parent fullscreen request and start the experience inside the current iframe bounds:

<PlayruoEmbed
  operation="iframe"
  enableWindowedLaunch
/>

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=:

<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.

<PlayruoEmbed
  operation="crypticalpath"
  clientFingerprint={visitorId}
/>

A vanilla host answers the same way, with no React:

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:

<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 React package forwards the payload through onEvent(data).

If the package host is itself inside another iframe, the same message is also forwarded one level up with window.parent.postMessage({ type: "playruo_event", data }, "*").