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.

It focuses on:

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 genymotion website.

Requirements

A Modern, WebRTC compatible, Web browser:

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

Getting started

With 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>

With CDN

<link
    rel="stylesheet"
    href="https://cdn.jsdelivr.net/npm/@genymotion/device-web-player@4.1.5/dist/css/device-renderer.min.css"
/>
<script src="https://cdn.jsdelivr.net/npm/@genymotion/device-web-player@4.1.5/dist/js/device-renderer.min.js"></script>

Usage

Use DeviceRendererFactory to instanciate one or more device renderer. 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>

Player API

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

Disconnects the player from the virtual machine (VM) and cleans up the memory listener.
addEventListener

Registers a listener for messages emitted from the VM.
- Parameters:
  - event (string): The name of the event to listen for. Example events include 'fingerprint', 'gps'...
  - callback (function): The function to call when the event is emitted. The message from the VM will be passed as an argument to the callback function.
- Example Usage
```
addEventListener('fingerprint', (msg) => {
    console.log(msg);
});
```
sendData

Sends messages to the VM.
- Parameters:
  - data (object): An object containing the channel and the messages to be sent.
    - channel (string): The channel to send the messages to.
    - messages (array): An array of messages to be sent.
- Example Usage

sendData({
    channel: 'battery',
    messages: ['set state level 10', 'set state status true'],
});

`utils`

getRegisteredFunctions
Returns a list of available functions with optional descriptions.

`keymapping`

`setConfig`

supply a config for keymapping

{
    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',
            },
            {
                key: 'a',
                effect: {
                    initialX: 20,
                    initialY: 80,
                    distanceX: -10,
                    distanceY: 0,
                },
                name: 'left',
                description: 'move left',
            },
            {
                key: 'd',
                effect: {
                    initialX: 20,
                    initialY: 80,
                    distanceX: 10,
                    distanceY: 0,
                },
                name: 'up',
                description: 'move right',
            },

        ],
        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

helper to create the config mapping
- Parameters:
  - isTraceActivate (boolean) : when true all click on video stream will print x and y coord over the video
  - isGridActivate (boolean): when true display a grid over the video stream. Row and column have both a size of 10%.
enable
- Parameters:
  - isActive (boolean) : Optionnal parameter to activate or desactivate keymapping, default false

`media`

mute
unmute

`video`

fullscreen
Need to be call from an user action, in accordance with browser security rules

Features & options

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

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

