Pley Connect Overview

Pley Connect has two ways of initiating account linking between mobile and web.

• Input code from mobile game
  The player presses a notification or button in the mobile game which displays a code. They go to the prompted website and input the code. The game starts instantly with linked accounts.
• QR code from the web
  The player gets sent to a website with a QR code. They scan the QR code with their phone. The game starts instantly with linked accounts.

Implementation

To use Pley Connect you need to implement (6) parts:

1) [Web game] ConnectionKit Account linking during the initial loading screen of your web game (Here).

2) [Mobile game] Deep linking into Pley Connect (Here).

3) [Mobile game] Pley Connect modal in the mobile game, which displays the account link code (Here).

4) [Game backend] Account Linking code generation, verification, & setting status (Here).

5) [Game backend] Linking Pley users-ids to game users in the game backend (Here).

6) [Configuring Pley] Enable Pley Connect in the Game Manager with the right config (Here).

ConnectionKit Account Linking During Game Load

Web Game. Before or the first thing in the loading screen for the web version of your game.

1) Wait for Pley.SDK.OnInitialized to be invoked.

2) If Pley.ConnectionKit.GetAccountLinkCode() returns a non-empty string, pauses loading and send the link code to the game backend to verify it.

3) The game backend verifies the link code with Pley's backend, connection-kit/verify-link-code.
This endpoint returns the Pley game user id and the payload that was provided to connection-kit/get-link-code.

4) When the game client gets a response from the game backend it should invoke Pley.ConnectionKit.SetAccountLinkResult with either Ok or Failed. The backend should also set the linking status to true if successful (read more).

5) Otherwise, continue with the game loading screen.

// Wait for this callback to be invoked before starting the first loading screen
SDK.OnInitialized += result =>
{
    if (result.IsError())
    {
        Debug.LogError($"Failed to initialize Pley: {result.ToString()}");
        return;
    }

    var linkCodeResult = ConnectionKit.GetAccountLinkCode(out var linkCode);
    if (linkCodeResult.IsError())
    {
        Debug.LogError($"Failed to get account link code: {linkCodeResult.ToString()}");
    }

    if (string.IsNullOrEmpty(linkCode) || backendManager.HasSentLinkVerification)
    {
        // Continue with the loading screen
        return;
    }
  
  
//Call the game backend to verify the Account Link Code.
//If verification is successful, attach the Play User ID to the game user in the backend.
//Finally, return a response to the game which then calls ConnectionKit's result methods.
    backendManager.PleyConnectVerifyLinkCode(linkCode, error =>
    {
        if (!string.IsNullOrEmpty(error))
        {
            ConnectionKit.SetAccountLinkResult(PleyAccountLinkResult.Failed, _ => {});
            Debug.LogError($"Failed to verify Pley link code: {error}");
            return;
        }
        ConnectionKit.SetAccountLinkResult(PleyAccountLinkResult.Ok, _ => {});
        // Continue the loading screen
    });
};

📘

Best practice | Before Authentication

ConnectionKit account liking is intended to occur before any backend authentication. It is best implemented before any authentication with the game backend is done.

If this is not possible, reach out to us for our alternative solution. In such a case, the game must refresh it's own IFrame to restart the game (authenticating as the newly account linked user).

Deep Linking into Pley Connect

Mobile Game. Example C# code to handle the deep linking that Pley Connect requires. This should be implemented into the mobile version of your game.

public static class PleyDeepLinkManager
{
    public static event Action<string> OnPleyConnectDeepLink;

    [RuntimeInitializeOnLoadMethod]
    public static void Init()
    {
#if (UNITY_ANDROID || UNITY_IOS) && !UNITY_EDITOR
        Application.deepLinkActivated += OnDeepLinkActivated;
        if (!string.IsNullOrEmpty(Application.absoluteURL))
        {
            OnDeepLinkActivated(Application.absoluteURL);
        }
#endif
    }

    private static void OnDeepLinkActivated(string url)
    {
        if (string.IsNullOrEmpty(url))
        {
            return;
        }

        var uri = new Uri(url);
        var host = uri.Host;
        if (host != "pley_account_link")
        {
            return;
        }

        var query = HttpUtility.ParseQueryString(uri.Query);
        var linkCodeId = query.Get("link_code_id");
        OnPleyConnectDeepLink?.Invoke(linkCodeId);
    }
}

In this example, if the game is opened with a deep link i.e. gamescheme://pley_account_link then PleyDeepLinkManager.OnPleyConnectDeepLink will be invoked.

The callback will have a string linkCodeId

