接口说明 | ARMCLOUD 文档中心

API接口说明

本文档描述了云手机 Web H5 SDK 提供的接口。

初始化

const engine = new ArmcloudEngine(params)

1.顶层参数（直接从 params 中获取）

参数路径	值类型	是否必填	说明	默认值或处理逻辑
`params.token`	string	是	服务端返回的 Token，用于身份验证或换取 RTC 信息	—
`params.baseUrl`	string	是	SDK 接口请求的域名	—
`params.enableMicrophone`	boolean	否	控制是否启用麦克风	若未传则默认为 `true`
`params.enableCamera`	boolean	否	控制是否启用摄像头	若未传则默认为 `true`
`params.masterIdPrefix`	string	否	群控中主控设备 ID 的前缀	若未传则默认为空字符串 `""`

2.设备信息参数（来自 params.deviceInfo）

参数路径	值类型	是否必填	说明	默认值或处理逻辑
`params.deviceInfo.padCode`	string	是	房间号或实例编号，用于标识云手机实例	—
`params.deviceInfo.userId`	string	是	用户 ID，用于标识操作用户	—
`params.deviceInfo.autoRecoveryTime`	number	否	无操作回收时间（秒），设为 0 表示禁用此功能	若未传则默认为 `300`
`params.deviceInfo.mediaType`	number	否	媒体流类型：1（仅音频）、2（仅视频）、3（音视频同时）	若未传则默认为 `2`
`params.deviceInfo.rotateType`	number	否	屏幕方向：0 表示竖屏，1 表示横屏；不传入则自动判断	默认根据云机内部横竖屏状态自动旋转
`params.deviceInfo.keyboard`	string	否	键盘模式：`"local"` 表示使用本机键盘，`"pad"` 表示使用云机键盘	若未传则默认为 `"pad"`
`params.deviceInfo.saveCloudClipboard`	boolean	否	是否启用云机剪切板回调功能	若未传则默认为 `true`
`params.deviceInfo.allowLocalIMEInCloud`	boolean	否	云机键盘时能否使用本地输入法	若未传则默认为 `false`
`params.deviceInfo.disableContextMenu`	boolean	否	是否禁用右键菜单	若未传则默认为 `false`
`params.deviceInfo.videoDeviceId`	string	否	指定摄像头（deviceId）	若未传则自动选择
`params.deviceInfo.audioDeviceId`	string	否	指定麦克风（deviceId）	若未传则自动选择

3. 视频流信息参数（来自 params.deviceInfo.videoStream）

参数路径	值类型	是否必填	说明	默认值或处理逻辑
`params.deviceInfo.videoStream.resolution`	number	否	视频流分辨率	若未传则默认为 `12`
`params.deviceInfo.videoStream.frameRate`	number	否	视频流帧率	若未传则默认为 `2`
`params.deviceInfo.videoStream.bitrate`	number	否	视频流码率	若未传则默认为 `3`

3.1 视频质量预设配置

质量等级	分辨率	帧率	码率
流畅	9	8	15
标清	10	8	15
高清	12	8	1
超清	15	1	3

注：详细的配置参数请参阅设置分辨率、码率、帧率部分，其中对 definitionConfig 参数做了详细说明。

云机操控接口

方法名	方法描述
isSupported	浏览器是否支持RTC服务
start	加入房间
stop	离开房间
setStreamConfig	设置分辨率，码率，帧率
setKeyboardStyle	切换本地/云机输入法类型
resumeAllSubscribedStream	恢复推流
pauseAllSubscribedStream	暂停推流
sendCommand	发送按键指令
muted	静音
unmuted	取消静音
setMicrophone	是否开启麦克风
setCamera	是否开启摄像头
setVideoDeviceId	指定摄像头
setAudioDeviceId	指定麦克风
increaseVolume	云机音量增加
decreaseVolume	云机音量减少
sendInputString	将字符串发送到云手机的输入框中
sendInputClipper	将字符串发送到云手机的粘贴板中
saveCloudClipboard	是否接收云机粘贴板内容回调
sendShake	发送摇一摇指令
setGPS	自定义GPS信息
setAutoRecycleTime	设置无操作回收时间
getAutoRecycleTime	获取无操作回收时间
setPhoneRotation	设置横竖屏播放
executeAdbCommand	执行ADB命令
joinGroupRoom	群控加入房间
kickItOutRoom	踢出群控房间
injectVideoStream	视频注入相机（启动和停止注入）
saveScreenShotToLocal	截图保存到本地
triggerPointerEvent	模拟触摸
triggerClickEvent	模拟点击
stopMediaStream	停止摄像头注入

