User Authentication

Log players in to coherence Cloud

The User API enables the creation and management of user accounts for players that uniquely identify them across multiple devices.

The API offers many ways to authenticate your players with coherence Cloud and enabling them to make use of its services:

• Auto Login As Guest

• Login As Guest

• Login With Password

• Login With Session Token

• Login With Steam

• Login With PlayStation

• Login With Xbox

• Login With Nintendo

• Login With JWT

• Login With Recovery Code

CoherenceBridge

CoherenceBridge's Inspector contains a coherence Cloud section that can be used to configure if and how the bridge should connect to coherence Cloud.

When a CoherenceBridge has been connected with a User, and the User has joined a lobby, the bridge will automatically join a play session started by the lobby's owner.

Auto Login As Guest

The quickest way to log a player in to coherence Cloud is to set User to Auto Login As Guest in a CoherenceBridge using the Inspector.

Auto Login As Guest

This will result in the player getting logged in to coherence Cloud as a guest automatically when the CoherenceBridge is loaded. The player will remain logged in until the CoherenceBridge is destroyed.

Guest ids are stored locally on the device, so it is important to know that uninstalling the game will also wipe out the data for the guest account, and players will no longer be able to access them even if they install the game again.

Main User

Setting User to Main User causes the CoherenceBridge to connect to coherence Cloud as the Main User.

When you log in to coherence Cloud using the User API, using any authentication method you want, it will result in a Main User being created. Once the user has successfully logged in, the CoherenceBridge will automatically connect to coherence Cloud as this user.

None

If User is set to None, then the CoherenceBridge will not connect to coherence Cloud automatically.

You can also connect a bridge with a User manually by assigning the User's Services to the the bridge's CloudService property:

using Coherence.Cloud;
using Coherence.Toolkit;
using UnityEngine;

public class ConnectBridgeWithUserExample : MonoBehaviour
{
    public CoherenceBridge bridge;

    async void Start()
    {
        User user = await User.LoginAsGuest();
        bridge.CloudService = user.Services;
    }
}

User

You can use the User API to log in to coherence Cloud manually.

Login As Guest

You can use User.LoginAsGuest to log in to coherence Cloud using a guest account that is automatically generated for you.

Guest ids are stored locally on the device, so it is important to know that uninstalling the game will also wipe out the data for the guest account, and players will no longer be able to access them even if they install the game again.

using Coherence.Cloud;
using UnityEngine;

public class LoginAsGuestExample : MonoBehaviour
{
    public User User { get; private set; }

    async void Start()
    {
        User = await User.LoginAsGuest();
        Debug.Log($"Logged in as: {User}.");
    }
}

Login With Password

You can use User.LoginWithPassword to log in to coherence Cloud using a username and password.

An autoSignup value of true can be passed to the method to automatically create a new coherence Cloud account with the provided username and password, if one does not exist already. The default value of autoSignup is false.

using Coherence.Cloud;
using UnityEngine;

public class LoginWithPasswordExample : MonoBehaviour
{
    [SerializeField] string username;
    [SerializeField] string password;
    [SerializeField] bool autoSignup;

    public User User { get; private set; }

    async void Start()
    {
        User = await User.LoginWithPassword(username, password, autoSignup);
        Debug.Log($"Logged in as: {User}.");
    }
}

Login With Session Token

You can use User.LoginWithSessionToken to log in to coherence Cloud using a session token acquired from a previously login operation.

This can be useful to avoid users from having to re-enter their username and password every time they want to log in.

Session tokens will expire after a certain period of time after the last login operation.

using Coherence.Cloud;
using UnityEngine;

public class LoginWithSessionTokenExample : MonoBehaviour
{
    [SerializeField] GameObject loginUi;

    async void Start()
    {
        var sessionToken = SessionToken.Deserialize(PlayerPrefs.GetString("SessionToken", ""));
        if(sessionToken == SessionToken.None)
        {
            Debug.Log("No session token found. Showing login UI...");
            Instantiate(loginUi);
            return;
        }

        var loginOperation = await User.LoginWithSessionToken(sessionToken);
        if (loginOperation.HasFailed)
        {
            Debug.LogWarning(loginOperation);
            Debug.Log("Logging in using session token failed. The session token may have expired. Showing login UI...");
            Instantiate(loginUi);
            return;
        }

        var user = loginOperation.Result;
        PlayerPrefs.SetString("SessionToken", SessionToken.Serialize(user.SessionToken));
        Debug.Log($"Logged in as: {user}.");
    }
}

Login With Steam

You can use User.LoginWithSteam to log in to coherence Cloud using a Steam account.

To do so, you have to provide at least an authentication ticket for the Steam User that you want to log in as. This can be acquired using SteamUser.GetAuthTicketForWebApi.

If you passed an identity string to the SteamUser.GetAuthTicketForWebApi method, you should also pass that same identity to the User.LoginWithSteam method.

using Coherence.Cloud;
using UnityEngine;

public class LoginWithSteamExample : MonoBehaviour
{
    public async Awaitable<User> Login(string ticket, string identity = null)
    {
        User user = await User.LoginWithSteam(ticket, identity);
        Debug.Log($"Logged in as: {user}.");
        return user;
    }
}

