Sign in to a game

How to sign in a player to Vivox services.

Read time 2 minutes

Last updated a day ago

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.

Documentation

Development

User Acquisition

Monetization

Industry

Documentation

Development

User Acquisition

Monetization

Industry

Vivox Core SDK

Vivox Core SDK

Sign in to a game

Alphanumerics

0-9, A-Z, a-z

0x30-0x39, 0x41-0x5A, 0x61-0x7A