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 name that is selected by the game. For the account name:

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

Note: It’s recommended that you re-use player account names to facilitate the use of Vivox features such as cross-mute and blocking. It will also become a requirement for using future safety features designed for reducing toxicity and fostering more positive communities.

The following criteria applies to account names:

Maximum of 127 bytes
Must start and end with a period (.)
No adjacent spaces
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

Note: You can only use the percent sign for URL encoding. Follow the percent sign by two uppercase hex characters.

Note: The account name and channel names must include a reference to the token issuer.

The game uses the vx_req_account_anonymous_login message to sign users in to Vivox. After the game receives a successful vx_resp_account_anonymous_login message, the user is signed in.

Note: Every sign in request must have an access token that authorizes that game instance to sign in as the specified account.

For more information, refer to the Access Token Developer Guide.

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 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 the displayname field in the vx_evt_buddy_presence and vx_evt_participant_added events.

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, plus a null terminator.
The display name is set in the displayname field of the vx_req_account_anonymous_login request.

Note: The Vivox SDK does not perform checks on the display name. It is the game developer's responsibility to ensure that the display name follows the rules of the game, that the font characters are supported by the in-game renderer, and that the name is checked for duplication, obscenity, and impersonation. We recommend that you check display names by using some out-of-band means (such as the game server), and not by using the game client.

The following code is an example of how to initiate the sign in process:

. . .
vx_req_account_anonymous_login_t *req;
vx_req_account_anonymous_login_create(&req);
req->connector_handle = vx_strdup("c1");
req->acct_name = vx_strdup(".issuer-w-dev.mytestaccountname.");
req->displayname = vx_strdup("John Doe");
req->account_handle = vx_strdup(req->acct_name);
req->access_token = vx_strdup(_the_access_token_generated_by_the_game_server);
vx_issue_request3(&req->base, &request_count);
. . .

The following code is an example of how to handle the sign in response:

void HandleLoginResponse(vx_resp_account_anonymous_login *resp)
{
    if (resp->base.return_code == 1)
    {
        printf(U, resp->base.status_code, vx_get_error_string(resp->base.status_code));
        return;
    }
    vx_req_account_anonymous_login *req = reinterpret_cast<vx_req_account_anonymous_login *>(req->base.request);
    printf("login succeeded for account %s\n", req->acct_name);
}

In addition to handling the vx_resp_account_anonymous_login message, the game must also handle vx_evt_account_login_state_change events that have the state field set to login_state_logged_out. The Vivox SDK sends this message when the connection to Vivox is lost unexpectedly (such as from network connectivity issues).

The following code is an example of the connection state change messaging process:

void HandleLoginStateChange(vx_evt_account_login_state_change *evt)
{
    if (evt->state == login_state_logged_in)
    {
        printf("%s is logged in\n", evt->account_handle);
    }
    else if (evt->state == login_state_logged_out)
    {
        if (evt->status_code !=0)
        {
            printf("%s logged out with status %d:%s\n", evt->status_code, vx_get_error_string(evt->status_code));
        }
        else
        {
            printf("%s is logged out\n", evt->acct_name);
        }
    }
}

After the game receives the vx_resp_connector_create message, the game can sign in to Vivox. For more information, refer to Create the connector object.

Sign in to a game#

Sign in to a game