API详情

浏览器是否支持

方法：

engine.isSupported()

类型：

() => Promise<boolean>
// true: 支持，false: 不支持

代码示例：

// 浏览器是否支持 RTC 服务监听
const isSupported = await armCloud.value.isSupported();
if (!isSupported) {
  showNotify({
    type: "warning",
    message: "该浏览器不支持 RTC 服务"
  });
  return false;
}

加入房间

参数：

isGroupControl (boolean)
是否开启群控，默认值：false
pads (Array)
需要被群控的实例编号，默认值：[]

方法：

engine.start(isGroupControl, pads)

离开房间

方法：

engine.stop()

注意： stop() 方法会销毁引擎及过程中所创建的 DOM 节点。如果有切换云机需求，需在每次 new ArmcloudEngine() 之前先调用 stop()。 注意： stop() stop() 返回一个 Promise，你可以通过 await 或 .then() 来监听操作的成功与失败。

代码示例：

 try {
    await engine.stop(); 
    console.log("Engine stopped successfully.");
  } catch (error) {
    console.error("Failed to stop engine:", error);
  }

切换本地/云机输入法类型

方法：

engine.setKeyboardStyle(keyboard: string)

参数：

keyboard (string)
输入法类型：
- local: 本地输入法
- pad: 云机虚拟输入法

代码示例：

engine.setKeyboardStyle('pad');

设置分辨率、码率、帧率

方法：

engine.setStreamConfig(definitionConfig: CustomDefinition)

参数：

definitionConfig (object)
配置对象，包含以下字段：

字段名	描述
definitionId	分辨率： 7：144×256； 8：216×384； 9：288×512； 10：360×640； 11：480×848； 12：540×960； 13：600×1024； 14：480×1280； 15：720×1280； 16：720×1920； 17：1080×1920； 18：1440×1920； 19：1600×2560； 20：2880×1080
framerateId	帧率： 1：20fps； 2：25fps； 3：30fps； 4：60fps； 5：1fps； 6：5fps； 7：10fps； 8：15fps； 9：2fps
bitrateId	码率： 1：1Mbps； 2：1.5Mbps； 3：2Mbps； 4：2.5Mbps； 5：3Mbps； 6：3.5Mbps； 7：4Mbps； 8：5Mbps； 9：6Mbps； 10：8Mbps； 11：10Mbps； 12：12Mbps； 13：200kbps； 14：400kbps； 15：600kbps

代码示例：

const definitionConfig = ref({
  definitionId: 12,
  framerateId: 2,
  bitrateId: 3
});
engine.setStreamConfig(definitionConfig.value);

恢复推流

方法：

engine.resumeAllSubscribedStream(mediaType: number)

参数：

mediaType (number)
媒体类型：
- 1: 恢复音频拉流
- 2: 恢复视频拉流
- 3: 恢复音视频拉流

代码示例：

// 恢复音频拉流
engine.resumeAllSubscribedStream(1);

暂停推流

方法：

engine.pauseAllSubscribedStream(mediaType: number)

参数：

mediaType (number)
媒体类型：
- 1: 暂停音频拉流
- 2: 暂停视频拉流
- 3: 暂停音视频拉流

代码示例：

// 暂停音频拉流
engine.pauseAllSubscribedStream(1);

截图保存到本地

方法：

engine.saveScreenShotToLocal()

返回值：

类型： Promise<ImageData>

代码示例：

