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.

📜 Table of contents

📋 Requirements
📦 Installation
1. 📥 Install via NPM / Yarn
2. 🌐 Install via a CDN
⚡ Quick Start Guide
🎨 Style and CSS
📘 API Documentation
1. 📡 VM Communication
2. 🛠️ utils
3. 🎮 keyMapping
4. 🔊 media
5. 🎥 video
⚙️ Features & Instance Options
1. 🖥️ Instance Options
2. 🔌 Plugin Options
❓ FAQ
🤝 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:

yarn add @genymotion/device-web-player

Using npm:

npm install @genymotion/device-web-player

Package import (commonJS):

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

<style lang="scss">
    @import 'genymotion-device-web-renderer/dist/css/device-renderer.min.css';
</style>

🌐 Install via a CDN

<link
    rel="stylesheet"
    href="https://cdn.jsdelivr.net/npm/@genymotion/[email protected]/dist/css/device-renderer.min.css"
/>
<script src="https://cdn.jsdelivr.net/npm/@genymotion/[email protected]/dist/js/device-renderer.min.js"></script>

⚡ 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 or check the PaaS documentation, based on your device provider.

<!-- OPTIONAL: Import google maps library with your API key to enable map positioning feature
<script src="https://maps.googleapis.com/maps/api/js?key=xxxxxxxxxxxxxxxxxxxxxxxx-yyyyyyyyyyyyyy"></script>
-->

<div id="genymotion"></div>

<script>
    // 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();
    });
</script>

🎨 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:

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<string>): An array of messages to send.

Example usage:

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:

{
    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). For SaaS devices, you must generate the access token using the login api.

`toolbarOrder`

Type: Array<string>
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:

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

`turn`

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

{
    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.

<!-- OPTIONAL: Import google maps library with your API key to enable map positioning feature -->
<script src="https://maps.googleapis.com/maps/api/js?key=xxxxxxxxxxxxxxxxxxxxxxxx-yyyyyyyyyyyyyy"></script>

`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 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 to learn about our submission process, coding rules and more.

Name		Name	Last commit message	Last commit date
Latest commit History 344 Commits
.github		.github
CI		CI
doc/assets		doc/assets
example		example
gulp		gulp
src		src
tests		tests
.eslintignore		.eslintignore
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.nvmrc		.nvmrc
.prettierrc		.prettierrc
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
bower.json		bower.json
gulpfile.js		gulpfile.js
index.d.ts		index.d.ts
package.json		package.json
yarn.lock		yarn.lock

License

Genymobile/genymotion-device-web-player

Folders and files

Latest commit

History

Repository files navigation

Genymotion device web renderer

🚀 Engineered for Power

📜 Table of contents

📋 Requirements

📦 Installation

📥 Install via NPM / Yarn

🌐 Install via a CDN

⚡ Quick Start Guide

🎨 Style and CSS

CSS variables available with their default presets:

📘 API Documentation

📡 VM_communication

disconnect

addEventListener

sendData

🛠️ utils

getRegisteredFunctions

🎮 keyMapping

setConfig

activeKeyMappingDebug

enable

🔊 media

mute

unmute

🎥 video

fullscreen

⚙️ Features & Instance options

🖥️ Instance options

token

toolbarOrder

showPhoneBorder

connectionFailedURL

giveFeedbackLink

🔧 Advanced Options

i18n

stun

turn

🔌 Plugin Options

battery

baseband

biometrics

camera

clipboard

capture

diskIO

fileUpload

fileUploadUrl

fullscreen

gamepad

gps

gpsSpeedSupport

identifiers

keyboard

keyboardMapping

microphone

mouse

navbar

network

phone

power

rotation

streamResolution

streamBitrate

volume

wifi

❓ FAQ

How do I get an API key?

Can I use this SDK with on-premise deployments?

🤝 Contributing

About

Topics

Resources

License

Code of conduct

📡 `VM_communication`

`disconnect`

`addEventListener`

`sendData`

🛠️ `utils`

`getRegisteredFunctions`

🎮 `keyMapping`

`setConfig`

`activeKeyMappingDebug`

`enable`

🔊 `media`

`mute`

`unmute`

🎥 `video`

`fullscreen`

`token`

`toolbarOrder`

`showPhoneBorder`

`connectionFailedURL`

`giveFeedbackLink`

`i18n`

`stun`

`turn`

`fileUploadUrl`

`gpsSpeedSupport`

`keyboard`

`microphone`

`mouse`

`wifi`

Packages