Gininet

Gininet API v1.0 (client side)

Introduction

This is the second part of how a Gininet event works: client side.
These calls do not require an API key, they require an Access Token to the event (ticket).

Never transfer your API access token to the client side.

Embedded session vs custom implementation

The Gininet Embedded Session is a complete client side implementation for web applications. Your application can embed it in an iframe. It requires only the ticket code to be passed as a parameter. See more about the Gininet Embedded Session and how to use it in How it works -> Gininet Embedded Session.

With the documentation below, you are able to implement your own client side if needed.

Client side flow:

All participants in a Gininet event including the presenter must start with a joinevent request which returns information about the ticket and the event

Save the obtained data on the client side for future reference

Then connect via websockets (except simple broadcast with no interactive tickets)

Once the WebSocket connection is established, wait for a 'connected' message

Based on event type, ticket type and available stack on the client side, choose a stack to use: WebRTC or RTMP in case of presenter in a simple broadcast. Start the Player stack in case of a TC or NI ticket holder and if an AV ticket holder's platform doesn't support WebRTC.

Joining an event

The protocol is the same as the server side API: HTTP POST a json object over SSL to the API endpoint.
The only difference is that this call doesn't require the APIToken header

Never transfer your API access token to the client side.

Join an event

The function returns the connection information to connect to the event.

https://api.gininet.com/event/join

Parameters:

Name Type Description
ticket (*) String The id of the ticket the client holds

Positive response:

Name Type Description
role (*) String The role that this ticket gives the userin this session. (can be one of "P","AV","TC","NI")
wsurl (*) String If the user needs to start the instant communication part of the client side, this is the URL to connect to
rtmp Object RTMP details as {"url":"rtmp url", "stream":"streamname and access parameters"} to use in an external streamer (only for the presenter in a simple broadcast)
ready Boolean Indicatin whether the session is ready to accept participants
starttime (*) ISO 8601 date+time string Time when the event starts
endtime (*) ISO 8601 date+time string Time when the event ends
ts (*) unix timestamp in milliseconds The Gininet system's collective timestamp at response time (to correct countdowns on client side)
item (*) Object The event's record (for displaying name or other details of the event)

Negative response:

Name Type Description
error String The error description

Example

Request

curl -X POST -H 'Content-Type: application/json' -d '{"ticket":"a452-bc8e-f2e6-9830-d89e-a71c"}' https://api.gininet.com/event/join

Response

{"wsurl":"wss://anode12345678.gininet.com/ws?ticket=a452-bc8e-f2e6-9830-d89e-a71c", "role":"AV", "starttime":"2017-10-18T14:47:47.000Z", "endtime":"2017-10-18T15:47:47.000Z", "ts":1508334522174, "item":{...}}

{"error":"Invalid ticket id"}

Player client side

The player stack plays an h.264+AAC HLS stream which has multiple bitrates.

The URL of the stream is in the following format:

https://ls.gininet.com/hls/<event.id>.m3u8?ticket=<ticket.id>

Where event.id is the ID of the current Gininet Session (event)
ticket.id is the ID of the Session Access Token (ticket)

The player must support cookies

The player on browser platform should work with the CORS headers.

RTMP client side

The RTMP stack displays the access details to the user to start publishing an RTMP stream and starts the Player client side stack to enable user to watch the broadcast back from 15 mins before the event starts. See our RTMP Guide for more information on how to publish an RTMP stream.

RTMP streaming is only available in case of a Simple Broadcast (SB) event and for the Presenter only

WebRTC client side

When the WebRTC session starts, you need to build the user interface and the layout of video surfaces according to the session type.

Layout

Interactive (Broadcast) renders the presenter's video that is automatically scaled to occupy the maximum available space in the container and up to ten containers for Audio-Video Interactive ticket holders. Each of these containers may contain a still picture, status indicators, the name and - when available and enabled - the camera video of the participant.

Conference (Broadcast) consists of "cards" of the same size. The screen is split into the required number of cards according to the number of participants at any time.

Presenter in a Simple Broadcast can use WebRTC to stream in. The layout in this case has one video surface which is the loopback video from the presenter's camera device.

On browser platform use the id attribute of the container and the received "avid" field of a participant to link the container to a participant.

These layouts are only examples and your application may require a different, more suitable one. By implementing your client side it's up to you, how you structure information on the user interface. Use the functions in the following section to build your interactive client side application:

WebRTC-related functions on a WebSocket connection with slim rpc layer

We require the usage of our slim rpc layer when communicating with the Gininet Interactive Endpoints. This layer forms a very simple protocol in which each message is a stringified JSON object.
Each of these objects has a required 'fnc' field which is the function name, an optional 'params' field which holds the parameters of the function and an optional 'id' field which indicates that this call requires results to be returned. The 'id' field also assigns a unique identifier to this call that can be used when delivering the results.
Returning results to a function call must use a special '%%ret' function, the result is stored in the 'params' field and the 'id' field must be the 'id' of the received call.

Example request:

