This assumes you already have completed (or understand) the game-level authentication part, independent of this website-level authentication. Read the documentation on game-level authentication with session tokens here.

📘
Summary of steps to integrate website-level user system with Pley.
To start the game on the web:

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.

Create the Web Playable using pley.createPlayable.

And also support:

Update the session's auth (pley.updateToken)

Provide a webhook POST /allocate-game-user to get a Pley Game User ID from the game backend by providing the Scope User ID (i.e. your user system user ID), or create a new Pley Game User if it's a guest who hasn't played on web before. (API Reference)

Terminology

Scope: One or more games using the same authentication system, such as YourStudioID.

Scope User: A user on your website ('scope')

Game User: A user in the backend of one of the games

Pley Access Token: A short-lived token certifying ownership of a certain Scope User

Pley Game User: Pley’s equivalent to your Game User for storing Pley-related features

Website setup

Issuing Pley Access Tokens

On your website, your account system is at the top level and determines which game progress is loaded when a user (Scope User) starts playing a game. To find the corresponding data on our side, Pley needs to stay in sync with which user is logged in. This is achieved by calling the Pley Issue Access Token endpoint using your Scope User ID and email (if available) which issues a Pley Access Token.

The player clicks "Start Game".
Call Pley's Issue Access Token endpoint and provide the ID and email of the user.
Receive Access Token in the response.

POST https://api.pley.com/v3/auth-kit/issue-access-token

// Authorization: Bearer API_TOKEN

// Body
{
	// Scope ID for game manager
	"scope_id": "xyz",
	// An ID of one of your scope users
	"scope_user_id": "xyz",
	// Email of the user
	"email": "[email protected]"
}

// Response
// 200
{
  "data": {
    // Pley Access Token
    "access_token": "xyz"
  }
}

Pley Web SDK

Pley provides the Pley Web SDK for your website to interface with Pley.

Adding it to your website

The Pley Web SDK script is hosted under https://www.pley.com/sdk/v1.js. You can include it wherever you like as long as it's loaded before you start using the Pley Web SDK. Some examples:

<!DOCTYPE html>
<!-- Included in header --!>
<head>
  <script src="https://www.pley.com/sdk/v1.js"></script>
</head>
<body>
  <!-- Or loaded asynchronously in body -->
  <script>
    var script = document.createElement("script");
    script.src = "https://www.pley.com/sdk/v1.js";
    script.async = true;
    script.onload = function() {
      const pley = new Pley.SDK({
        // ...
      });
      // ...
    };
    document.body.appendChild(script);
  </script>
</body>

When initializing the Pley Web SDK, pass the token as initialToken. If the user is currently not logged in, pass undefined. Because the Pley Access Token is short-lived, it needs to be continually re-issued. If a new token is needed, the onIssueToken callback will fire which you should use to do a call to your backend to fetch a new Pley Access Token.

Initialize the Pley Web SDK with the initial Access Token.
When callback onIssueToken fires, call your backend to fetch a new Pley Access Token using Issue Access Token.

// Example implementation
async function issueToken(): string {
	if (!isLoggedIn) {
		return undefined;
	}
	return fetch("https://your-back-end.tech/v5/issue-pley-access-token").json()["token"];
}

const pley = new Pley.SDK({
	scopeID: "ID_FROM_GAME_MANAGER",
	initialToken?: "xyz" | undefined,
	onIssueToken: issueToken,
})

Session updates

When the user decides to log in, change account, log out or the logged-in Scope User ID changes for any reason, the Pley Web SDK needs to be notified to take appropriate actions; such as close the game or payment sessions. When that happens, issue a new Pley Access Token or pass undefined to pley.updateToken() if the user is a guest.

// User session changed
pley.updateToken(token | undefined);

Create playable

Once the Web SDK is created successfully, you can create a Playable within your website. In order for the Web SDK to know for which game, you need to get the release track ID from your game manager.

pley.createPlayable("div-id", releaseTrackID);

Linking game accounts

