Npm Setup Guide

This guide walks you through setting up the PlayerZero SDK using npm to start monitoring and improving your frontend applications.

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.

3. Identify the User (Recommended)

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: "[e-mail]",
  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.