How to add games to a Headless Destination with the Pley Web SDK

📘

About Headless Destination

The Pley Web SDK is used when implementing the Web Playable (the "box" which runs the game) onto a website you're building yourself. Pley calls this "Headless Destination".

Read more here

About 90% of games are better served using Pley Gamesite which comes out-of-the-box.

Overview

The Pley Web SDK allows you to embed and control the playable game in web applications and websites. It provides functionality for authentication, player controls, and event handling.

The Pley Web SDK allows your website or web application to interface with Pley. Its most critical feature is creating a Playable instance, which is the box where the game is played.

Setup

1. Add the SDK script to your website.

<script src="https://www.pley.com/playable/v1/web_sdk.js" async />

2. Initialize the Pley Web SDK

const webSdk = new window.Pley.Web({
  scopeId: string, // Unique identifier for the scope that you can get in manage.pley.com
  initialToken: string, // Initial authentication token
  onIssueToken: () => Promise<string>, // Callback to get new token
  onLoginRequested: (type: "login" | "signup") => Promise<void>, // Handle login/signup requests
});

3. Create a Playable instance. The Web Playable is the "box" where the game is played.

const playable = webSdk.createPlayable(
  "container-element-id", // DOM element ID where the game will be mounted
  "release-track-id", // Unique identifier for the game release that you can get in manage.pley.com
  {
    allowAllBrowsers: boolean,
  }
);

If the flag allowAllBrowers is set to false, the Playable will block mobile browsers from starting the game. Pley recommends leaving this as true as mobile is supported..

Features

Authentication

Call updateToken whenever the authentication state is updated (such as the user logging in or out).

// Update authentication token
await webSdk.updateToken(newAccessToken);

Read more about integrating your login system here.

Volume Control

Mute or unmute the game's audio.

// Toggle mute/unmute
webSdk.updateVolume(releaseTrackId, "mute" | "unmute");

Event Handling

Event handling is optional but can be set up to receive analytics events from the Web Playable to the website (which can send the event data wherever it wishes). Read more about analytics here.

playable.addEventHandler((event) => {
  // Handle events
  // event.type: string
  // event.data: any
  // event.channel: "internal" | "external"
});

Cleanup

// Dispose the SDK instance when done
webSdk.dispose();

Interfaces

Website-level Login

Launching your game through your custom-built website requires authentication. Without it, the user cannot save their progress and purchases.

This requires:

• Call Pley's API issue-access-token HTTP API to get an access token.
• Initialize the Pley Web SDK on the website, including the callback to issue new Access Tokens.
• If the user is not logged in, initialize the Pley Web SDK without an access token to start a guest session.
• Update the session's authentication status (pley.updateToken) if the user logs in or out.

Article: How to integrate your website-level login system with Pley.

Web Interface

interface Web {
  createPlayable: (
    element: string,
    releaseTrack: string,
    options: object
  ) => Playable;
  // Used for when user is logged in.
  updateToken: (token: string) => Promise<void>;
  updateVolume: (releaseTrackID: string, volume: "mute" | "unmute") => void;
  dispose: () => void;
}

Best Practices

1. Token Management

   • Always handle token updates properly (especially during logins/logouts)
   • Make sure to implement proper error handling for token operations, as token errors tend to be critical and prevent gameplay.

2. Event Handling

   • Set up event handlers early in the codebase.

3. Cleanup

   • Always dispose of the SDK when unmounting and clear any event listeners.

4. Error Handling

   • Make sure to implement proper error handling for all async operations
   • Handle initialization failures that may occur.

5. Guest Sessions

   • Enable guest sessions (users who play without logging in) by not providing an access token when the Pley Web SDK is initialized (Read more).

Example Web SDK Implementation

function GamePlayer() {
  const sdkRef = useRef<Web | null>(null);
  const { token, refreshToken } = useAuthStore(); // Your auth store

  useEffect(() => {
    // Initialize SDK
    sdkRef.current = new window.Pley.Web({
      scopeId: "your-scope-id",
      initialToken: token,
      onIssueToken: async () => {
        // Get new token from your auth system
        const newToken = await refreshToken();
        return newToken;
      },
      onLoginRequested: async (type) => {
        // Handle login/signup
      },
    });

    // Create playable
    const playable = sdkRef.current.createPlayable(
      "game-container",
      "your-release-track-id",
      {
        allowAllBrowsers: true,
      }
    );

    // Cleanup
    return () => {
      sdkRef.current?.dispose();
    };
  }, []);

  // Update SDK token when store token changes
  useEffect(() => {
    if (sdkRef.current && token) {
      sdkRef.current.updateToken(token);
    }
  }, [token]);

  return <div id="game-container" />;
}

📘

Headless Destination or Pley Gamesite

Don't want to implement the Pley Web SDK, build your own login, and maintain your own website?

About 90% of games are better served using Pley Gamesite which comes out-of-the-box.