JavaScript WebRTC samples

This document descibes how to run the gRPC/WebRTC example. Support for WebRTC is officially only available on linux releases. This sample expects the emulator to be running in a server like environment:

There is a Webserver hosting the HTML/JS
There is a gRPC web proxy
The udp ports required for WebRTC are open, or a turn service is configured.

These services should be accessible for the browsers that want to interact with the emulator. For example a publicly visible GCE/AWS server should work fine.

This sample is based on ReactJS and provides the following set of components:

EmulatorWebrtcView: A view on the emulator that is using WebRTC. It will use the Jsep protocol over gRPC to establish the video streams. This is the preferred method to view the emulator, as it will provide the best experience.
EmulatorPngView: A view on the emulator that is generated by requesting a screenshot at a fixed interval. Beware that these screenshots can arrive out of order, so the user experience could be a little odd at times. Note: This is very expensive, and is merely here to showcase how you could make an interactive UI using gRPC.
EmulatorFallbackView: A View that will use WebRTC if possible, and otherwise will revert to using the png view.

You will likely need to modify App.js and index.html to suit your needs.

Dependencies

The JavaScript sample has the following requirements:

You are using linux.
You have android sdk installed, and the environment variable ANDROID_SDK_ROOT is set properly. The easiest way to install the sdk is by installing Android Studio.
An emulator build newer than 5769853. You can either:
- Check if your current installed version will work. Run:
```
 $ $ANDROID_SDK_ROOT/emulator/emulator -version | head -n 1
```
and make sure that the reported build_id is higher than 5769853
- Build one from source yourself.
- Obtain one from the build bots. Make sure to get sdk-repo-linux-emulator-XXXX.zip where XXXX is the build number. You can unzip the contents to $ANDROID_SDK_ROOT. For example:
```
  $ unzip ~/Downloads/sdk-repo-linux-emulator-5775474.zip -d $ANDROID_SDK_ROOT
```
A valid virtual device to run inside the emulator. Instructions on how to create a virtual device can be found here. Any virtual device can be used.
Node.js Stable version 10.16.1 LTS or later.
A protobuf compiler, version 3.6 or higher is supported.
The Go language. We use a gRPC web proxy written in Go for development purposes.
Dep the Go dependency manager. We use this to resolve all the dependencies for the web proxy.
Docker. We will use the container infrastructure for easy deployment. Follow the instructions here if you are within Google.

Configure the emulator

Make sure you are able to launch the emulator from the command line with a valid avd. Instructions on how to create a virtual device can be found here.

For example if you created a avd with the name P, you should be able to launch it as follows:

  $ $ANDROID_SDK_ROOT/emulator/emulator @P

Make sure that the emulator is working properly, and that can use the desired avd.

WebRTC support will be activated if the emulator is launched with the -grpc <port> flag. The current demos expect the gRPC endpoint to be available at localhost:5556. This port only needs to be accessible by the gRPC proxy that is being used. There is no need for this port to be publicly visible.

  $ $ANDROID_SDK_ROOT/emulator/emulator @P -grpc 5556

Do I need TURN?

The most important thing to is to figure out if you need a Turn Server. You usually only need this if your server running the emulator is behind a firewall, and not publicly accessible. Most of the time there is no need for a turn server.

If for example you are running the emulator in a private Google GCE project, you will need to make use of a turn server. You can take the following steps to enable turn:

Enable a turn service. There are many services you could use. A quick Google search will provide a series of provides. If you are internal at google you could use the GCE turn api.
Launch the emulator with the -turncfg flag. This will inform the videobridge to execute the given command for every new incoming connection to obtain the JSON turn configuration that will be used.
This command must do the following:
- Produce a result on stdout.
- Produce a result within 1000 ms.
- Produce a valid JSON RTCConfiguration object.
- That contain at least an “iceServers” array.
- The exit value should be 0 on success
For example:
```
emulator -grpc 5556 -turncfg "curl -s -X POST https://networktraversal.googleapis.com/v1alpha/iceconfig?key=MySec"
```

Configuring the web server

Once you can run the emulator with your avd of choice it is time to install all the development dependencies.

 $ make deps

If all goes well all the go, protobuf and javascript dependencies will be installed.

As a Developer

As a developer you will make use of the gRPC go proxy and use node.js to serve the react app. You can launch the develop environment with:

  $ make develop

This should open up a browser, and detect any change made to the webpages and JavaScript sources.

To stop the service:

  $ make stop

Note: make stop merely kills node and the grpcwebproxy

In production

A production version based on docker compose can be created as follows:

 $ make build-release

This will create two docker containers that work together to make the emulator accessible on the web. The two containers are:

Nginx container with the HTML and compiled JavaScript
Envoy proxy that forwards calls to the emulator.

The containers are configured in a compose file that binds to port 80 and 443. The envoy container will offer the self signed certs found in docker/certs. Modify the certs according to your needs.

You can start the service as follows:

 $ make run-release

Now point your browser to http://localhost.