UserId & UserName

Playgent supports a cross-platform identity flow so players can be recognized across devices and embeds. You can provide a hashed user ID and optional username to keep leaderboards and user-specific features consistent without sharing PII.

Overview

• The game iframe requests identity from its parent via a postMessage handshake.
• You respond with a hashed user_id and optional user_name.
• The game stores these values locally and uses them for scoring, leaderboards, and events.
• If no identity is provided, the game generates a random ID and continues to work.

Identity Handshake

When the game loads, it sends:

// Sent by the game to the parent window
{
  type: "PG_REQUEST_IDENTITY",
  publish_key: "<your-publish-key>"
}

Your page should listen for this message and reply with PG_IDENTITY:

window.addEventListener("message", (event) => {
  const data = event.data || {};
  if (data.type === "PG_REQUEST_IDENTITY") {
    // Provide a hashed/non-PII id and optional username
    event.source?.postMessage(
      {
        type: "PG_IDENTITY",
        publish_key: data.publish_key,
        user_id: "hashed_unique_user_id", // required for cross-platform consistency
        user_name: "Player123", // optional
      },
      "*"
    );
  }
});

After applying the identity, the game acknowledges with:

// Sent by the game to the parent
{
  type: "PG_IDENTITY_ACK",
  publish_key: "<your-publish-key>",
  user_id: "hashed_unique_user_id"
}

Local Storage Keys

The game stores identity locally:

• _pg_uid: the hashed user ID
• _pg_un: the optional username

If you do not provide a user_id, the game generates an anonymous ID and proceeds.

Event Names

• Event names are prefixed with PG_.
• The game may emit PG_GAME_VIEW immediately on load (before identity is set). Subsequent events use the provided or generated _pg_uid.

Privacy Considerations

• Do not send PII. Provide a hashed or anonymized user_id.
• Using your own user_id enables cross-platform consistency for leaderboards and scores. If omitted, a random ID is generated per user/device.

Example: Full Parent Integration

// 1) Listen for identity requests and respond with your hashed id
window.addEventListener("message", (event) => {
  const data = event.data || {};
  if (data.type === "PG_REQUEST_IDENTITY") {
    event.source?.postMessage(
      {
        type: "PG_IDENTITY",
        publish_key: data.publish_key,
        user_id: myHashedUserId, // required for consistent leaderboards
        user_name: myUserName, // optional
      },
      "*"
    );
  }
});

// 2) Optionally handle the identity acknowledgement
window.addEventListener("message", (event) => {
  const data = event.data || {};
  if (data.type === "PG_IDENTITY_ACK") {
    // Identity is set inside the iframe; you can update your UI or logs
  }
});

Benefits of Cross-Platform Support

• Consistent User Experience: The same user sees consistent scores and rankings across devices.
• Privacy by Design: You control the hashed user_id and never share PII.
• Better Analytics: Consistent identifiers improve engagement tracking.

Troubleshooting

• Not seeing your user_id applied? Verify that your parent page is replying to PG_REQUEST_IDENTITY with PG_IDENTITY and that the values are strings.
• Events arriving before identity? This is expected for initial PG_GAME_VIEW. Identity will be applied for subsequent events.