Connecting to Interactive

Authorization

In order to connect to interactive and create a session you must first get authorization from the user.

// Get an authorization token for the user to pass to the connect function.
std::string authorization;
int error = authorize(authorization);
if (error) return error;

See the Authorization page for more details.

Create a session

Create a session by calling interactive_open_session.

interactive_session session;
int error = interactive_open_session(&session);
if (error) return error;

Register callbacks that you want to handle

You will almost certainly want to handle on_input and perhaps some other callbacks such as on_error or on_state_changed.

err = interactive_set_input_handler(session, handle_interactive_input);
if (err) return err;

See Handling Input for more details about how you might handle input from the interactive service.

Connect to Mixer interactive

// Connect to the user's interactive channel, using the interactive project specified by
// the version ID.
err = interactive_connect(session, authorization.c_str(), INTERACTIVE_ID, SHARE_CODE, true);
if(err) return err;

Pump interactive

Continuously call interactive_run to update state and handle messages from the interactive service.

// Simulate game update loop. All previously registered session callbacks will be called from this thread.
for (;;)
{
	// This call processes any waiting messages from the interactive service.
        // If there are no messages this returns immediately.
	err = interactive_run(session, 1);
	if (err) break;
	std::this_thread::sleep_for(std::chrono::milliseconds(16));
}

interactive_run takes an interactive_session and an int as a parameter. The int is the maximum number of interactive messages the call should process. This "pumping" design is meant to allow all registered callback handlers to be executed on the thread that calls interactive_run so that you may safely update UI or interact with the rest of your game without worrying about synchronization. Generally we recommend calling interactive_run at least once per frame in order to have input be responsive however you may want to process more than one message per frame if your game design expects to handle lots of input from interactive.

Connection state

After connecting to the session, connection state progress is reported via the on_state_changed handler. The states progress as follows:

enum interactive_state
{
    interactive_disconnected,
    interactive_connecting,
    interactive_connected,
    interactive_ready
};

Once interactive_connect returns, the interactive session will progress to interactive_connecting as it attempts to establish a websocket connection to the Mixer interactive servers. Once the socket is connected and all internal bootstrapping has completed, the next call to interactive_run will progress the session state to interactive_connected. During this time participants will be shown a "waiting for the game to be ready" notification indicating that the game is not in a state where it is accepting input. If the interactive_connect setReady flag was set or interactive_set_ready is called with true, the state will progress to interactive_ready which means all channel participants see controls and be able to interact with the scene that is set for their group, more on scenes and groups here.

If the websocket connection is lost for any reason, the state is reset to interactive_connecting as the websocket automatically attempts to repair itself. If this happens, all session state is reset. It's recommended that any session state bootstrapping that your application code does (participant group management or throttling for example) should be re-executed whenever the session state moves from interactive_connecting to interactive_connected, this way your application will gracefully handle reconnections.