Supported Components framework

| Framework | Compatible with Vite-built components? | Additional Notes | |---------------------------|--------------------------------------------|----------------------------------------| | Vite + React | ✅ Native compatibility | Already based on Vite | | Next.js | ✅ Fully compatible | Import as usual | | Remix | ✅ Compatible | No issues | | Gatsby | ✅ Compatible | Use like any React package | | CRA (Create React App)| ✅ Compatible | Import or install as an npm package | | Storybook | ✅ Great for UI testing | Works well | | Electron (React UI) | ✅ Compatible | Used in the renderer process | | React Native | ⚠️ Not directly compatible | Uses a different rendering system (no DOM) |

Installation

  npm i github:devbeta-hcode/viewrp-js
  or 
  npm i viewrp-js

import

import { ViewRP } from "viewrp-js";

require

const { ViewRP } = require("viewrp-js");

controlRef

import { useRef } from "react";
const controlRef = useRef(null);

dataDevice

const dataDevice = {
  device_id: "21408686",
  passwd: "12345"
};

maxWidth This is the maximum width size when in portrait, with landscape everything will automatically fit

const [maxWidth, setMaxWidth] = useState(333);

use

<ViewRP
  api={"https://viewrp.com/api/v1/client/device/connect-control"}
  ref={controlRef} // useRef
  codec={"avc1.42001E"}
  hardwareAcceleration={"prefer-hardware"}
  dataDevice={dataDevice}
  maxWidth={320} // maximum size of width
  showAssistive={true} // show accessibility button
  showDeviceId={true} // display DeviceId
  autoResize={true},
  // onSyncEvent={(data)=>{
  //   console.log(data); // receive event to synchronize operation
  // }}
  // onSyncButton={(device_id)=>{
  //   console.log(device_id);  event click sync button
  // }}
/>

Codec

| Codec String | Meaning (Profile / Level) | When to Use | | -------------------- | --------------------------------------------------- | ------------------------------------------------------------ | | "avc1.42001E" | H.264 Baseline, Level 3.0 | For low-end devices, basic streams, highest compatibility | | "avc1.4D001E" | H.264 Main, Level 3.0 | For general-purpose streaming, good browser/device support | | "avc1.64001E" | H.264 High, Level 3.0 | Higher quality, commonly used with Android MediaCodec |

hardwareAcceleration

| Value | Meaning | When to Use | | --------------------- | ---------------------------------------------------------------------- | -------------------------------------------------- | | "no-preference" | Let the browser decide automatically | Default if you don’t set anything | | "prefer-hardware" ✅ | Prefer hardware acceleration (GPU/SoC), fallback to software if needed | Best for low latency, and avoids crashes | | "prefer-software" | Prefer software decoding, use hardware only if necessary | Rarely used, only when hardware decoding has bugs |

Use the synchronization feature syncEvent and syncButton

• pay attention to 2 events in Components syncEvent and syncButton

• for example create 1 useState to specify which controlRef is the main

const [defaultDeviceId, setDefaultDeviceId] = useState(null);

• onSyncButton when we press the sync button in the accessibility menu like iphone this event will receive the device_id we want to set as defaultControlRef

onSyncButton={(device_id)=>{
  setDefaultDeviceId(device_id); // set this device_id to which controlRef is the main
}}

• for example we have a list of controlRef

const ListControlRef = [controlRef_1, controlRef_2, controlRef_3]; // .... 4,5,6 ....

• onSyncEvent this is the event of operations such as shortcuts, touch gestures, keyboard

onSyncEvent={dataDevice.device_id===defaultDeviceId ? (data)=>{
  ListControlRef.map((item)=>{
    if(item.current.getDeviceId() != defaultDeviceId){ // ignore your own controlRef
      item.current.sync(data);
    }
  }: null)
}}

use with api for automation

