Authentication for Destinations

This overview article is for launching games on web with Pley on your own website with your own login system on the website. Here you get an intuitive overview of how it should work. Read the article below for the implementation guide.

Article: Implementation 'How-to' of website-level authentication

Example: Pixel Federation's web gaming portal, with their own PixelID login system

Terminology

Term	Defintion
Scope	A authentication system, such as YourStudioID, used by one or multiple Pley web games.
Scope User	A user on your website (which we call 'scope'). They will have some identifier which Pley calls the Scope User ID.
Game User	A user in the backend of one of the games
Pley Access Token	A token certifying ownership of a certain Scope User (alive for 30 minutes)
Pley Game User	Pley’s equivalent to your Game User for storing Pley-related features
Guest Session	A session where the user is not logged in, which is created by not issuing an access token.
Adopting progress	When a guest user signs up or logs in to an account without progress for a game, that scope user should be assigned the Pley game user. The user will continue to play with their progress, but in a logged-in state.
Game Website	The Website which you run games and a login-system on.
Authentication System	Your login system (with both frontend and backend)
Pley WebSDK	The SDK initialized on the website.

Game-level & Website-level

Pley splits the authentication up into two:

Destinations and website-level (Article: Where you are)
Game-level (Article: Authentication for Game Developers)

This is done because it is core for Pley (and web gaming in general) for your game to run anywhere, no matter what login system is used on that website. By splitting these into two, your game can be launched on Discord, Crazy Games, or any other website through Pley (without you having to do anything else).

Additionally, it is very common for game developers to handle the game-server side, and web developers handling the website-level authentication. So splitting them up makes perfect sense.

Conceptual split between website-level and game-level

How Website-Authentication should work with Pley

Here is the full schema for all four parts: Authentication, Creating the Playable, Webhook, and updating the state. This can seem intimidating at first, but it isn't very complicated. It breaks down into four implementations:

Authenticate users using POST issue-access-token to authenticate users.
Create the game pre-authenticated with Pley by passing the access token.
A webhook which Pley can call which takes a website-level user ID, and returns which game user should be used.
If the authentication state changes (user logs in, signs up, or logs out), update the login state by calling pley.updateToken() with a new access token (or no token, if the user is logging out).

(1) User Authentication

User logs in on the website.
The authentication system calls pley POST issue-access-token with the ID for the user, their email, and (optional) if they are a guest user or not.
Recives a Pley Access Token, which is then used to initialize the Pley WebSDK.

📘
Guest Users
There are two ways
Recommended: To start the game as a guest user, simply initialize the Pley WebSDK without any initial (access) token. This should be done when the website login system is in a logged-out state. Pley will then handle all of guest sessions, no other action required.
Not Recommended, but viable: If your login system already supports guest sessions, Pley can let you handle it. In that case, pass is_guest = true in the issue-access-token call. Then pass the returned Pley access token when you initialize the Playable (game).

(2) Create Playable

The Playable is the box where the game is played. It should be created pre-authenticated through the access token. The Playable needs two things:

An access token if the user is returning so the game starts with the right game progress.
A release_track_id, which defines which game is being launched. This is found in the Game Manager.

Article: How-to initialize the Pley Web SDK

(3) Webhook

Article: How-to implement the allocate-game-user webhook

Finally, when the game starts, Pley will call the allocate-game-user webhook. This webhook connects the website-level authentication with the game-level (the user with the game progress).

Since the source of truth for website-level login and game user progress lies in your system and not in Pley, Pley needs to be able to request the current state (which website Scope User is connected to which Pley Game User, which has the game progress). This is where the Allocate Game User webhook comes in (https://docs.pley.com/reference/allocate-game-user). The webhook takes care of multiple cases:

Correctly pick existing Game Users based on the Scope User ID from other platforms, so players can continue playing on the web just by logging into the correct Scope User on the website level.
Ensure that the Game User is correctly connected to the Scope User before the game starts.
Enable the 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.

(4) Update Access Token

When the user decides to log in, change accounts, log out, or the logged-in Scope User ID changes for any reason, the access-token process should be repeated. When that happens, issue a new Pley Access Token or pass undefined to pley.updateToken() if the user is a guest.

This allows the Pley Web SDK to take appropriate actions, such as closing game or payment sessions.

📘
Ready to do the implementation?

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