Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/genymobile/genymotion-device-web-player

Genymotion Virtual Device Web Player
https://github.com/genymobile/genymotion-device-web-player

android android-emulator emulator webrtc

Last synced: 7 days ago
JSON representation

Genymotion Virtual Device Web Player

Awesome Lists containing this project

README

        

# Genymotion device web renderer

![npm](https://img.shields.io/npm/v/@genymotion/device-web-player)
![GitHub](https://img.shields.io/github/license/Genymobile/genymotion-device-web-player)



This repository contains the Genymotion device web renderer JavaScript SDK.
It provides an easy way to integrate **Genymotion devices** running in the cloud into any web application. You will be able to display an emulator screen and interact with the device.

### ๐Ÿš€ Engineered for Power

- **compatibility** (vanilla JavaScript, no external framework used)
- **performance** (30fps or more)
- **quality** (Up to 1920ร—1080)
- **low latency**

For more information about Genymotion devices, please visit the [Genymotion website](https://www.genymotion.com).

## ๐Ÿ“œ Table of contents

1. ๐Ÿ“‹ [Requirements](#๐Ÿ“‹-requirements)
2. ๐Ÿ“ฆ [Installation](#๐Ÿ“ฆ-installation)
1. ๐Ÿ“ฅ [Install via NPM / Yarn](#๐Ÿ“ฅ-install-via-npm--yarn)
2. ๐ŸŒ [Install via a CDN](#๐ŸŒ-install-via-a-cdn)
3. โšก [Quick Start Guide](#โšก-quick-start-guide)
4. ๐ŸŽจ [Style and CSS](#๐ŸŽจ-style-and-css)
5. ๐Ÿ“˜ [API Documentation](#๐Ÿ“˜-api-documentation)
1. ๐Ÿ“ก [VM Communication](#๐Ÿ“ก-vm_communication)
2. ๐Ÿ› ๏ธ [utils](#๐Ÿ› ๏ธ-utils)
3. ๐ŸŽฎ [keyMapping](#๐ŸŽฎ-keyMapping)
4. ๐Ÿ”Š [media](#๐Ÿ”Š-media)
5. ๐ŸŽฅ [video](#๐ŸŽฅ-video)
6. โš™๏ธ [Features & Instance Options](#โš™๏ธ-features--instance-options)
1. ๐Ÿ–ฅ๏ธ [Instance Options](#๐Ÿ–ฅ๏ธ-instance-options)
2. ๐Ÿ”Œ [Plugin Options](#๐Ÿ”Œ-plugin-options)
7. โ“ [FAQ](#โ“-faq)
8. ๐Ÿค [Contributing](#๐Ÿค-contributing)

## ๐Ÿ“‹ Requirements

A Modern, WebRTC compatible, Web browser:

- Google Chrome 85+
- Mozilla Firefox 78+
- Opera 70+
- Microsoft Edge 20.10240+
- Safari 11+

## ๐Ÿ“ฆ Installation

### ๐Ÿ“ฅ Install via NPM / Yarn

Using yarn:

```bash
yarn add @genymotion/device-web-player
```

Using npm:

```bash
npm install @genymotion/device-web-player
```

Package import (commonJS):

```js
const {DeviceRendererFactory} = require('genymotion/device-web-player');
```

```html

@import 'genymotion-device-web-renderer/dist/css/device-renderer.min.css';

```

### ๐ŸŒ Install via a CDN

```html

```

## โšก Quick Start Guide

Use `DeviceRendererFactory` to instantiate one or more device renderers.
All you need is an HTML element to use as a container. See example below.
To find your instance WebRTC address, use the [SaaS API](https://developer.genymotion.com/saas/#operation/getInstance)
or check the [PaaS documentation](https://docs.genymotion.com/paas/01_Requirements/), based on your device provider.

```html

// Instance address
const webrtcAddress = 'wss://x.x.x.x';
const container = document.getElementById('genymotion');

// See "Features & options" section for more details about options
const options = {
token: 'i-XXXXXXXXXX', // token is the shared secret to connect to your VM
fileUpload: false, // requires fileUploadUrl
};

// Device renderer instanciation
const {DeviceRendererFactory} = window.genyDeviceWebPlayer;
const deviceRendererFactory = new DeviceRendererFactory();
const rendererAPI = deviceRendererFactory.setupRenderer(
container, // the container element or element ID to use
webrtcAddress, // the websocket address of your instance connector
options, // options object to enable or disable features
);

// Disconnect the device renderer, closing any open data channels.
window.addEventListener('beforeunload', function () {
playerAPI.disconnect();
});

```

## ๐ŸŽจ Style and CSS

The player uses css variables to style some parts of the app, but the player is still totally customisable through overloading the css classes.

#### CSS variables available with their default presets:

Colors

--gm-text-color: #ffffff;
--gm-primary-color: #e6195e;
--gm-secondary-color: #292929;
--gm-success-color: #11b920;

Player

--gm-player-bg-color: var(--gm-secondary-color);
--gm-loader-color: var(--gm-text-color);

Toolbar

--gm-toolbar-bg-color: var(--gm-secondary-color);
--gm-toolbar-icon-color: #e8eaed;
--gm-toolbar-icon-color-hover: var(--gm-primary-color);

Button

--gm-btn-text-color: var(--gm-text-color);
--gm-btn-bg-color: var(--gm-primary-color);
--gm-btn-bg-color-hover: var(--gm-primary-color);
--gm-btn-bg-color-disabled: rgba(179, 179, 179, 0.24);
--gm-btn-bg-color-disabled-hover: #828282;
--gm-btn-color-disabled: #c4c4c4;

Input

--gm-input-text-color: #000;

Design

--gm-underline-color: var(--gm-text-color);

Modal
--gm-modal-bg-color: var(--gm-secondary-color);

## ๐Ÿ“˜ API Documentation

The Player API provides functionality for managing plugin options and websocket communication. These operations are handled through the API (categorized) object returned by the `setupRenderer` function.

### ๐Ÿ“ก `VM_communication`

#### `disconnect`

**Description**: Disconnects the player from the virtual machine (VM) and cleans up the memory listeners.

#### `addEventListener`

**Description**: Registers a listener for messages emitted from the VM.

- **Parameters**:

- `event` (string): The name of the event to listen for (e.g., 'fingerprint', 'gps').
- `callback` (function): The function to call when the event is emitted. The VM's message will be passed to the callback.

- **Example usage**:
```js
addEventListener('fingerprint', (msg) => {
console.log(msg);
});
```

#### `sendData`

**Description**: Sends messages to the VM.

- **Parameters**:

- `data` (object): An object containing the channel and messages to be sent.
- `channel` (string): The channel to send the messages to.
- `messages` (array\): An array of messages to send.

- **Example usage**:
```js
sendData({
channel: 'battery',
messages: ['set state level 10', 'set state status true'],
});
```

### ๐Ÿ› ๏ธ `utils`

#### `getRegisteredFunctions`

**Description**: Returns a list of available functions with optional descriptions.

### ๐ŸŽฎ `keyMapping`

#### `setConfig`

**Description**: Provides configuration for keymapping. The configuration is passed as an object containing key-value pairs

- **Example configuration**:
```js
{
dPad: [{
keys: [
{
key: 'w',
effect: { initialX: 20, initialY: 80, distanceX: 0, distanceY: -10 },
name: 'up',
description: 'move up',
},
{
key: 's',
effect: { initialX: 20, initialY: 80, distanceX: 0, distanceY: 10 },
name: 'down',
description: 'move down',
},
// ... other keys
],
name: 'character movement',
description: 'Left joystick used to move the character',
}],
tap: [{
key: 'p',
effect: { initialX: 50, initialY: 50 },
name: 'Fire',
}],
swipe: [{
key: 'u',
effect: { initialX: 50, initialY: 50, distanceX: -10, distanceY: 0, description: 'swipe left' },
name: 'Left dodge',
description: 'Dodge on the left',
}]
}
```

#### `activeKeyMappingDebug`

**Description**: Helper to create the config mapping.

- **Parameters**:
- `isTraceActivate` (boolean): If true, it prints the x and y coordinates over the video stream for all clicks.
- `isGridActivate` (boolean): If true, displays a grid over the video stream. Both rows and columns have a size of 10%.

#### `enable`

**Description**: Enable or disable keymapping.

- **Parameters**:
- `isActive` (boolean, optional): Enable or disable keymapping. Default is false.

### ๐Ÿ”Š `media`

#### `mute`

**Description**: Mutes the playerโ€™s audio.

#### `unmute`

**Description**: Unmutes the playerโ€™s audio.

### ๐ŸŽฅ `video`

#### `fullscreen`

**Description**: Enables fullscreen mode, but must be called from a user action in compliance with browser security rules.

## โš™๏ธ Features & Instance options

A device renderer instance can be configured using the `options` argument (object). Possible configuration key / value are described below.

### ๐Ÿ–ฅ๏ธ Instance options

#### `token`

- **Type:** `String`
- **Default:** `undefined`
- **Compatibility:** `PaaS`, `SaaS`
- **Details:**
Instance access token, the shared secret used to connect to the device. For Genymotion PaaS devices, the token is the instance id (more information can be find [here](https://docs.genymotion.com/paas/02_Getting_Started/)). For SaaS devices, you must generate the access token using the [login api](https://developer.genymotion.com/saas/#operation/login).

#### `toolbarOrder`

- **Type:** `Array`
- **Default:** `[]`
- **Special options**
- `separator`: to display a separator between icons
- `unordered`: displays all other plugin icons that are active but not explicitly specified in the `toolbarOrder`
- **Example**:`[
'ButtonsEvents_ROTATE',
'separator',
'Battery',
'FingerPrint',
'separator',
'unordered',
'separator',
'ButtonsEvents_POWER']`
- **Details:**
The `toolbarOrder` option allows you to define the order in which plugin icons appear in the toolbar. Each string in the array corresponds to the unique identifier (id) of a button registered in the toolbar manager. The IDs of the plugins are provided below in the plugin option details.

#### `showPhoneBorder`

- **Type:** `Boolean`
- **Default:** `false`
- **Details:**
Adds a mobile-style frame around the video to mimic the appearance of a smartphone screen.

#### `connectionFailedURL`

- **Type:** `String`
- **Default:** `undefined`
- **Compatibility:** `SaaS`, `PaaS`
- **Details:**
Redirection page in case of a connection error.

#### `giveFeedbackLink`

- **Type:** `String`
- **Default:** `giveFeedbackLink`
- **Compatibility:** `SaaS`, `PaaS`
- **Details:**
Set the url for the feedback page.

#### ๐Ÿ”ง Advanced Options

#### `i18n`

- **Type:** `Object`
- **Default:** `{}`
- **Compatibility:** `PaaS`, `SaaS`
- **Details:**
Alternative translation for the renderer UI.

#### `stun`

- **Type:** `Object`
- **Default:** `{}`
- **Compatibility:** `PaaS`, `SaaS`
- **Details:**
WebRTC STUN servers configuration. Format:

```js
{
urls: [
'stun:stun-server1.org:80',
'stun:stun-server2.org:443',
...
],
}
```

#### `turn`

- **Type:** `Object`
- **Default:** `{}`
- **Compatibility:** `PaaS`, `SaaS`
- **Details:**
WebRTC TURN servers configuration. Format:

```js
{
urls: [],
username: "myUsername",
credential: "myPassword",
default: false // Whether or not we should use the TURN servers by default. Default: false.
}
```

### ๐Ÿ”Œ Plugin Options

#### battery

- **Type:** `Boolean`
- **Default:** `true`
- **Toolbar name:** `Battery`
- **Compatibility:** `PaaS`, `SaaS`
- **Details:**
Enable or disable the battery widget. This widget can be used to set the battery level and state of the Android virtual device.

#### baseband

- **Type:** `Boolean`
- **Default:** `false`
- **Toolbar name:** `Baseband`
- **Compatibility:** `PaaS`, `SaaS`
- **Details:**
Enable or disable the baseband (MMC/MNC) widget.

#### biometrics

- **Type:** `Boolean`
- **Default:** `true`
- **Toolbar name:** `FingerPrint`
- **Compatibility:** `SaaS`, `PaaS`
- **Details:**
Enable or disable the fingerprint widget. This widget can be used to manage fingerprint reading requests. Available for Android 9 and above.

#### camera

- **Type:** `Boolean`
- **Default:** `true`
- **Toolbar name:** `Camera`
- **Compatibility:** `PaaS`, `SaaS`
- **Details:**
Enable or disable the camera widget. This widget can be used to forward local webcam video to the Android virtual device. By default, if the `microphone` property is also true, then the default audio input will be used as well.

#### clipboard

- **Type:** `Boolean`
- **Default:** `true`
- **Toolbar name:** `Clipboard`
- **Compatibility:** `PaaS`, `SaaS`
- **Details:**
Enable or disable the clipboard widget. This widget allows you to share clipboard content between the local machine and the Android virtual device, enabling seamless copy-paste functionality in both directions.

#### capture

- **Type:** `Boolean`
- **Default:** `true`
- **Toolbar name:** `Screencast`
- **Compatibility:** `PaaS`, `SaaS`
- **Details:**
Enable or disable the capture widget. This widget can be used to capture the screen of the Android virtual device (screenshot or screencast).

#### diskIO

- **Type:** `Boolean`
- **Default:** `true`
- **Toolbar name:** `IOThrottling`
- **Compatibility:** `PaaS`, `SaaS`
- **Details:**
Enable or disable the diskIO widget. This widget can be used to modify Disk IO (throttling) of the Android virtual device.

#### fileUpload

- **Type:** `Boolean`
- **Default:** `true`
- **Toolbar name:** `FileUpload`
- **Compatibility:** `PaaS`, `SaaS`
- **Details:**
Enable or disable the fileUpload widget and drag & drop. This widget can be used to forward local file to the Android virtual device. When dragging & dropping APK or ZIP files, it will install them.

#### `fileUploadUrl`

- **Type:** `String`
- **Default:** `undefined`
- **Compatibility:** `PaaS`, `SaaS`
- **Details:**
Set the file upload URL, required if `fileUpload` is set to `true`.

#### fullscreen

- **Type:** `Boolean`
- **Default:** `true`
- **Toolbar name:** `Fullscreen`
- **Compatibility:** `PaaS`, `SaaS`
- **Details:**
Enable or disable the fullscreen widget. This widget can be used to make the renderer go fullscreen.

#### gamepad

- **Type:** `Boolean`
- **Default:** `true`
- **Toolbar name:** `Gamepad`
- **Compatibility:** `SaaS`, `PaaS`
- **Details:**
Enable or disable gamepad support & widget.

#### gps

- **Type:** `Boolean`
- **Default:** `true`
- **Toolbar name:** `GPS`
- **Compatibility:** `PaaS`, `SaaS`
- **Details:**
Enable or disable the GPS widget. This widget can be used to set the GPS location of the Android virtual device. If you want to use a visual map instead of GPS coordinates to set the location, you must import the Google Maps library with your API key.

```html

```

#### `gpsSpeedSupport`

- **Type:** `Boolean`
- **Default:** `false`
- **Compatibility:** `PaaS`, `SaaS`
- **Details:**
Enable or disable GPS speed support.

#### identifiers

- **Type:** `Boolean`
- **Default:** `true`
- **Toolbar name:** `Identifiers`
- **Compatibility:** `PaaS`, `SaaS`
- **Details:**
Enable or disable the identifiers widget. This widget can be used to set the identifiers (Android ID / IMEI) of the Android virtual device.

#### `keyboard`

- **Type:** `Boolean`
- **Default:** `true`
- **Compatibility:** `PaaS`, `SaaS`
- **Details:**
Enable or disable the keyboard widget. This widget can be used to transmit keyboard keystrokes to the Android virtual device.

#### keyboardMapping

- **Type:** `Boolean`
- **Default:** `true`
- **Toolbar name:** `KeyboardMapping`
- **Compatibility:** `PaaS`, `SaaS`
- **Details:**
Enable or disable the keyboard mapping. This widget can be used to map keys with commands (e.g., tap, swipe-left, tilt, etc.).

#### `microphone`

- **Type:** `Boolean`
- **Default:** `false`
- **Compatibility:** `PaaS`
- **Details:**
Enable or disable microphone injection. This can be used to forward the local microphone (or webcam audio) to the Android virtual device.

#### `mouse`

- **Type:** `Boolean`
- **Default:** `true`
- **Compatibility:** `PaaS`, `SaaS`
- **Details:**
Enable or disable the mouse events. If you want to disable all VM interactions, also disable `touch` and `keyboard`.

#### navbar

- **Type:** `Boolean`
- **Default:** `true`
- **Toolbar name:** `ButtonsEvents_RECENT_APP`, `ButtonsEvents_HOME`, `ButtonsEvents_BACK`
- **Compatibility:** `PaaS`, `SaaS`
- **Details:**
Enable or disable the navbar widgets. This widget can be used to navigate in the Android virtual device like when using hardware buttons.

#### network

- **Type:** `Boolean`
- **Default:** `true`
- **Toolbar name:** `Network`
- **Compatibility:** `PaaS`, `SaaS`
- **Details:**
Enable or disable the network widget. This widget can be used to enable or disable the Wi-Fi or mobile network, and to set network throttling (mobile network type and signal strength) of the Android virtual device.

#### phone

- **Type:** `Boolean`
- **Default:** `true`
- **Toolbar name:** `Phone`
- **Compatibility:** `PaaS`, `SaaS`
- **Details:**
Enable or disable the phone widget. This widget can be used to send SMS's or make phone calls to the Android virtual device.

#### power

- **Type:** `Boolean`
- **Default:** `true`
- **Toolbar name:** `ButtonsEvents_POWER`
- **Compatibility:** `PaaS`, `SaaS`
- **Details:**
Enable or disable the power widget. This widget can be used to power off or reboot the Android virtual device.

#### rotation

- **Type:** `Boolean`
- **Default:** `true`
- **Toolbar name:** `ButtonsEvents_ROTATE`
- **Compatibility:** `PaaS`, `SaaS`
- **Details:**
Enable or disable the rotation widget. This widget can be used to rotate the Android virtual device.

#### streamResolution

- **Type:** `Boolean`
- **Default:** `true`
- **Toolbar name:** `StreamResolution`
- **Compatibility:** `SaaS`
- **Details:**
Enable or disable the video stream quality widget.

#### streamBitrate

- **Type:** `Boolean`
- **Default:** `false`
- **Toolbar name:** `StreamBitrate`
- **Compatibility:** `SaaS`
- **Details:**
Enable or disable the stream bitrate widget.

#### volume

- **Type:** `Boolean`
- **Default:** `true`
- **Toolbar name:** `ButtonsEvents_VOLUME_UP`, `ButtonsEvents_VOLUME_DOWN`
- **Compatibility:** `PaaS`, `SaaS`
- **Details:**
Enable or disable the volume widget. This widget can be used to increase or decrease the volume of the Android virtual device.

#### `wifi`

- **Type:** `Boolean`
- **Default:** `true`
- **Compatibility:** `PaaS`, `SaaS`
- **Details:**
Enable or disable the Wi-Fi widget. This widget can be used to enable or disable the Wi-Fi network on the Android virtual device.

## โ“ FAQ

### How do I get an API key?

Sign up on [Genymotion SaaS](https://cloud.geny.io/signin) and generate an API key from the dashboard.

### Can I use this SDK with on-premise deployments?

No, this SDK is designed for Genymotion's SaaS platform only.

## ๐Ÿค Contributing

Read through our [contributing guidelines](https://github.com/Genymobile/genymotion-device-web-player/blob/main/CONTRIBUTING.md) to learn about our submission process, coding rules and more.