Sign in to a game#

After you initialize the Vivox SDK, you can sign a user in to the Vivox instance assigned to your game by using an Account object. An Account is generated with a Vivox access token issuer, a username that is selected by the game, and the host for your Vivox domain.

• Create a one-to-one mapping between an Account and a player.
• Use the same Account for the same player every time they play the game.
• Player account names must be unique for each play and be anonymous.

If you do not want to use a unique account name per player, or if you do not want to expose the username to the network, then use one of the following options:

• A hash of the unique username
• A universally unique identifier (UUID)

The following criteria apply to account names:

• The total length of the issuer + username cannot exceed 124 characters
• Can use only the following characters:

• Alphanumerics	0-9, A-Z, a-z	0x30-0x39, 0x41-0x5A, 0x61-0x7A
  Exclamation mark	' ! '	0x21
  Open parenthesis	' ( '	0x28
  Close parenthesis	' ) '	0x29
  Plus	' + '	0x2B
  Minus	' - '	0x2D
  Period	' . '	0x2E
  Equals	' = '	0x3D
  Underscore	' _ '	0x5F
  Tilde	' ~ '	0x7E
  Percent	' % '	0x7F

Each participant must have a unique username portion of the Account, or collisions can occur during gameplay. If a duplicate Account is used in a channel where that Account already exists, then the Account already in the channel is kicked from the channel.

After the Account is created, call the ILoginSession.BeginLogin method to sign in to Vivox.

• The last argument of ILoginSession.BeginLogin is the AsyncCallback that is called after the sign in is complete.
• Every BeginLogin method call must have an access token that authorizes that game instance to sign in as the specified account.
• The EndLogin method must be called within a try block in case an error occurs.

The game sets a display name for the account by using UTF-8 encoding. This name is visible to all users in the channel; they receive it as DisplayName within the Account section of the Participant results from IChannelSession.Participants.AfterKeyAdded, IChannelSession.Participants.BeforeKeyRemoved, and IChannelSession.Participants.AfterValueUpdated.

• The display name is only valid for the current session and does not persist in the Vivox network.
• The maximum display name length is 127 bytes.
• The display name is set in the displayname field of the Account constructor.

The following code displays an example of how to initiate the sign in process and the resulting callback. using System; is required for Unity exceptions, and using System.ComponentModel; is required for IChannelSession.PropertyChange calls to work.

This code uses the GetLoginToken method for generating access tokens.For more information, refer to the Access Token Developer Guide.

To enable development and prototyping token generation, manually add or automatically pull your Vivox Token key into your project.

1. Open your Unity project.

2. Select Edit > Project Settings. Select the Vivox tab, and then perform either of the following actions:

   • Manually enter the Vivox credentials.

     These are found on the Unity Cloud Dashboard, in the Vivox section, on your project’s Credentials page.

   • For a project that is already associated with the Unity Cloud Dashboard, update Environment to Automatic.

     This automatically pulls Vivox credentials into your project.

You can then generate a development login token by using LoginSession.GetLoginToken().

using UnityEngine;
using VivoxUnity;
using Unity.Services.Vivox;

class LogInExample : MonoBehaviour
{
    . . .
    void LoginUser()
    {
        // For this example, client is initialized.
        var account = new Account("username-0001");
        var _loginSession = client.GetLoginSession(account);
        _loginSession.BeginLogin(_serverUri, _loginSession.GetLoginToken(_tokenKey,_tokenExpiration), ar =>
        {
            try
            {
                _loginSession.EndLogin(ar);
            }
            catch (Exception e)
            {
                // Handle error
                return;
            }
            // At this point, login is successful and other operations can be performed.
            . . .
            });
        }
    }
    . . .
}

You can subscribe to various ILoginSession events by using a standard C# EventHandler delegate style. The most important of these is ILoginSession.PropertyChanged, which occurs when the session changes its connection state. The game must handle events that have the state value set to LoginState.LoggedOut. The Vivox SDK sends this message when the connection to Vivox is lost unexpectedly (such as from network connectivity issues) or when a user manually initiates a sign-out.

The following code displays an example of how to subscribe to the ILoginSession.PropertyChanged event, and how to handle the functions for the different LoginState values:

using UnityEngine;
using VivoxUnity;
using Unity.Services.Vivox;
            
class LoginPropChangeExample : MonoBehaviour
{
    . . .
    _loginSession.PropertyChanged += onLoginSessionPropertyChanged;
    . . .
    
    private void onLoginSessionPropertyChanged(object sender, PropertyChangedEventArgs propertyChangedEventArgs)
    {
        if ("State" == propertyChangedEventArgs.PropertyName)
        {
            switch ((sender as ILoginSession).State)
            {
                case LoginState.LoggingIn:
                    // Operations as needed 
                break;
                
                case LoginState.LoggedIn:
                    // Operations as needed 
                break;    
    
                case LoginState.LoggedOut:
                    // Operations as needed 
                break;
                default:
                break;
            }    
        }
    }
}