Login With Epic Games

You can use User.LoginWithEpicGames to log in to coherence Cloud using an Epic Games account.

using Coherence.Cloud;
using UnityEngine;

public class LoginWithEpicGamesExample : MonoBehaviour
{
    public async Awaitable<User> Login(string token)
    {
        User user = await User.LoginWithEpicGames(token);
        Debug.Log($"Logged in as: {user}.");
        return user;
    }
}

Login With PlayStation

You can use User.LoginWithPlayStation to log in to coherence Cloud using a PlayStation Network account.

using Coherence.Cloud;
using UnityEngine;

public class LoginWithPlayStationExample : MonoBehaviour
{
    public async Awaitable<User> Login(string token)
    {
        User user = await User.LoginWithPlayStation(token);
        Debug.Log($"Logged in as: {user}.");
        return user;
    }
}

Login With Xbox

You can use User.LoginWithXbox to log in to coherence Cloud using an Xbox account.

using Coherence.Cloud;
using UnityEngine;

public class LoginWithXboxExample : MonoBehaviour
{
    public async Awaitable<User> Login(string token)
    {
        User user = await User.LoginWithXbox(token);
        Debug.Log($"Logged in as: {user}.");
        return user;
    }
}

Login With Nintendo

You can use User.LoginWithNintendo to log in to coherence Cloud using a Nintendo Services account.

using Coherence.Cloud;
using UnityEngine;

public class LoginWithNintendoExample : MonoBehaviour
{
    public async Awaitable<User> Login(string token)
    {
        User user = await User.LoginWithNintendo(token);
        Debug.Log($"Logged in as: {user}.", this);
        return user;
    }
}

Login With JWT

You can use User.LoginWithJwt to log in to coherence Cloud using a custom JSON Web Token.

using Coherence.Cloud;
using UnityEngine;

public class LoginWithNintendoExample : MonoBehaviour
{
    async Awaitable<User> Login(string ticket)
    {
        User user = await User.LoginWithNintendo(ticket);
        Debug.Log($"Logged in as: {user}.", this);
        return user;
    }
}

Login With Recovery Code

You can use User.LoginWithRecoveryCode to log in to coherence Cloud using a recovery code acquired from another device using User.GetRecoveryCode.

using Coherence.Cloud;
using UnityEngine;

public class AcquireRecoveryCodeExample : MonoBehaviour
{
    async void Start()
    {
        User user = await User.LoginAsGuest();
        string recoveryCode = await user.GetRecoveryCode();
        Debug.Log($"Login with this code on your other device: {recoveryCode}.");
    }
}

public class LoginWithRecoveryCodeExample : MonoBehaviour
{
    public async Awaitable<User> LoginWithRecoveryCode(string recoveryCode)
    {
        var loginOperation = await User.LoginWithRecoveryCode(recoveryCode);
        if (loginOperation.HasFailed)
        {
            Debug.LogWarning($"Recovering user failed. The code may have already expired.\n{loginOperation}.");
            return null;
        }

        var user = loginOperation.Result;
        Debug.Log($"Recovered user: {user}.");
        return user;
    }
}

Linking

If you want to add multiple authentication methods to the same User Account, you can do so by first logging in using any of of the authentication methods, and then linking the rest of the authentication methods using the Link methods on the User class.

using Coherence.Cloud;
using UnityEngine;

public class LinkGuestExample : MonoBehaviour
{
    async void Start()
    {
        var mainUser = await User.GetMainUserAsync();

        // Acquire Guest Id from guest account associated with this machine.
        User guestUser = await User.LoginAsGuest();
        GuestId guestId = guestUser.GuestId.Value;
        guestUser.Logout();

        // Link the guest id to the main account:
        await mainUser.LinkGuest(guestId, force: true);
    }
}

The User class provides the following methods for linking authentication methods into an existing User Account:

• LinkGuest

• LinkSteam

• LinkPlayStation

• LinkXbox

• LinkNintendo

• LinkJwt

Unlinking

Each of the Link methods listed above also have a corresponding Unlink method in the User class that can be used to remove an authentication method from the User Account.

If an authentication method is already linked with one User Account, and you try to link it with another one, the operation will fail by default. If however you pass a force value of true to a Link method, then the authentication method will automatically be unlinked from any existing User Accounts it's associated with.

Warning: If an authentication method is unlinked from an User Account, and the User Account has no other authentication methods set up, then access to that User Account will be lost.

Account Information

Username and Password

You can change the username and (optionally) password of a User Account using SetUsername.

If no password is provided, then the option to login with password will not be available. This might still be useful if the username is used for game purposes only and not as an authentication method.

You can remove the username and password from from a User Account using RemoveUsername.

If the User Account has no other authentication methods set up besides the username and password, then RemoveUsername will fail by default. If however you pass a force value of true to the method, then the username and password will be removed regardless.

Warning: Access to a User Account will be lost if the last authentication method is removed from it.

Display Name and Image

You can change the display name and image of a Use Account using SetDisplayInformation.

You can remove the display name and image from a User Account using RemoveDisplayInformation.

Email

You can assign an email address to a Use Account using SetEmail.

You can remove an email address from a User Account using RemoveEmail.