华为云云手机服务KooPhone对接使用完全指南
一、KooPhone云手机服务概述
1.1 什么是KooPhone
云手机服务(KooPhone)是华为云面向政企、互联网等客户推出的一款优体验、高安全的云手机服务,融合了ARM服务器虚拟化、音视频编解码、实时传输能力等核心技术,并引入华为丰富的应用生态,为更多带屏联网设备提供云算力和云应用的能力。KooPhone充分发挥端云协同的优势,提供端云交互、麦克风和摄像头等各类传感器的模拟仿真,以及应用和数据权限云端统一管控等多种功能特性。
KooPhone可以便捷安全地应用于移动办公、客服同屏互助、个人/家庭娱乐等多种场景。在移动安全办公场景中,KooPhone提供全链路(云-管-端)、多维度(云机-网络-应用-数据)的安全防控和管理维护能力。端侧构建防截屏、防录屏、实时加水印等特性防控信息外泄;云侧进行应用黑白名单管理、权限管控,用户数据加密存储、多副本备份,配合云机监控和安全审计,保障云端安全。在客服与营销场景中,KooPhone提供同屏分享、可视化沟通和远程指导能力,业务数据云端留存,操作记录可保存,用户行为可追溯。
1.2 核心技术优势
KooPhone具备四大核心优势。第一是极致体验,独家自研端云协议和编解码算法提供1080P超高清视频画质,云-管-端协同处理时延在百毫秒以内,用户操控无感知。第二是多端协同,突破屏幕限制,支持多终端(手机、PC等)和多系统(Android、iOS等)通过App或H5方式随时随地访问云手机。第三是安全可靠,数据云端存储不落地,基于华为云企业级安全防护能力提供全链路管控策略。第四是丰富生态,提供GPS、摄像头、陀螺仪等10多种真机设备仿真,兼容业界主流游戏与应用,开放API和SDK支持企业二次开发。
1.3 KooPhone与CPH的差异
理解KooPhone需要先了解其与云手机服务器(CPH)的关系。云手机服务器(Cloud Phone Host,简称CPH)是基于鲲鹏裸金属服务器在服务器上虚拟出N个带有原生安卓操作系统的云手机,简单来说就是云服务器加Android操作系统。用户可以远程实时控制云手机,实现安卓APP的云端运行。
而KooPhone是在CPH的基础上提供了上层复杂的软件系统,更偏向于用户体验的提升。KooPhone通过端云协同引擎、计算资源管理、用户账号鉴权认证、手机UI界面优化等一系列技术叠加,在CPH的基础上向用户提供了一个远程手机操作环境。简而言之,CPH提供的是底层的云手机算力资源,而KooPhone则是在此之上构建了完整的云手机服务体验。
二、购买与开通KooPhone服务
2.1 准备工作
使用KooPhone之前需要完成以下准备工作:注册华为账号并开通华为云,完成企业账号实名认证。完成这些前置条件后,即可进入KooPhone管理控制台进行操作。
需要先登录华为云控制台,点击:华为云控制台,还没有账号,点击:注册并关联,已有账号点击:登录后关联
2.2 购买云手机实例
登录云手机服务管理控制台,进入云手机服务总览页面,单击页面的"立即购买"跳转至购买页面。购买时需要配置以下关键参数:
- 计费方式:支持包年/包月和按需两种计费模式
- 区域:选择最靠近业务所在的区域以减少网络时延
- 实例规格:不同版本提供不同规格类型,如专业版配置4vCPUs、8GB内存、64GB存储
- 镜像:选择实例运行的操作系统,目前支持Android系统(AOSP 9或AOSP 11)
- 网络:支持选择EIP或ADN线路
- 带宽大小:根据实例规格配套不同带宽,如专业版配套2Mbps带宽
- 购买数量:1到1500个实例
配置完成后阅读并勾选同意协议,确认无误后单击"去支付"并根据页面提示完成支付。
2.3 创建组织和用户
首次购买通用云终端后,管理员需要创建组织。创建完成后,该华为账号会自动成为组织创建者即租户管理员,拥有该组织的所有管理权限。一个账号最多可以创建五个组织。在"组织和用户管理"页面可以管理组织架构并为用户分配云手机实例。
三、控制台管理与操作
3.1 云手机实例管理
通过KooPhone管理控制台可以对云手机实例进行全方位的管理操作:
- 实例生命周期管理:支持云手机实例的关机、开机、重启、删除等操作
- 用户管理:支持实例的绑定用户和解绑用户操作
- 应用管理:支持应用的安装和卸载
- 状态查询:支持查询实例的运行状态、登录状态、绑定状态和到期时间
在"云手机实例管理"页面可以查看所有实例的列表,并对单个或批量实例进行操作。重启云手机实例时需要注意,运行状态为"运行中"的实例才可以执行重启操作。
3.2 自定义镜像管理
KooPhone提供了自定义镜像功能,用户可以通过控制台创建和管理自定义镜像。登录云手机服务管理控制台,单击左侧导航栏的"自定义镜像"进入自定义镜像页面。单击"创建镜像",在系统配置中配置镜像名称和操作系统,配置完成后单击"下一步"完成创建。
创建成功后,自定义镜像页面会展示镜像的名称、镜像ID、设备类型、系统类型、镜像描述等信息。每个账号最多允许创建10个自定义镜像。在购买云手机实例时,可以选择系统镜像或自定义镜像。
四、OpenAPI接口对接
4.1 API概览
KooPhone提供了一套完整的OpenAPI接口,开发者可以通过API对云手机服务进行相关操作,如实例管理、视频设置、批量重置等。调用API之前需要确保已经充分了解云手机服务的相关概念。
KooPhone API涵盖以下主要类型:
- 实例管理:实例创建、查询、重启、重置、分配用户、取消分配等
- ADB命令执行:同步执行和异步执行adb shell命令
- 视频设置:设置实例的码率和帧率
- 应用管理:批量安装应用、查询已安装应用列表
- 串流管理:实例准备、停止串流、释放会话
- 数据备份:实例数据批量备份到OBS
4.2 认证鉴权
调用KooPhone API需要使用IAM服务获取Token进行认证鉴权。账号具备所有API的调用权限,如果使用账号下的IAM用户调用API,该IAM用户需具备调用API所需的权限。可以通过IAM控制台创建用户组并授予云手机服务只读权限"KooPhone ReadOnlyUser"或所有操作权限的角色"KooPhone Administrator"。
4.3 实例开通接口(CreateInstance)
租户可以通过调用CreateInstance接口生成实例。该接口需要结合BatchShowSku接口一起使用,在BatchShowSku接口中获取全量的可售SKU,租户根据自己需要选择相应规格进行订购。
接口的URI为POST /v1/instances/create。关键请求参数包括:
- os:创建实例的镜像规格,如AOSP9或AOSP11
- instanceSkuId:实例商品规格ID
- bandSkuId:带宽商品规格ID
- regionId:区域ID
- instanceNamePrefix:实例名称前缀,最大14个字符
- bandSize:带宽大小(单位M)
- count:购买实例数量,最大1500个
- chargeParam:计费相关参数
调用接口时如果想要直接购买成功,需要在账户上充值并在订购参数中选择isAutoPay为自动付费。如果没有选择自动付费,调用接口后需要拿对应的订单号在待支付订单中手动付费。
以下是使用Python调用CreateInstance接口的示例代码:
import requests
import json
def create_koophone_instance(token, region_id, instance_sku_id, band_sku_id, os_version, count=1):
url = "https://koophone.region_id.myhuaweicloud.com/v1/instances/create"
headers = {
"X-Auth-Token": token,
"Content-Type": "application/json"
}
payload = {
"os": os_version, # AOSP9 或 AOSP11
"instanceSkuId": instance_sku_id,
"bandSkuId": band_sku_id,
"regionId": region_id,
"instanceNamePrefix": "my-koophone",
"bandSize": 2.0,
"count": count,
"chargeParam": {
"chargeMode": "prePaid",
"periodType": "month",
"periodNum": 1,
"isAutoPay": True
}
}
response = requests.post(url, headers=headers, json=payload)
return response.json()
# 使用示例(需要替换为实际的token和参数)
# result = create_koophone_instance(token, "cn-north-4", "sku_001", "band_001", "AOSP11", 1)
# print(result)
4.4 实例查询接口(ListInstances)
通过ListInstances接口可以批量查询租户下所有实例信息。调用此API的前提是租户需要先购买实例。接口返回租户下所有实例的详细信息,包括实例ID、状态、规格、创建时间等。
以下是实例查询的Python示例:
def list_koophone_instances(token, region_id):
url = f"https://koophone.{region_id}.myhuaweicloud.com/v1/instances"
headers = {
"X-Auth-Token": token,
"Content-Type": "application/json"
}
response = requests.get(url, headers=headers)
return response.json()
# 使用示例
# instances = list_koophone_instances(token, "cn-north-4")
# for instance in instances.get("data", []):
# print(f"实例ID: {instance['instanceId']}, 状态: {instance['status']}")
4.5 实例重启接口(BatchRebootInstance)
通过BatchRebootInstance接口可以批量重启云机实例。调用此API的前提是租户需要先购买实例。
Python示例:
def reboot_koophone_instances(token, region_id, instance_ids):
url = f"https://koophone.{region_id}.myhuaweicloud.com/v1/instances/reboot"
headers = {
"X-Auth-Token": token,
"Content-Type": "application/json"
}
payload = {
"instanceIds": instance_ids
}
response = requests.post(url, headers=headers, json=payload)
return response.json()
# 使用示例
# result = reboot_koophone_instances(token, "cn-north-4", ["instance_id_1", "instance_id_2"])
4.6 实例重置接口(BatchReset)
通过BatchReset接口可以批量重置云机实例,调用该接口后实例会被初始化。此操作会清除实例中的所有数据,需要谨慎使用。
4.7 实例执行ADB命令接口
KooPhone提供了在云手机实例中执行adb shell命令的API接口。支持同步命令和异步命令两种方式。
同步命令(SyncCommand):通过该接口可以指定云机实例同步执行adb shell命令。该接口是同步操作接口,如果有耗时adb操作建议使用异步命令接口。
异步命令(AsyncCommand):通过该接口可以指定云机实例异步执行adb shell命令。执行异步命令后,需要通过实例执行任务查询接口(GetTask)获取执行结果。
同步执行ADB命令的Python示例:
def sync_adb_command(token, region_id, instance_id, command):
url = f"https://koophone.{region_id}.myhuaweicloud.com/v1/instances/{instance_id}/sync-command"
headers = {
"X-Auth-Token": token,
"Content-Type": "application/json"
}
payload = {
"command": command
}
response = requests.post(url, headers=headers, json=payload)
return response.json()
# 使用示例:在云手机中安装APK
# result = sync_adb_command(token, "cn-north-4", "instance_001", "pm install /data/local/tmp/app.apk")
4.8 实例串流准备接口(BatchPrepareInstances)
通过BatchPrepareInstances接口可以将实例准备到可以串流的状态。调用此API的前提是租户需要先购买实例。通过循环调用此接口直到云机状态为正常,即可开启串流。
五、端侧SDK集成开发
5.1 SDK概述
KooPhone提供了完整的端侧SDK,支持多种平台和开发方式。Android SDK以AAR包形式提供,适用于原生Android应用集成。JavaScript SDK(H5 SDK)以JavaScript包形式提供,适用于Web应用和混合开发场景。
通过标准化的SDK架构,KooPhone SDK提供端云交互、传感器仿真(如麦克风、摄像头)、应用与数据云端统一管控等核心功能。基于可扩展的设计理念,SDK可以实现对云手机、云车机、云机顶盒、云AI等多业务场景的无缝适配。
5.2 Android SDK集成开发
Android SDK的集成开发流程包括以下步骤:
- 准备工作:准备开发Android客户端的环境和工具
- 创建工程:创建Android客户端工程并按快速开始指导集成所需的SDK
- 获取鉴权信息:通过身份认证获取串流前鉴权信息
- 开发Demo及启动串流:实现客户端基础功能并启动串流
在MainActivity的onCreate()中初始化SDK和UI,创建并绑定PlayerFragment作为画面容器。连接云手机后,后台会执行以下操作:
- 调用IAM服务获取Token
- 使用Token获取云手机连接信息
- 构建串流参数Bundle
- 调用SDK的start()方法启动串流
- 隐藏遮罩层,显示云手机画面
Android SDK集成核心代码示例:
// MainActivity.java - SDK初始化与串流启动
public class MainActivity extends AppCompatActivity {
private KooPhoneSDK koophoneSDK;
private PlayerFragment playerFragment;
private TextView connectionStatus;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
// 初始化SDK
initCloudPhoneSDK();
// 初始化UI
initUI();
}
private void initCloudPhoneSDK() {
// 创建SDK实例
koophoneSDK = new KooPhoneSDK(this);
// 设置SDK配置
SDKConfig config = new SDKConfig.Builder()
.setDeviceId(deviceId)
.setDeviceToken(deviceToken)
.setSignalingUrl(signalingUrl)
.build();
koophoneSDK.init(config);
}
private void initUI() {
// 创建并绑定PlayerFragment作为画面容器
playerFragment = new PlayerFragment();
getSupportFragmentManager()
.beginTransaction()
.add(R.id.player_container, playerFragment)
.commit();
connectionStatus = findViewById(R.id.tv_connection_status);
}
private void connectCloudPhone() {
// 构建串流参数Bundle
Bundle streamParams = new Bundle();
streamParams.putString("deviceId", deviceId);
streamParams.putString("deviceToken", deviceToken);
streamParams.putString("signalingUrl", signalingUrl);
// 调用SDK的start()方法启动串流
koophoneSDK.start(streamParams, new StreamCallback() {
@Override
public void onSuccess() {
// 隐藏遮罩层,显示云手机画面
connectionStatus.setText("已连接");
hideOverlay();
}
@Override
public void onError(int errorCode, String errorMsg) {
Toast.makeText(MainActivity.this,
"连接失败: " + errorMsg, Toast.LENGTH_SHORT).show();
}
});
}
private void disconnectCloudPhone() {
// 调用SDK的stop()方法停止串流
koophoneSDK.stop(new StopCallback() {
@Override
public void onSuccess() {
// 显示遮罩层,更新连接状态
connectionStatus.setText("已断开");
showOverlay();
}
});
}
}
5.3 JavaScript SDK集成开发
JavaScript SDK让开发者可以在HTML页面中快速集成KooPhone的基线能力。集成步骤如下:
- 创建新工程,选择JavaScript语言
- 下载KooPhone JS SDK包并解压缩,得到kp-client-xx.js
- 在工程根目录创建js文件夹,将kp-client-xx.js复制到该文件夹
JavaScript SDK集成核心代码示例:
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>KooPhone Web客户端</title>
<script src="js/kp-client-xx.js"></script>
<style>
#player-container {
width: 100%;
max-width: 400px;
height: 800px;
margin: 0 auto;
background: #1a1a1a;
}
.controls {
text-align: center;
margin-top: 20px;
}
button {
padding: 10px 30px;
margin: 0 10px;
font-size: 16px;
border: none;
border-radius: 5px;
cursor: pointer;
}
.btn-connect { background: #4CAF50; color: white; }
.btn-disconnect { background: #f44336; color: white; }
#status { text-align: center; margin-top: 10px; font-size: 14px; }
</style>
</head>
<body>
<div id="player-container"></div>
<div class="controls">
<button class="btn-connect" onclick="connectPhone()">连接云手机</button>
<button class="btn-disconnect" onclick="disconnectPhone()">断开连接</button>
</div>
<div id="status">状态:未连接</div>
<script>
let kpClient = null;
const deviceId = "your_device_id";
const deviceToken = "your_device_token";
const signalingUrl = "your_signaling_url";
// 初始化SDK
function initSDK() {
kpClient = new KooPhoneClient({
container: 'player-container',
onReady: function() {
console.log('SDK初始化完成');
updateStatus('SDK就绪');
},
onError: function(error) {
console.error('SDK错误:', error);
updateStatus('错误: ' + error.message);
}
});
}
// 连接云手机
function connectPhone() {
if (!kpClient) {
alert('请先初始化SDK');
return;
}
updateStatus('正在连接...');
// 获取鉴权信息(实际需要从服务端获取)
const authInfo = {
deviceId: deviceId,
deviceToken: deviceToken,
signalingUrl: signalingUrl
};
kpClient.connect(authInfo, {
onConnected: function() {
updateStatus('已连接');
console.log('云手机连接成功');
},
onDisconnected: function() {
updateStatus('已断开');
console.log('云手机已断开');
},
onError: function(error) {
updateStatus('连接失败: ' + error.message);
console.error('连接错误:', error);
}
});
}
// 断开云手机
function disconnectPhone() {
if (kpClient) {
kpClient.disconnect();
updateStatus('已断开');
}
}
function updateStatus(msg) {
document.getElementById('status').textContent = '状态:' + msg;
}
// 页面加载完成后初始化
window.onload = function() {
initSDK();
};
</script>
</body>
</html>
5.4 获取鉴权信息
连接并使用云手机之前,必须通过身份认证获取必要的串流前鉴权信息。请求鉴权信息需要满足以下前提:
- 已购买KooPhone云手机产品
- 已获取IAM租户鉴权信息
通过API获取device_token等串流所需参数:
- device_token:鉴权Token
- device_id:设备ID
- signaling_url:信令服务器地址
注意IAM租户鉴权信息需严格遵循官方指导文档获取,不可频繁调用,避免产生不必要的问题。
六、ADB调试与连接
6.1 ADB连接概述
KooPhone基于CPH稳定可靠的IaaS服务器底座,在端侧支持通过ADB(Android Debug Bridge,安卓调试桥)方式接入云手机。ADB是安卓官方的命令行工具,开发者可以通过ADB对云手机进行调试和应用安装等操作。
需要注意的是,管理面性能有限,对相同服务器批量执行的ADB命令会阻塞云手机其他任务的执行。因此建议合理安排ADB命令的执行频率和并发量。
6.2 通过API执行ADB命令
如前文所述,KooPhone提供了实例执行同步命令和异步命令的API接口。开发者可以通过调用这些API在云手机中执行adb shell命令。
常见的ADB命令示例:
# 安装APK
pm install /data/local/tmp/your_app.apk
# 卸载应用
pm uninstall com.example.app
# 查看已安装应用列表
pm list packages
# 启动Activity
am start -n com.example.app/.MainActivity
# 模拟点击
input tap x y
# 模拟滑动
input swipe x1 y1 x2 y2 duration
# 获取设备信息
getprop ro.product.model
6.3 ADB使用注意事项
使用ADB连接云手机时有几点需要特别注意:
- 禁止使用adb reboot命令:adb reboot命令不能用来重启云手机,因其可能导致云手机故障
- 使用控制台或API重启:重启云手机实例请在控制台操作或调用API接口
- 注意命令耗时:耗时较长的adb操作建议使用异步命令接口
七、安全管理与权限控制
7.1 IAM权限管理
KooPhone通过IAM(统一身份认证)服务进行权限管理。管理员可以在IAM控制台创建用户组,并授予云手机服务只读权限"KooPhone ReadOnlyUser"或所有操作权限的角色"KooPhone Administrator"。然后创建用户并将其加入对应的用户组。
权限生效后,使用已授权的用户登录云手机服务控制台,在"总览"页面如果可以查看实例列表,表示只读权限已生效;如果可以购买云手机,则表示所有操作权限已生效。
7.2 数据安全
KooPhone在数据安全方面提供了多重保障:
- 数据不落地:数据云端存储不落地,避免终端数据泄露风险
- 加密存储:用户数据加密存储、多副本备份
- 防截屏录屏:端侧构建防截屏、防录屏、实时加水印等特性
- 应用管控:应用黑白名单管理、权限管控
- 安全审计:云机监控和安全审计,保障云端安全
八、成本优化建议
使用KooPhone云手机服务时,可以从以下几个方面进行成本优化:
- 合理选择计费模式:长期稳定使用建议选择包年/包月模式,短期或弹性需求可选择按需计费
- 选择合适的规格:根据实际业务需求选择实例规格,避免资源浪费
- 合理规划区域:选择最靠近业务的区域以减少网络时延,同时注意不同区域之间内网互不相通
- 按需购买数量:根据实际用户数量购买实例,数量在1到1500之间灵活调整
九、常见问题解答
问1:KooPhone和CPH有什么区别?
KooPhone是在CPH(云手机服务器)基础上构建的上层云手机服务。CPH提供底层的云手机算力资源,而KooPhone在此基础上提供了端云协同引擎、用户账号鉴权、UI界面优化等完整的服务体验。
问2:如何获取KooPhone API的调用权限?
使用IAM服务获取Token进行认证鉴权。账号具备所有API的调用权限,IAM用户需要在IAM控制台被授予KooPhone ReadOnlyUser或KooPhone Administrator权限。
问3:KooPhone支持哪些平台的SDK?
KooPhone提供Android SDK(AAR包,适用于原生Android应用)和JavaScript SDK(JS包,适用于Web应用和混合开发场景)。
问4:可以使用ADB命令重启云手机吗?
不可以。adb reboot命令不能用来重启云手机,可能导致云手机故障。重启操作需要在控制台进行或调用API接口。
问5:KooPhone的自定义镜像有什么限制?
每个账号最多允许创建10个自定义镜像。创建镜像时需要在控制台配置镜像名称和操作系统。
问6:如何将云手机实例准备到可串流状态?
调用BatchPrepareInstances接口可以将实例准备到可以串流的状态。通过循环调用此接口直到云机状态为正常,即可开启串流。