engine.saveScreenShotToLocal().then(res => {
  const imageData = res;
  // 创建 canvas 元素
  const canvas = document.createElement("canvas");
  canvas.width = imageData.width;
  canvas.height = imageData.height;
  const ctx = canvas.getContext("2d");

  // 将图像数据绘制到 canvas 上
  ctx.putImageData(imageData, 0, 0);
  // 将 Canvas 转换为图片并保存到本地
  const link = document.createElement("a");
  link.href = canvas.toDataURL(); // 使用 toDataURL() 将 canvas 转换为 base64 编码图片 URL
  link.download = "image.png";     // 设置下载文件名
  document.body.appendChild(link);
  link.click();
  document.body.removeChild(link);
});

截图保存到云机

方法：

engine.saveScreenShotToRemote()

代码示例：

engine.saveScreenShotToRemote();

设置横竖屏播放

方法：

engine.setPhoneRotation(type: number)

参数：

type (number)
屏幕方向：
- 0: 竖屏
- 1: 横屏

代码示例：

// 设置横屏
engine.setPhoneRotation(1);

自定义GPS信息

方法：

engine.setGPS(longitude: number, latitude: number)

参数：

longitude (number) – 经度
latitude (number) – 纬度

代码示例：

// 设置经纬度坐标
engine.setGPS(113, 28);

设置无操作回收时间

方法：

engine.setAutoRecycleTime(second: number)

参数：

second (number)
无操作回收时间，默认 300 秒，范围：0s ~ 7200s
0 禁用操作回收功能

代码示例：

engine.setAutoRecycleTime(300);

获取无操作回收时间

方法：

engine.getAutoRecycleTime()

返回值：

类型： Promise<number>

代码示例：

engine.getAutoRecycleTime().then(time => {
  console.log(time);
});

发送按键指令

方法：

engine.sendCommand(command: string)

参数：

command (string)
按键指令：
- back: 返回键
- home: Home 键
- menu: 菜单键

代码示例：

// 发送 Home 键指令
engine.sendCommand("home");

静音

方法：

engine.muted()

代码示例：

engine.muted();

取消静音

方法：

engine.unmuted()

代码示例：

engine.unmuted();

云机音量增加

方法：

engine.increaseVolume()

代码示例：

engine.increaseVolume();

云机音量减少

方法：

engine.decreaseVolume()

代码示例：

engine.decreaseVolume();

将字符串发送到云手机的粘贴板中

方法：

engine.sendInputClipper(text: string)

代码示例：

// 该操作只会将内容发送到云机粘贴板中，使用时请在云机输入框中长按粘贴
const text = 'hello world';
engine.sendInputClipper(text);

将字符串发送到云手机的输入框中

方法：

engine.sendInputString(text: string)

代码示例：

// 该操作在云机输入框聚焦时自动将内容发送到输入框，无需长按粘贴
const text = 'hello world';
engine.sendInputString(text);

// 注意：此操作仅将文本发送至输入框，不会更新云机剪切板内容，如有需要请手动调用 engine.sendInputClipper(text)

是否接收云机粘贴板内容回调

方法：

engine.saveCloudClipboard(flag: boolean)

参数：

flag (boolean)
是否接收云机粘贴板内容回调：
- true: 接收
- false: 不接收

代码示例：

const flag = true;
engine.saveCloudClipboard(flag);

发送摇一摇指令

方法：

engine.sendShake(time: number)

参数：

time (number)
持续时间（毫秒），默认值：1500
时间过长可能导致多次截屏

代码示例：

engine.sendShake(1500);

是否开启麦克风

方法：

engine.setMicrophone(enable: boolean)

参数：

enable (boolean)
是否开启麦克风，默认值：true

代码示例：

engine.setMicrophone(true);

是否开启摄像头

方法：

engine.setCamera(enable: boolean)

参数：

enable (boolean)
是否开启摄像头，默认值：true

代码示例：

engine.setCamera(true);

指定摄像头

方法：

engine.setVideoDeviceId(deviceId: string)

参数：

deviceId (string)
设备Id

代码示例：

engine.setVideoDeviceId('ab484e060c5f1186004457c5be97e874e976983ebf66e1227e4e925523fc4f11');

注：设置为空则会变成自动选择

指定麦克风

方法：

engine.setAudioDeviceId(deviceId: string)

参数：

deviceId (string)
设备Id

代码示例：

engine.setAudioDeviceId('ab484e060c5f1186004457c5be97e874e976983ebf66e1227e4e925523fc4f11');

