Initializing Vivox

How to initialize Vivox.

Read time 3 minutes

Last updated 7 months ago

Use this guide to initialize Vivox and test your integration. The game client must initialize with the Vivox SDK before interacting with it.

1. Set up your message handler

Goal: Create a function to process Vivox messages as they appear.

Set up Vivox to handle responses and events via a common callback. Set this callback function via the

pf_sdk_message_callback

member of the

vx_sdk_config_t

parameter passed into

vx_initialize3()

. The void *callback_handle, which is also registered with

vx_sdk_config_t

, will call the bound method. This can be a pointer to a singleton class that tracks the Vivox state.

When the callback occurs, call

vx_get_message()

(non-blocking) until no more messages are processed. It is unnecessary to handle messages on the thread that generated the notification callback, but you can if you want to.

The example below is an implementation of this process:


void OnResponseOrEventFromSdk() {    int status;    vx_message_base_t *msg;    for (;;) {        status = vx_get_message(&msg);        if (status == VX_GET_MESSAGE_AVAILABLE) {            if (msg->type == msg_event) {                DispatchEvent(reinterpret_cast<vx_evt_base_t *>(msg));            }            else {                DispatchResponse(reinterpret_cast<vx_resp_base_t *>(msg));            }            vx_destroy_message(msg);        }        else if (status == VX_GET_MESSAGE_FAILURE) {        // Handle error here. Occurs if vx_initialize3() has yet to be called.        }        else { /* VX_GET_MESSAGE_NO_MESSAGE */            break;        }    }}

For more details, refer to Message callback.

2. Call initialize

Goal: Initialize the Vivox SDK.

Initialize the Vivox SDK by creating a config variable and passing it to

vx_initialize3()

. Both of these calls will return a response code defined in

VxcErrors.h

. A successful response returns

VxErrorSuccess


#include"Vxc.h"#include"VxcErrors.h"vx_sdk_config_t defaultConfig;int status = vx_get_default_config3(&defaultConfig, size of (defaultConfig));if (status != VxErrorSuccess) {    printf("vx_sdk_get_default_config3() returned %d: %s\n", status,    vx_get_error_string(status));    return;}config.pf_sdk_message_callback = &sOnResponseOrEventFromSdk;status = vx_initialize3(&defaultConfig, size of (defaultConfig));if (status != VxErrorSuccess) {    printf("vx_initialize3() returned %d : %s\n", status, vx_get_error_string(status));    return;}// Vivox Client SDK is now initialized

For more details, refer to Initialize the Vivox SDK.

3. Create a connector handle

Goal: Fetch the pre-login server-side configuration file.

Create a request object of type

vx_req_connector_create

, set a

connector_handle

value of your choosing and wait for the

vx_resp_connector_create

response before logging in to the Vivox network.

This request fetches important pre-login information from your assigned Vivox server. This information is required before logging into the Vivox network. If you have one or more dedicated servers, the

acct_mgmt_server

value might vary by title and region.

Note

It is best practice for the game client to craft the

connector_handle

and store it for use in subsequent requests.


vx_req_connector_create *req;vx_req_connector_create_create(&req);req->connector_handle = vx_strdup("c1");req->acct_mgmt_server = vx_strdup("https://mt1s.www.vivox.com/api2/");int request_count;int vx_issue_request3_response = vx_issue_request3(&req->base, &request_count);

For more information, refer to Create the connector object.

Verify your implementation

Follow these steps to verify your implementation:

Launch your client application. Navigate past the point where the Vivox SDK should be initialized.
Set a breakpoint on the SDK message callback or observe a client log file.
Add or remove an audio headset multiple times.
Observe that the message callback fires and
```
vx_get_message()
```
retrieves events.
Navigate past the point where the
```
connector_create
```
request is submitted.
Verify that the message callback picks up a
```
vx_resp_connector_create
```
response.
Rerun the
```
connector_create
```
test with no internet connection, and verify that error handling and logging work as expected.

When your game client receives an event from the Vivox SDK, your first step is to evaluate if it was successful. For the initialization process, check for success with the

connector_create

call. If successful, the

status_code

field will be 0. If it is not zero, your game client should follow the below steps to initiate a retry.

If connector create is unsuccessful

Print an error to debug log or the client event capture location.
Attempt to retry
```
vx_req_connector_create
```
initialization.
Delay for 10 seconds between retries.
After 5 failed retries, inform the user that voice chat services are not available.
Retry on the next match or party invite or in 15 minutes, whichever comes first.
Write the failure to a client log or a server log. Include the
```
status_code
```
.

For more information on Vivox logs, refer to Vivox Client SDK logs.

Once you have verified your implementation you can move on to logging in users.

Documentation

Development

User Acquisition

Monetization

Industry