Live Video Streaming

Authenticate yourself with the POST /authentication request.

Surfsight API uses Bearer authentication (also known as token authentication). The server generates a bearer token in response to a login request. The client provides this token in the Authorization header when making further requests.

You need an email address and password to get a token. When beginning your partnership with Surfsight, we send you an email containing this information.

To receive an authentication token:

Send the POST /authentication request with the following structure:

A. In the request body, enter the email address and password you received from Surfsight.

An authentication token is returned. This is the authentication token you will use for subsequent requests.

curl --request POST 'https://api-prod.surfsight.net/v2/authentication'
--header 'Content-Type: application/json'
--data-raw '{

  "email": "email@email.com",
  "password": "123Abcd!"
}'

B. In any subsequent request, include the header, using the following structure:

```--header 'Authorization: ImahFWLZWFdD8VVcUtIED2YuOjPFlZpldQTE5tUqKdv'```
    
The following is an example of the `POST /organizations` request, with the token in the header.

```
curl --request POST https://api-prod.surfsight.net/v2/organizations
--header 'Content-Type: application/json'
--header 'Authorization: ImahFWLZWFdD8VVcUtIED2YuOjPFlZpldQTE5tUqKdv'
--data-raw '{

  "name": "Missouri fleet"
}'

Receive the authentication token and media server address to retrieve a recording or live video with the POST /devices/{imei}/connect-media request.

    curl --request POST https://api-prod.surfsight.net/v2/devices/{imei}/connect-media
    --header 'Content-Type: application/json'
    --header 'Authorization: Bearer {token}'

Returned response:

{
    "data": {
        "address": "prodmedia-us-05.surfsolutions.com",
        "mediaToken": "0e5d4dfb-56fe-4271-b9c8-86e4d7f214d5"
    }
 }

In some cases the initial connection might and the request will return 404 - Not Found error. We recommend implementing a retry mechanism during this step if the error is catched.

To request to see the lenses available for live streaming, perform the request GET /devices/{imei}/cameras. cameraId 1 will be the front lens, and cameraId 2 will be the driver-facing lens.

Returned response:

{
    "data": [
        {
            "cameraId": 1
        },
        {
            "cameraId": 2
        }
    ]
}

Using the following URL format, perform the request GET https://mediaServerAddress/webrtc/sessionId/<imei>/cameraId/mediaToken. You may also refer to the function sendMessageToStartCall in the code example. A succesful connection will return the SDP information relevant to this connection.

If the response is 404 or a server error, your code is required to have a retry mechanism every three seconds.

Example code:

function sendMessageToStartCall(peer_id) {
    var theUrl = original_source.replace("#PEERID#", peer_id.toString());
    console.log(
        "sendMessageToStartCall(): ",
        theUrl /*JSON.stringify(options)*/
    );
    //making the https get call
    httpGetAsync(theUrl, httpGetAnswer);
}

An RTCPeerConnection() (https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/RTCPeerConnection) function should be used in order to begin the streaming session between the user-client and the device.

Use the following rtc_configuration with the RTCPeerConnection() function: {iceServers: [{urls: "stun:stun.services.mozilla.com"}, {urls: "stun:stun.l.google.com:19302"}]

Once a connection is made, the client should receive the Incoming stream message about which data the connection is sending. In this case, it will be video.

Example code:

function createCall(msg) {
    // Reset connection attempts because we connected successfully
    connect_attempts = 0;

    console.log("Creating RTCPeerConnection");

    peer_connection = new RTCPeerConnection(rtc_configuration);
    peer_connection.onaddstream = onRemoteStreamAdded;
    /* Send our video/audio to the other peer */
    var browserInfo = getBrowserInfo();
    if (browserInfo.name.toLowerCase() == "safari") {
        local_stream_promise = getLocalStream()
            .then((stream) => {
                console.log("Adding local stream");
                peer_connection.addStream(stream);
                return stream;
            })
            .catch(setError);
    } else {
        local_stream_promise = new Promise(function (resolve, reject) {
            resolve();
        });
    }

Using RTCSessionDescription protocol (https://developer.mozilla.org/en-US/docs/Web/API/RTCSessionDescription), accept and offer the SDP connection. You may also refer to the function onIncomingSDP in the code example.

Example code:

 function onIncomingSDP(sdp) {
		peer_connection
			.setRemoteDescription(sdp)
			.then(() => {
				setStatus("Remote SDP set");
				if (sdp.type != "offer") return;
				setStatus("Got SDP offer");
				local_stream_promise
					.then((stream) => {
						setStatus("Got local stream, creating answer");
						peer_connection
							.createAnswer()
							.then(onLocalDescription)
							.catch(setError);
					})
					.catch(setError);
			})
			.catch(setError);
	}

Using RTCPeerConnection.onicecandidate protocol (https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/onicecandidate), create a connection directly between the user-client and the device. At this point, the connection is strictly between the user's browser and the device. You may also refer to onIncomingIce function in the code example. The complete code is in the code sample. At this point, live video streaming should begin.

Example code:

	function onIncomingICE(ice) {
		var candidate = new RTCIceCandidate(ice);
		peer_connection.addIceCandidate(candidate).catch(setError);
	}