​
Prerequisites

  • Node.js and npm or yarn installed.
  • Access to your project’s frontend codebase.
  • Your PlayerZero API Key.

​
Step-by-Step Instructions

​
1. Install the SDK

npm
npm i @goplayerzero/sdk-web --save
yarn
yarn add @goplayerzero/sdk-web

​
2. Initialize the SDK

Insert this early in your application’s entry point (e.g., index.js, main.ts, App.vue, etc.):

import PlayerZero from "@goplayerzero/sdk-web";
PlayerZero.init("your project id here");

Important: PlayerZero.init should only be called once. Use PlayerZero.isInitialized() to check if initialization has occurred.

Once the user is authenticated or known: The authentication logic of your application will want to invoke the following logic appropriately at the point your application has identified the user.

PlayerZero.identify("user-id", {
  name: "Jane Doe",
  email: "jane@example.com",
  group: "Engineering",
});

​
Example Implementations

​
Single Page Application (SPA) Setup

Once PlayerZero has been initialized, the below snippet demonstrates how to call the playerzero.identify method and capture user details in PlayerZero.

const userId = "userId";
const metadata = {
  name: "<DISPLAY_NAME>",
  email: "<USER_EMAIL>",
  group: "<CUSTOMER_ID_OR_OTHER_GROUP>", // Optional
};

if (window.playerzero) {
  window.playerzero.identify(userId, metadata);
} else {
  window.addEventListener(
    "playerzero_ready",
    () => { window.playerzero.identify(userId, metadata) },
    { once: true }
  );
}

​
Server Side Rendered (SSR) Setup

Once PlayerZero has been initialized, the below snippet demonstrates how to call the playerzero.identify method and capture user details in PlayerZero.

const userId = "<USER_ID>";
const metadata = {
  name: "<USER_NAME>",
  email: "<USER_EMAIL>",
  group: "<GROUP>", // optional
};

const setCookie = (traceId) => {
  document.cookie = `pz-traceid=${traceId}; Path=/;`;
};

if (window.playerzero) {
  // PlayerZero has loaded
  window.playerzero.identify(userId, metadata);
  window.playerzero.onTraceChange(setCookie);
} else {
  // Wait for PlayerZero to load
  window.addEventListener(
    "playerzero_ready",
    () => {
      window.playerzero.identify(userId, metadata);
      window.playerzero.onTraceChange(setCookie);
    },
    { once: true }
  );
}

​
Next Steps

Once the SDK is installed and initialized, you can visit the Users page in PlayerZero to see live user sessions being captured.

If you want to control where PlayerZero is active, visit the Domain Settings guide to configure domain-level access and environment-specific behavior.

Want to extend your integration further? Explore the Advanced SDK Usage guide to unlock features like custom event tracking, devtools links, and user metadata enhancements.