注：设置为空则会变成自动选择

执行ADB命令

方法：

engine.executeAdbCommand(command: string)

参数：

command (string) – ADB 命令字符串

代码示例：

engine.executeAdbCommand('cd /;ls');

群控加入房间

方法：

engine.joinGroupRoom(pads)

参数：

pads (Array) – 实例编号列表

代码示例：

engine.joinGroupRoom(['ACXXXX', 'ACXXXX']);

踢出群控房间

方法：

engine.kickItOutRoom(pads)

参数：

pads (Array) – 实例编号列表

代码示例：

engine.kickItOutRoom(['ACXXXX', 'ACXXXX']);

视频注入相机（启动和停止注入）

方法：

engine.injectVideoStream(type, options)

参数：

type (String)：操作类型，可选值为：
- startVideoInjection - 开启视频注入，将外部视频源注入到应用中。
- stopVideoInjection - 停止视频注入，中断当前的视频流注入。
options (Object)：配置注入视频的选项，仅在 type 为 startVideoInjection 时使用。包含以下字段：
- fileUrl (String) - 必填。云机内目录和URL地址，从该地址加载视频进行注入。
- isLoop (Boolean) - 可选。是否循环播放视频。如果设置为 true，视频在播放结束后将重新开始播放，默认：true
- fileName (String) - 视频文件的名称 URL地址必填云机目录非必填

注：fileUrl 可以是云机内目录和第三方地址（http或https）注：视频能解码的格式视频H265，H264，分辨率需要是2的倍数

代码示例：

// 开启并注入视频
engine.injectVideoStream('startVideoInjection', {
    fileUrl: 'http://example.com/video.mp4',
    isLoop: true,
    fileName: 'video.mp4' // URL地址 必填
});

// 从云机内目录获取视频
engine.injectVideoStream('startVideoInjection', {
    fileUrl: '/sdcard/Downloads/video.mp4',
    isLoop: true
});

// 停止视频注入
engine.injectVideoStream('stopVideoInjection');

说明：

使用 startVideoInjection 时，必须提供 fileUrl 来指定需要注入的视频文件地址。可以选择设置 isLoop 和 fileName 以配置视频播放行为和标识。
使用 stopVideoInjection 时，options 参数将被忽略。

模拟点击

方法：

engine.triggerClickEvent(options)

参数：

options (Object)：配置：
- x (Number) - 必填。点击的x坐标。
- y (Number) - 必填。点击的y坐标。
- width (Number) - 必填。容器宽度
- height (Number) - 必填。容器高度

注：x和y 是基于容器大小计算的位置。

代码示例：

engine.triggerClickEvent({
  x:430,
  y: 1383,
  width: 871,
  height: 1550
});

模拟触摸

方法：

engine.triggerPointerEvent(action, options)

参数：

action (Number)：操作类型，可选值为：
- 0 - 按下。
- 1 - 抬起。
- 2 - 触摸中。
options (Object)：配置：
- x (Number) - 必填。触摸的x坐标。
- y (Number) - 必填。触摸的y坐标。
- width (Number) - 必填。触摸容器宽度
- height (Number) - 必填。触摸容器高度

注：x和y 是基于容器大小计算的位置。

代码示例：

// 模拟移动效果
engine.triggerPointerEvent(0, {
    width: 871,
    height: 1550,
    x: 92,
    y:1325
})
engine.triggerPointerEvent(2, {
    width: 871,
    height: 1550,
    x: 92,
    y: 1325
})
engine.triggerPointerEvent(2, {
    width: 871,
    height: 1550,
    x: 92,
    y: 1326
})

setTimeout(() => {
  engine.triggerPointerEvent(1, {
      width: 871,
      height: 1550,
      x: 92,
      y:1325
  }) 
}, 1)

注：根据时机情况看是否使用定时器。

停止摄像头注入

方法：

engine.stopMediaStream(mediaType: number)

参数：

mediaType (Number)：可选值为：
- 1 - 麦克风。
- 2 - 摄像头。
- 3 - 摄像头和麦克风。

代码示例：

engine.stopMediaStream(3)

注：只有摄像头或者麦克风注入才有效