❗️
Note
This section is only relevant if your players can link their accounts with your existing website-level user system. Examples of this are "Link with ScopeAccountSystem" buttons in the game.

By default, Pley maintains the relationship between website-level users and game progress. However if players in your game have the ability to connect to the website-level user system (Scope User system), the source of truth lies in your backend, not in Pley's. So Pley needs to be able to query the current state of that relationship for individual Scope Users.

This is where the Allocate Game User webhook comes in (https://docs.pley.com/reference/allocate-game-user). The webhook also takes care of a few other use cases:

Correctly pick existing Game Users based on the Scope User ID from other platforms so players can continue playing on web just by logging into the correct Scope User on the website level.
Make sure that before the game starts, the Game User is correctly connected to the Scope User.
Enable adoption of guest progress without the site-level user system having to support guest users.
Enable Pley to pick the correct Pley Game User for the game session.

The webhook implementation needs to follow this logic (in this order):

Return existing web progress: If there is already an existing Game User for this Scope User with a Pley Game User ID, return the Pley Game User ID. This is the most common case where a player is starting the game as a logged-in Scope User and has already made progress on the web.
Return existing non-web progress: If there already is an existing Game User for this Scope User, but has no Pley Game User ID assigned, assign new_pley_game_user_id to it and return new_pley_game_user_id. This is the case when a user has existing progress but has never played on the web before.
Adopt guest progress: If the player has been playing without logging in (as a guest), there might be an existing Pley Game User with some progress the player has done in their guest session. When this happens, the unlinked_pley_game_user_id field is set. Find the Game User where the Pley Game User ID is unlinked_pley_game_user_id. If you cannot find it, it could be that a game user has already been created on Pley's side in a guest session but the game never fully launched, so there is no user on your end. If the game user is missing, create a new Game User and assign unlinked_pley_game_user_id. Always adopt the progress by assigning scope_user_id to the Game User with unlinked_pley_game_user_id and return unlinked_pley_game_user_id.
Create new player: At this point, there is not any existing progress for this user. Create a new Game User and assign the scope_user_id and new_pley_game_user_id to it, linking it to the currently logged in Scope User. Return new_pley_game_user_id. This is for when the current user has never played the game before.

This is an example implementation in Python of the webhook:

# This function takes the response as a JSON object and returns the Pley Game User ID
def handle_allocate_game_user(req):
    existing_game_user = users.get_by_scope_user_id(req.scope_user_id)

    if existing_game_user is not None:
        if existing_game_user.pley_game_user_id is not None:
            # 1. Existing web progress
            return existing_game_user.pley_game_user_id

        users.set_pley_game_user_id(existing_game_user.id, req.new_pley_game_user_id)
        # 2. Existing non-web progress
        return req.new_pley_game_user_id

    if req.unlinked_pley_game_user_id is not None:
        game_user = users.get_by_pley_game_user_id(req.unlinked_pley_game_user_id)
        if game_user is None:
          game_user = users.create_new_game_user()
          users.set_pley_game_user_id(game_user.id, req.unlinked_pley_game_user_id)
        users.set_scope_user_id(game_user.id, req.scope_user_id)
        # 3. Adopt guest progress
        return req.unlinked_pley_game_user_id

    game_user = users.create_new_game_user()
    users.set_pley_game_user_id(game_user.id, req.new_pley_game_user_id)
    users.set_scope_user_id(game_user.id, req.scope_user_id)

    # 4. New player
    return req.new_pley_game_user_id

How to integrate the Web Playable with your website-level login

📘
Summary of steps to integrate website-level user system with Pley.

Terminology

Website setup

Issuing Pley Access Tokens

Pley Web SDK

Adding it to your website

Session updates

Create playable

Linking game accounts

❗️
Note

📘Summary of steps to integrate website-level user system with Pley.

Terminology

Website setup

Issuing Pley Access Tokens

Pley Web SDK

Adding it to your website

Session updates

Create playable

Linking game accounts

❗️Note

📘
Summary of steps to integrate website-level user system with Pley.

❗️
Note