Sign in to a game
How to sign in a player to Vivox services.
Read time 2 minutesLast updated 7 months 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:
-
Alphanumerics0-9, A-Z, a-z0x30-0x39, 0x41-0x5A, 0x61-0x7AExclamation mark' ! '0x21Open parenthesis' ( '0x28Close parenthesis' ) '0x29Plus' + '0x2BMinus' - '0x2DPeriod' . '0x2EEquals' = '0x3DUnderscore' _ '0x5FTilde' ~ '0x7EPercent' % '0x7FNoteYou 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 message to sign users in to Vivox. After the game receives a successful message, the user is signed in.
vx_req_account_anonymous_loginvx_resp_account_anonymous_loginNote
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 and events.
vx_evt_buddy_presencevx_evt_participant_added- 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 field of the
displaynamerequest.vx_req_account_anonymous_login
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 message, the game must also handle events that have the state field set to . The Vivox SDK sends this message when the connection to Vivox is lost unexpectedly (such as from network connectivity issues).
vx_resp_account_anonymous_loginvx_evt_account_login_state_changelogin_state_logged_outThe 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 message, the game can sign in to Vivox. For more information, refer to Create the connector object.
vx_resp_connector_create