Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
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
- Host: GitHub
- URL: https://github.com/genymobile/genymotion-device-web-player
- Owner: Genymobile
- License: mit
- Created: 2021-10-18T16:20:50.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-01-28T15:41:01.000Z (21 days ago)
- Last Synced: 2025-02-05T04:24:25.646Z (14 days ago)
- Topics: android, android-emulator, emulator, webrtc
- Language: JavaScript
- Homepage: https://www.genymotion.com/
- Size: 2.57 MB
- Stars: 114
- Watchers: 19
- Forks: 39
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Genymotion device web renderer

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.