`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.
}

`showPhoneBorder`

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

`streamResolution`

Type: Boolean
Default: true
Compatibility: SaaS
Details: Enables or disables the video stream quality widget.

`streamBitrate`

Type: Boolean
Default: false
Compatibility: SaaS
Details: Enables or disables the stream bitrate widget.

`touch`

Type: Boolean
Default: true
Compatibility: PaaS, SaaS
Details: Enables or disables the touch events (fingers on screen). If you want to disable all VM interaction, please also disable mouse and keyboard.

`mouse`

Type: Boolean
Default: true
Compatibility: PaaS, SaaS
Details: Enables or disables the mouse events. If you want to disable all VM interaction, please also disable touch and keyboard.

`keyboard`

Type: Boolean
Default: true
Compatibility: PaaS, SaaS
Details: Enables or disables the keyboard widget. This widget can be used to transmit keyboard key strokes to the Android virtual device.

`keyboardMapping`

Type: Boolean
Default: true
Compatibility: PaaS, SaaS
Details: Enables or disables the keyboardMapping. This widget can be used to map key with command (i.e. tap, swipe-left, tilt, ...).

`volume`

Type: Boolean
Default: true
Compatibility: PaaS, SaaS
Details: Enables or disables the volume widget. This widget can be used to increase or decrease the volume of the Android virtual device.

`rotation`

Type: Boolean
Default: true
Compatibility: PaaS, SaaS
Details: Enables or disables the rotation widget. This widget can be used to rotate the Android virtual device.

`navbar`

Type: Boolean
Default: true
Compatibility: PaaS, SaaS
Details: Enables or disables the navbar widgets. This widget can be used to navigate in the Android virtual device like when using hardware buttons.

`power`

Type: Boolean
Default: true
Compatibility: PaaS, SaaS
Details: Enables or disables the power widget. This widget can be used to poweroff or reboot the Android virtual device.

`fullscreen`

Type: Boolean
Default: true
Compatibility: PaaS, SaaS
Details: Enables or disables the fullscreen widget. This widget can be used to make the renderer go fullscreen.

`camera`

Type: Boolean
Default: true
Compatibility: PaaS, SaaS
Details: Enables or disables 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.

`microphone`

Type: Boolean
Default: false
Compatibility: PaaS
Details: Enables or disables microphone injection. This can be used to forward local microphone (or webcam audio) to the Android virtual device.

`fileUpload`

Type: Boolean
Default: true
Compatibility: PaaS, SaaS
Details: Enables or disables the fileUpload widget and drag & drop. This widget can be used to forward local file to the Android virtual device. When drag & 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.

`clipboard`

Type: Boolean
Default: true
Compatibility: PaaS, SaaS
Details: Enables or disables the clipboard widget. This widget can be used to forward local clipboard to the Android virtual device.

`battery`

Type: Boolean
Default: true
Compatibility: PaaS, SaaS
Details: Enables or disables the battery widget. This widget can be used to set the battery level and state of the Android virtual device.

`gps`

Type: Boolean
Default: true
Compatibility: PaaS, SaaS
Details: Enables or disables 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 number to set the location, you must import 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: Enables or disables gps speed support.

`capture`

Type: Boolean
Default: true
Compatibility: PaaS, SaaS
Details: Enables or disables the capture widget. This widget can be used to capture the screen of the Android virtual device (screenshot or screencast).

`identifiers`

Type: Boolean
Default: true
Compatibility: PaaS, SaaS
Details:

Enables or disables the identifiers widget. This widget can be used to set the identifiers (Android ID / IMEI) of the Android virtual device.

`network`

Type: Boolean
Default: true
Compatibility: PaaS, SaaS
Details: Enables or disables the network widget. This widget can be used to enable or disable the wifi or mobile network, and to set the network throttling (mobile network type and signal strength) of the Android virtual device.

`phone`

Type: Boolean
Default: true
Compatibility: PaaS, SaaS
Details:

Enables or disables the phone widget. This widget can be used to send SMS or phone call the Android virtual device.

`baseband`

Type: Boolean
Default: false
Compatibility: PaaS, SaaS
Details: Enable or disable baseband (MMC/MNC) widget.

`diskIO`

Type: Boolean
Default: true
Compatibility: PaaS, SaaS
Details: Enables or disables the diskIO widget. This widget can be used to modify Disk IO (throttling) of the Android virtual device.

`gamepad`

Type: Boolean
Default: true
Compatibility: SaaS, PaaS
Details: Enable or disable gamepad support & widget

`biometrics`

Type: Boolean
Default: true
Compatibility: SaaS, PaaS
Details: Enable or disable fingerprints widget. This widget can be used to manage fingerprint reading requests. Available for Android 9 and above

`connectionFailedURL`

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

`giveFeedbackLink`

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

Contributing

Read through our contributing guidelines to learn about our submission process, coding rules and more.

Files

README.md

Latest commit

History

README.md

File metadata and controls

Genymotion device web renderer

Table of contents

Requirements

Getting started

With NPM/Yarn

With CDN

Usage

Player API

VM_communication

disconnect

addEventListener

sendData

utils

getRegisteredFunctions

keymapping

setConfig

activeKeyMappingDebug

enable

media

mute

unmute

video

fullscreen

Features & options

token

i18n

stun

turn

showPhoneBorder

streamResolution

streamBitrate

touch

mouse

keyboard

keyboardMapping

volume

rotation

navbar

power

fullscreen

camera

microphone

fileUpload

fileUploadUrl

clipboard

battery

gps

gpsSpeedSupport

capture

identifiers

network

phone

baseband

diskIO

gamepad

biometrics

connectionFailedURL

giveFeedbackLink

Contributing

`VM_communication`

`disconnect`

`addEventListener`

`sendData`

`utils`

`getRegisteredFunctions`

`keymapping`

`setConfig`

`activeKeyMappingDebug`

`enable`

`media`

`mute`

`unmute`

`video`

`fullscreen`

`token`

`i18n`

`stun`

`turn`

`showPhoneBorder`

`streamResolution`

`streamBitrate`

`touch`

`mouse`

`keyboard`

`keyboardMapping`

`volume`

`rotation`

`navbar`

`power`

`fullscreen`

`camera`

`microphone`

`fileUpload`

`fileUploadUrl`

`clipboard`

`battery`

`gps`

`gpsSpeedSupport`

`capture`

`identifiers`

`network`

`phone`

`baseband`

`diskIO`

`gamepad`

`biometrics`

`connectionFailedURL`

`giveFeedbackLink`