{ "fnc":"publish", "id": 1, "params": { "type": "av" } }

Example response:

{ "fnc":"%%ret", "id":1, "params":{ "rtcid": "598eb2e439650e9e8ffe3490" } }

List of functions in an Interactive Session

Outbound (client side calls function on the Interactive Endpoint)

keepalive

After you established the WebSocket connection to the Interactive Endpoint, you must periodically call this function to maintain the connection.
We require a once per 30s rate.

Parameters:
none

Returns:
none

avDetails

Audio-Video Interactive ticket holders must use this function once they are connected to the Interactive Endpoint to send their name and picture. The Interactive Endpoint then start introducing this AV ticket holder to the ongoing session.

Parameters:
{
"name":"username",
"pic":"image-data" // HTML image toDataURL("image/jpeg") produced jpeg buffer
}

Returns:
none

publish

When the client side wants to start publishing a stream, it needs to request an rtcid from the Interactive Endpoint.

Parameters:
{
"type": "stream-type", // One of "av" or "ss". "av" means audio video (camera and microphone) while "ss" means screenshare
}

Returns:
{
"rtcid": "rtc-id-of-the-new-stream"
}

subscribe

After receiving notification of a new available stream, the client side can subscribe to that stream using this function.

Parameters:
{
"sid":"stream-id"
}

Returns:
{
"rtcid":"rtc-id-of-the-new-stream"
}

avHandUp

In an Interactive (Broadcast) session, the AV ticket holder can indicate that she/he wishes to interact using audio-video. This function sends a request to the Presenter who then decides when the AV ticket holder can publish a stream

Parameters:
none

Returns:
none

signaling

Use this function on the client side when a WebRTC Offer or Answer is produced or a Candidate was produced by an RTCConnection object on the client side

Parameters:
{
"sid":"rtc-stream-id", "type":"signaling-type", // one of "offer", "candidate", "answer" "offer":"sdp-offer-data" || "candidate":"sdp-candidate-data" || "answer":"sdp-answer-data" // only one of these fields should be supplied, depending on Signaling type.
}

Returns:
none

avStart

Presenter sends this command in an Interactive (Broadcast) session to instruct an AV client side to start publishing a stream.

Parameters:
{
"avid":"id-of-the-av-user"
}

Returns:
none

avStop

Presenter sends this command in an Interactive (Broadcast) session to instruct an AV client side to stop publishing a stream.

Parameters:
{
"avid":"id-of-the-av-user"
}

Returns:
none

message

All but NI ticket holders can use this function in all session types to send a public message.

Parameters:
{
"name":"name-of-user",
"msg":"message-to-send"
}

Returns:
none

Inbound (Interactive Endpoint calls function on the client side)

avIn

When a new AV ticket holder joined the session. The data sent as parameter contains the new user's picture, name and avid.

Parameters:
{
"name":"name-of-the-new-av-user",
"pic":"picture-of-user-in-base64-jpeg-format",
"avid":"av-id-of-the-new-user"
}

Returns:
none

avOut

When one of the AV ticket holders left the session.

Parameters:
{
"avid":"av-id-of-the-user-who-left-the-session"
}

Returns:
none

avHandUp

When one of the AV ticket hodlers indicated that she or he wants to talk.

Parameters:
{
"avid":"avid-of-the-user"
}

Returns:
none

avStart

Av ticket holders receive this message from the Interactive Endpoint when the Presenter wants to start this AV ticket holder publishing.

Parameters:
none

Returns:
none

avStop

When the Presenter wants to stop this AV ticket holder's stream.

Parameters:
none

Returns:
none

signaling

When a signaling message is available. According to its id, pass this information to the relevant RTCConnection object.

Parameters:
{
"sid":"rtc-stream-id",
"type":"signaling-type", // One of "offer", "candidate", "answer" depending what produces the message
"candidate":"sdp-candidate-data" || "offer":"sdp-offer-data" || "answer":"sdp-answer-data" // Only one of these fields should exists depending on Signaling type
}

Returns:
none

streamAvailable

Indicates that a new Stream is available in the session. The message also contains informatin about the role of the stream origin, the type of the stream and optionally if the origin is one of the AV ticket holders the ID of the AV ticket holder.

Parameters:
{
"sid":"stream-id-of-the-new-stream",
"role":"role-of-user",
"type":"stream-type", // One of "av", "ss". av means audio-video (camera and microphone), ss means screenshare
["avid": "av-id-of-user-if-stream-belongs-to-one"] // Optional field, if role is "AV", this field carries the id of the AV ticket holder
}

Returns:
none

streamRemoved

When one of the streams in the session has been removed.

Parameters:
{
"sid":"stream-id-of-the-stream",
"role":"role-of-user",
["avid": "av-id-of-user-if-stream-belongs-to-one"] // Optional field, if role is "AV", this field carries the id of the AV ticket holder
}

Returns:
none

message

When a new message has been sent in the session.

Parameters:
{
"name":"name-of-user",
"msg":"message-of-user",
"timestamp":"timestamp-of-message"
}

Returns:
none