User identity

Pass your logged-in user id/name into Playgent via postMessage so leaderboards and events are tied to your users.

When you embed Playgent on your site, you can optionally pass your own user identity into the game iframe.

Why do this?: so leaderboard entries, analytics, and event payloads can be associated with the same user across sessions/devices (without using PII).
What you send:
- user_id (recommended): a stable, anonymized/hashed identifier from your system
- user_name (optional): display name for your UI / event payloads (some leaderboard systems may still use an internally-generated name)

How it works (what you need to do)

1) Embed the player as usual

Follow the Player integration guide (player/sdk) to create the embed.

2) Listen for the identity request

After the iframe loads, it will ask the parent page for identity:

type: "PG_REQUEST_IDENTITY"

3) Reply with your identity

Reply back to the iframe with:

type: "PG_IDENTITY"
user_id and optionally user_name

Here’s a copy/paste example that works with player.js embeds:

// 1) Create the embed
const player = Playgent.init({
  containerId: "playgent-player",
  contentId: "your-content-id",
});

// 2) Derive the trusted origin from the iframe URL
const playgentOrigin = new URL(player.iframe.src).origin;

// 3) Respond to the handshake
window.addEventListener("message", (event) => {
  if (event.origin !== playgentOrigin) return;
  if (event.source !== player.iframe.contentWindow) return;

  const data = event.data || {};
  if (data.type !== "PG_REQUEST_IDENTITY") return;

  // Use a stable, non-PII identifier (recommended: hashed/anonymized)
  const userId = window.myApp?.currentUser?.hashedId;
  const userName = window.myApp?.currentUser?.displayName;

  event.source?.postMessage(
    {
      type: "PG_IDENTITY",
      publish_key: data.publish_key, // echo back (optional but recommended)
      user_id: String(userId || ""),
      user_name: String(userName || ""),
    },
    playgentOrigin,
  );
});

4) (Optional) Confirm it was received

The iframe may reply with:

type: "PG_IDENTITY_ACK"

window.addEventListener("message", (event) => {
  const data = event.data || {};
  if (data.type === "PG_IDENTITY_ACK") {
    // Identity was accepted inside the iframe
    // data.user_id contains the id that was applied
  }
});

Updating identity after login/logout

If the user logs in after the player has already loaded, you can send PG_IDENTITY again (same payload) to update the iframe. This is useful for “continue as guest → log in” flows.

Best practices

Do not send PII: don’t send email, phone, or raw database IDs if they’re sensitive. Use an anonymized/hashed user_id.
Always verify origin: use new URL(player.iframe.src).origin and check event.origin and event.source to avoid accepting messages from other iframes.
Multiple players on one page: create one listener that routes by event.source (iframe window) to the correct player instance.

Getting the score on completion

Yes — the completion event name is PG_GAME_COMPLETED and it includes a score field.

window.addEventListener("message", (event) => {
  const data = event.data || {};
  if (data.type !== "PG_GAME_COMPLETED") return;

  // Example fields you can use
  const score = data.score; // number | null
  const durationSeconds = data.duration_seconds; // number
  const userId = data.user_id; // string
  const userName = data.user_name; // string
});

User identity

On this page