session.md

Session

A Session object can be thought of as a collection of streams on which you may operate (publish or subscribe), or more simply as a "room". You can construct this object using opentok.createSession(props). A sessionId can be dynamically createdby your backend web service. This object is analogous to the JS API Session object.

Methods	Properties	Events
connect(apiKey, token)	sessionId	sessionConnected
disconnect()	streams	sessionDisconnected
publish(props)	sessionConnectionStatus	sessionFailed
unpublish()	connectionCount	streamCreated
subscribe(stream, props)		streamDestroyed

Methods

connect(apiKey, token)

Connect to an OpenTok Session. This must be done before you can do anything else with a Session.

Parameters:

• apiKey (String) required - OpenTok API Key. Sign up for an account and get one here
• token (String) required - User Token. This is generated by a server-side SDK.

Returns: (void)

disconnect()

Disconnect from an OpenTok session.

Returns: (void)

publish(props)

Begin publishing video data from the device's camera to the Session. When the publisher begins streaming data, the Session dispatches a "streamCreated" event. You can compare the connection.connectionId property of the Session object with the stream.connection.connectionId property of the "streamCreated" event object. If they match, the stream is published from your own connection.

Note that multiple publishers are not supported.

Parameters:

• props (Dictionary) optional:
  • name (String) optional - A name for the stream being created in the Session. The name is readable to others connected to the Session. Defaults to device name.
  • publishAudio (Boolean) optional - Whether or not the publisher sends audio. Defaults to true.
  • publishVideo (Boolean) optional - Whether or not the publisher sends video. Defaults to true.

Returns: (Publisher

unpublish()

Stop publishing to the Session. Removes the Publisher's VideoView from its superview.

Returns: (void)

subscribe(stream, props)

Begin receiving audio and/or video media from another Stream which is publishing to the Session. Steam objects are made available by listening to the streamCreated event.

Parameters:

• stream (Stream) required - A Stream object that refers to the video or audio data from a device.
• props (Dictionary) optional:
  • subscribeToAudio (Boolean) optional - Whether or not to subscribe to the audio data. Defaults to true.
  • subscribeToVideo (Boolean) optional - Whether or not to subscribe to the video data. Defaults to true.

Returns: (Subscriber)

Properties

sessionId

(String) The Session ID for this Session object. This is only writable before session.connect(apiKey, token) is called.

streams

(Array) A collection of all the Streams currently in the Session. Read Only

sessionConnectionStatus

(String) The state of the session. Possible values: "connected", "connecting", "disconnected", "failed". Read Only

connectionCount

(Number) The number of connections in the Session. Read Only

Events

"sessionConnected"

This event is fired when the session.connect(apiKey, token) call has resulted in a successful connection.

"sessionDisconnected"

This event is fired when the session.disconnect() call has completed.

"sessionFailed"

This event is fired when a Session is disconnected for any reason other than a call to session.disconnect().

Event Properties:

• error (Dictionary):
• message (String) - An English description of why the session disconnected.

"streamCreated"

This event is fired when a new Stream is available in the Session. This happens when another device publishes.

Event Properties:

• stream (Stream) - The stream that was just created.

"streamDestroyed"

This event is fired when a Stream leaves a Session. This can happen when a publishing device unpublishes or disconnects.

Event Properties:

• stream (Stream) - The stream that was just destroyed.