Documentation

Support

Vivox Unity SDK

Vivox Unity SDK

Sign in with Custom IDs

Sign in users to Vivox with custom identifiers.
Read time 2 minutesLast updated 2 days ago
If you already have an existing player management system that creates player IDs, you can use the Custom ID provider to link the identities. Prerequisites:
  1. Set up a Unity Cloud project
    • Make sure you have your project ID, environment ID, and environment name.
  2. Enable the UAS custom ID provider Make sure you have your Service Account credentials handy from this setup
The overall flow of this setup:
A flow diagram with arrows that illustrate the sign in flow with custom IDs.
 Sign in flow
  1. The game client sends the sign in request to the game back end
  2. The game back end either signs in the player using your custom logic or registers the player with a custom ID provider sent to UAS.
  3. UAS returns an access token to the game back end.
  4. The game back end then returns the access token to the game client.
  5. The game client then initializes the authentication service and the Vivox service to finish signing in the player.
Sign in steps
  1. Register all users with the UAS custom ID provider on sign-in and retrieve 
    accessToken
    and 
    sessionTokens
    for players.
  2. Set up the AuthenticationService in the client using the 
    accessToken
    and 
    sessionToken

Client-side setup

Together with the server side sign in set up, an access token has to be retrieved from your back end and processed with the 
AuthenticationService
: 
ProcessAuthenticationTokens
is used to process Unity Authentication Service Access Tokens and make them available to other UGS SDKs integrated into the game that require the player to be authenticated. Since the access tokens expire you must manually refresh the access token and call 
ProcessAuthenticationTokens
with the new access token. You can call 
ProcessAuthenticationTokens
with both the access token and the session token. The Unity Authentication SDK refreshes the access token before it expires, keeps the player's session active, and enables sign in a cached player. 
using Unity.Services.Authentication;using Unity.Services.Vivox;void SignUserWithCustomTokenWithAutoRefresh(){    try    {        // Check if a cached player already exists by checking if the session token exists        if (AuthenticationService.Instance.SessionTokenExists)        {            // This call will sign in the cached player.            await AuthenticationService.Instance.SignInAnonymouslyAsync();            Debug.Log("Cached user sign in succeeded!");        }        else        {            var userTokens = // Fetch the user tokens using your method calls            AuthenticationService.Instance.ProcessAuthenticationTokens(userTokens.AccessToken, userTokens.SessionToken)        }        // Shows how to get the playerID        Debug.Log($"PlayerID: {AuthenticationService.Instance.PlayerId}");        await VivoxService.Instance.InitializeAsync();    }    catch (AuthenticationException ex)    {        // Compare error code to AuthenticationErrorCodes        // Notify the player with the proper error message        Debug.LogException(ex);    }    catch (RequestFailedException ex)    {        // Compare error code to CommonErrorCodes        // Notify the player with the proper error message        Debug.LogException(ex);    }    catch (Exception ex) {        // Handle exceptions from your method call        Debug.LogException(ex);    }}
Note that the sample code is a method only, not a class. The access token needs to be retrieved from your backend. Refer to the Server-side setup below for more information on that.

Server-side setup

During player sign-in, ensure that each player is registered with the UAS custom ID provider and retrieve a 
accessToken
and 
sessionToken
for the player. If you haven't done it yet, refer to Enable the UAS custom ID provider to set it up. Using the Service Account credentials you can send a request to register a player on your game server:
  1. Call the Token Exchange API to retrieve a stateless token.
  2. Call the Sign In With Custom ID API:
curl --location 'https://player-auth.services.api.unity.com/v1/projects/<PROJECT_ID>/authentication/server/custom-id' \--header 'Content-Type: application/json' \--header 'UnityEnvironment: <ENVIRONMENT_NAME>' \--header 'Authorization: Bearer <STATELESS_TOKEN' \--data '{    "externalId": "YOUR_CUSTOM_PLAYER_ID"}'
The response of this request will contain an 
idToken
and a 
sessionToken
that you have to return to the client for initializing the 
AuthenticationService
. The 
idToken
can be used as the 
accessToken
in this context. Optionally, you can use the Player Names API to set a name for the players. This is useful if you are using the Vivox Safety products as it will allow the player names to be displayed to moderators in the Moderation dashboard. Make sure you keep the player name up to date if players change it. You can also directly manage player names from the client side using Player Name Management.