google / android-emulator-webrtc

Apache License 2.0
131 stars 35 forks source link

android-emulator-webrtc

This contains a set of React components that can be used to interact with the android emulator from the browser. It is intended to be used with an envoy proxy that is connected to a running emulator.

See the android container scripts for an example on how to run an emulator that is accessible via the web.

npm install --save android-emulator-webrtc

Full reference

Features


Usage

You can connect to remote unsecured emulator as follows:

import { Emulator } from "android-emulator-webrtc/emulator";

class EmulatorScreen extends React.Component {
  render() {
    return <Emulator uri="https://my.emulator" />;
  }
}

In order to connect to a secure endpoint you will have to provide an authorization service that provides the following functions:

 authHeader = () => {
    return { Authorization: 'Some Token' };
  };
}

For example:

import { Emulator } from "android-emulator-webrtc/emulator";

class EmulatorScreen extends React.Component {
  render() {
    return <Emulator uri="https://my.emulator" auth={my_auth_object} />;
  }
}

Full Reference

Emulator

A React component that displays a remote android emulator.

The emulator will mount a png or webrtc view component to display the current state of the emulator. It will translate mouse events on this component and send them to the actual emulator.

Authentication Service

The authentication service should implement the following methods:

Type of view

You usually want this to be webrtc as this will make use of the efficient webrtc implementation. The png view will request screenshots, which are very slow, and require the envoy proxy. You should not use this for remote emulators.

Pressing hardware buttons

This component has a method sendKey to sends a key to the emulator. You can use this to send physical hardwar events to the emulator for example:

"AudioVolumeDown" - Decreases the audio volume. "AudioVolumeUp" - Increases the audio volume. "Power" - The Power button or key, turn off the device. "AppSwitch" - Should bring up the application switcher dialog. "GoHome" - Go to the home screen. "GoBack" - Open the previous screen you were looking at.

prop type default required description
auth Object null :x: The authentication service to use, or null for no authentication.
height Number :x: The height of the component
muted Boolean true :x: True if the audio should be disabled. This is only relevant when using the webrtc engine.
onAudioStateChange Function (s) => { console.log("emulator audio: " + s); } :x: Called when the audio becomes (un)available. True if audio is available, false otherwise.
onError Function (e) => { console.error(e); } :x: Callback that will be invoked in case of gRPC errors.
onStateChange Function (s) => { console.log("emulator state: " + s); } :x: Called upon state change, one of ["connecting", "connected", "disconnected"]
gps :x: A GeolocationCoordinates like object indicating where the device is.
poll Boolean false :x: True if polling should be used, only set this to true if you are using the go webgrpc proxy.
uri String :white_check_mark: gRPC Endpoint where we can reach the emulator.
view Enum("webrtc", "png") "webrtc" :x: The underlying view used to display the emulator, one of ["webrtc", "png"]
volume Number 1.0 :x: Volume between [0, 1] when audio is enabled. 0 is muted, 1.0 is 100%
width Number :x: The width of the component

Note: The user must have interacted with the page before you can set the volume to "unmuted" (muted = false). Otherwise the video will not play and will throw an error, which is currently not handled.

Note: The volume is the volume of the video element that is displayed, this is not the actual volume used inside the emulator. You can change the audio inside the emulator by sending the proper keys as documented above, or follow the steps in the support document on how to change the audio volume.


EmulatorStatus

Kind: global class

new EmulatorStatus()

Gets the status of the emulator, parsing the hardware config into something easy to digest.

Param Type Description
uriOrEmulator string/EmulatorControllerService uri to gRPC endpoint.
auth object authorization class.

EmulatorStatus.getStatus

Gets the cached status.

Kind: static property of EmulatorStatus

EmulatorStatus.updateStatus

Retrieves the current status from the emulator.

Kind: static property of EmulatorStatus

Param Type Description
fnNotify Callback when the status is available, returns the retrieved status.
cache boolean True if the cache can be used.

Logcat

Observe the logcat stream from the emulator.

Streaming is done by either polling the emulator endpoint or making a streaming call.

It will send out the following events:

Kind: global class

new Logcat(uriOrEmulator, auth)

Creates a logcat stream.

The authentication service should implement the following methods:

Param Type
uriOrEmulator object
auth object

Logcat.on

Register a listener.

Kind: static property of Logcat

Param Type Description
name string Name of the event.
fn Callback Function to notify on the given event.

Logcat.off

Removes a listener.

Kind: static property of Logcat

Param Type Description
name string Name of the event.
fn Callback Function to notify on the given event.

Logcat.stop

Cancel the currently active logcat stream.

Kind: static property of Logcat

Logcat.start

Requests the logcat stream, invoking the callback when a log line arrives.

Note: Streaming can cause serious UI delays, so best not to use it.

Kind: static property of Logcat

Param Type Description
fnNotify Callback when a new log line arrives.
refreshRate number polling interval, or 0 if you wish to use streaming.