If the linkCodeId is empty or null then the game should display the Pley Connect UI within the game and show the link code. Read more about requesting a link code from Pley here.

If the linkCodeId has a value, do not show the Pley Connect UI. Instead, send the ID to the game backend which in turn should send it to Pley using the HTTP API connection-kit/get-link-code. Read more about the backend implementation here.

Example of the payload for connection-kit/get-link-code:

{
    "link_code_id": "The linkCodeId from the deep link URL",
    "game_id": "Game id that can be found in the Pley Game Manager",
    "payload": "user id from the game itself"
}

📘

Account Linking Successful - and close the game!

Depending on the game backend response show an account link success prompt and close the game. The web-version of the game will automatically start on the player's desktop screen. If the game starts like normally, it'll likely confuse the user.

In-game UI for Pley Connect

Mobile Game. Within the game's mobile version, the player should be able to find the Pley Connect input code. The view should provide the player with:

• The Pley Connect Input code, generated whenever the view is opened by the game backend through the JSON APIs here.
• The prompt to play the game on the web on a desktop/laptop device.
• The instruction to enter the code on Pley.com/connect.

If the window in-game is closed and re-opened, the game should request a new code from the backend. This Ui should be built in the game using the game's visual asset style.

Code Generation, Verification, & Setting Status

Game Backend. During account linking, the game backend should communicate with Pley to generate link codes, verify link codes, and if account linking is successfully executed, set the account link status to true. These three steps should occur in the backend of the game, communicating with Pley through cURL.

Generating Account Link Code

Whenever the Pley Connect UI is opened in the mobile game or a QR-code deep link occurs, the backend should request Pley to generate a link code. For the QR code path, include the link-code-id provided by the QR code. For the input code path, the game should simply call the game backend, which in turn generates a link code through the Pley HTTP API connection-kit/get-link-code.

curl \
--location 'https://json.api.pley.com/v2/connection-kit/get-link-code' \
--header 'Authorization: Bearer your-org-api-token-here' \
--data '{
    "game_id": "game-id",
    "link_code_id": "link-code-id", // only used with the QR code.
    "payload": "any-payload" // optional payload. Often the game user ID.
}'

Response when generating link code:

{
    "code": "ABC123", 
    "expiry": 1686316953000 // unix timestamp in ms
}

📘

QR-Code Path & Input-Code Path

Pley Connect lets the user use two different ways to link accounts. In the HTTP API, the link_code_id is only used for the QR-code path. No link_code_id is used for the Game UI Input Code account linking.

Verifying Account Link Code

Whenever the game starts on the web with an account link code, the game backend should verify the code before executing the linking of users. This should happen whenever the web game loads with a link code parameter (here).

curl \
--location 'https://json.api.pley.com/v2/connection-kit/verify-link-code' \
--header 'Authorization: Bearer your-org-api-token-here' \
--data '{
    "play_token": "play-token from pley-sdk",
    "code": "ABC123"
}'

Response when verifying link code:

{
    "game_user_id": "xxxxx-xxxx-xxxx-xxxxxxxxxx", // id of the pley user
    "is_guest_user": true,
    "payload": "your-payload" // payload when code was generated
}

After successfully getting the game_user_id back from Pley, the game backend should link that game_user_id to the current user. (Read more)

Set Account Link Status after Successful Account Linking

After account linking is successfully executed (generation, verification, and the backend/database account linking), inform Pley by setting the account link status to true. This step is important as Pley changes the interface for users with linked accounts to improve their experience.

curl \
--location 'https://json.api.pley.com/v2/connection-kit/set-accountlink-status' \
--header 'Authorization: Bearer your-org-api-token-here' \
--data '{
    "play_token": "play-token from pley-sdk",
    "linked": true
}'

Response code 200 indicates success.

Game Backend Account Linking

Game Backend. Linking accounts and user progress in the game backend will always be unique for each game. The intended use is for the game to link the Pley users to the mobile game users as a pointer or as a social login. If a Pley user starts the game, the backend checks if their Pley Game User ID is linked to a mobile game user. If so, launch the game with that progress data.

Database Concept / Example

If Pley Game User xxxxx-xxxx-xxxx-xxxxxxxxxx connects to the game, they'll be authenticated as User2193113. The game then starts with the progress of User2193113 (in this example called currentProgress2193113.sav).

Enabling Pley Connect on Pley

Pley Game Manager. In the Pley Game Manger, under 'Project Settings', you'll find Pley Connect.
Add in the information and check to enable Pley Connect. If configured correctly, it will begin to work instantly.

Find the Game Manager here.