declare interface ElementWrapper {
  click({index, retry_time, timeout}:{index?:number, retry_time?:number, timeout?:number}): Promise<void>;
  setText({text, index, retry_time, timeout}:{text:string,index?:number, retry_time?:number, timeout?:number}): Promise<void>;
  all({retry_time, timeout}:{retry_time?:number, timeout?:number}): Promise<any[]>;
}
declare interface DeviceController {
  jsloop(iterations: number, callback: (index: number) => Promise<void>): Promise<void>;
  pause(is_pause: boolean): void;
  deviceId(): {id: string};
  resolution(): { width: number, height: number, orientation: number };
  screenshot(): {base64: string};
  sleep(timeout?: number): Promise<any>;
  toast(text: string, timeout?: number): Promise<any>;
  unlockScreen(timeout?: number): Promise<any>;
  pressHome(timeout?: number): Promise<any>;
  pressBack(timeout?: number): Promise<any>;
  pressSwitch(timeout?: number): Promise<any>;
  getClipboard(timeout?: number): Promise<string>;
  setClipboard(text: string, timeout?: number): Promise<any>;
  appStart(packageName: string, timeout?: number): Promise<any>;
  appStop(packageName: string, timeout?: number): Promise<any>;
  appClear(packageName: string, timeout?: number): Promise<any>;
  appInfo(packageName: string, timeout?: number): Promise<any>;
  click(x: number, y: number, duration?: number, timeout?: number): Promise<any>;
  swipe(start_x: number, start_y: number, end_x: number, end_y: number, duration: number, timeout?: number): Promise<any>;
  keyCode(key: number, meta_state?: number, repeat?: boolean, timeout?: number): Promise<any>;
  keyText(text: string, timeout?: number): Promise<any>;
  setText(text: string, timeout?: number): Promise<any>;
  findElements(strategy: 'resourceId' | 'text' | 'xpath' | 'className', value: string): ElementWrapper;
}

System & Hardware Actions

• unlockScreen(timeout?): Wakes up the device and unlocks the lock screen.
• pressHome(timeout?): Simulates pressing the physical Home button.
• pressBack(timeout?): Simulates pressing the Back button.
• pressSwitch(timeout?): Opens the Recent Apps / App Switcher screen.
• keyCode(key, ...): Sends a specific Android KeyCode (e.g., 66 for Enter, 24 for Volume Up).
• keyText(text): Sends raw keyboard input text.
• setText(text): Sets text directly (usually used for focused fields).
• toast(text): Displays a small popup message on the device screen.
• setClipboard(text) / getClipboard(): Writes to or reads from the device's system clipboard.

Screen & Touch Gestures

• click(x, y, duration?, timeout?): Taps the screen at specific coordinates (x, y).
• swipe(start_x, start_y, end_x, end_y, duration): Performs a swipe gesture from start to end points.
• resolution(): Returns the device's width, height, and orientation.
• screenshot(): Returns the current screen capture as a string.

App Management

• appStart(packageName): Launches an application (e.g., com.android.chrome).
• appStop(packageName): Force-stops a running application (Requires root or system privileges).
• appClear(packageName): Clears all data and cache for the specified app (Requires root or system privileges).
• appInfo(packageName): Retrieves version and package details.

Data & Utilities

• jsloop(iterations, callback): A high-performance loop optimized for ViewRP infrastructure.
• pause(is_pause): Pauses or resumes the execution of the script.
• sleep(timeout?): Pauses the script for a duration (milliseconds).
• deviceId(): Returns the unique ID of the current device.

2. ElementWrapper Interface

Instead of using raw coordinates, ElementWrapper allows you to interact with UI components (buttons, text fields) intelligently.

Finding Elements

Use device.findElements(strategy, value) to target elements.

| Strategy | Description | Example Value | | :--- | :--- | :--- | | resourceId | The unique ID in the app's code. | com.android.settings:id/title | | text | The literal text displayed on screen. | Login | | className | The Android View class type. | android.widget.Button | | xpath | A XML-like path to the element. | //android.widget.LinearLayout[1] |

Available Actions

• click({index, retry_time, timeout}): Clicks the found element. Use index if multiple elements are found (starts at 0).
• setText({text, index, ...}): Inputs text into a text field.
• all({retry_time, timeout}): Returns an array of all elements matching the criteria.

3. Practical Example

Here is a simple script to open a browser and search for a website:

async function searchTask() {
    // 1. Open Chrome
    await device.appStart("com.android.chrome");
    await device.sleep(2000);

    // 2. Find the search bar using its Class Name
    const inputs = device.findElements('className', 'android.widget.EditText');
    
    // 3. Type "ViewRP" into the first input field found
    await inputs.setText({ text: "ViewRP", index: 0 });

    // 4. Press Enter Key
    await device.keyCode(66);
    
    // 5. Notify the user via a Toast
    await device.toast("Search Command Sent!");
}