This getting started page will guide you through your first ApiRTC implementation.
In your .html
file, load the ApiRTC js library from the <head>...</head>
tag:
In your project directory, run:
In your project directory, run:
In your project directory, run:
In build.gradle
, add:
CocoaPods installation
Use Podfile post_install setup to properly link dependencies:
Before we start coding... let's walk through the main concepts and classes:
UserAgent
representing the local individual, Session
must be opened with ApiRTC's servers to create a Conversation
to which individuals can join, Conversation
, individuals can chat, watch, listen and/or share real-time audio, video, data, screen..., Stream
is audio, and/or video captured from sources available from browser and published on a Conversation
. As the entry point to ApiRTC, UserAgent
is instantiated using the apiKey associated to your enterprise account on https://cloud.apirtc.com .
Get your apiKey from https://cloud.apirtc.com/enterprise/api
When UserAgent.createStream(options)
is called, a popup opens in the browser to request user acceptance for using media devices. The returned Promise
resolves with an instance of Stream
, which carries media stream from computer device through the browser.
The method Stream.attachToElement(domElement)
binds the media stream to a DOM <video>
element in order to display it in the web page.
To use ApiRTC's connected features, a userAgent
must register to get a session. This can be done with or without authentication.
Simply using UserAgent.register()
without authentication details registers a userAgent
with ApiRTC's servers without authentication.
The session
grants access to connected features such like conversations.
An instance of Conversation
is obtained from Session.getOrCreateConversation(name)
.
Calling Conversation.join()
makes the userAgent
used to create the Session
used to create this instance of Conversation
(through it's Session
) join the conversation.
Once a conversation joined, a userAgent
can publish a stream using Conversation.publish(stream)
method:
Subscribing to peer streams shall be implemented as followed:
Listen on Conversation
'streamListChanged'
event to get notified of streams published to the conversation. The data provided by the event is a StreamInfo
: It gives information on streams published in the conversation such as the id (StreamInfo.streamId
) of the stream. StreamInfo.listEventType
property tells whether the event is triggered for and addition (value 'added'
) or a removal.
Calling conversation.subscribeToStream(streamId)
with the StreamInfo.streamId
of an added remote stream makes this conversation subscribe to a stream.
Finally, listening on Conversation
'streamAdded'
notifies with a remote Stream
instance which can be attached to web page for display.
A stream published to a conversation can be restarted for various technical reasons. In this case the 'streamListChanged'
won't be fired ; but the 'streamRemoved'
event will be fired with corresponding Stream
instance, and a 'streamAdded'
with the new instance will follow, allowing to display correct Stream
.
It is then important to listen on 'streamRemoved'
to stop displaying the corresponding Stream
.
Also, handling the remote streamInfo.listEventType === 'removed'
is important to get notified that a stream is not published anymore.