环境要求

• 支持 Android 4.3（Android-19+）及以上系统的真机设备，支持 armeabi-v7a
• IDE：Android Studio（推荐使用最新版本）
• 搭建 Java 环境，使用 Java 作为开发语言，JDK 版本需要 1.8+

添加 Maven 仓库地址

1. 在 Project 根目录下的 build.gradle 文件中的 repositories 中配置 maven 仓库地址。
   示例代码如下：

   buildscript {
       repositories {
           maven {
               url 'https://artifact.bytedance.com/repository/Volcengine/'
           }
       }
   }
   
   allprojects {
       repositories {
           maven {
               url 'https://artifact.bytedance.com/repository/Volcengine/'
           }
       }
   }
   

2. 在项目中引入 vePhoneSDK。

   • 方式一：解压下载的 vePhoneSDK 包文件，将 phone-release.aar 文件拷贝到 libs 目录下。在应用模块的 build.gradle 文件中的 dependencies 中加入以下代码。

     repositories {
        flatDir {dirs 'libs'}
     }
     dependencies {
        implementation fileTree(include: ['*.jar'], dir: 'libs')
        // 云手机 SDK
        implementation files('libs/phone`-release.aar`')
        implementation 'androidx.annotation:annotation:1.1.0'
        // 选择引用以下三种框架中的任意一种
        implementation 'com.google.code.gson:gson:2.8.5'
        implementation 'com.alibaba:fastjson:1.1.72.android'
        implementation 'com.fasterxml.jackson.core:jackson-databind:2.7.0'
        implementation 'com.fasterxml.jackson.core:jackson-core:2.7.0'
     }
     

   • 方式二：在应用模块的 build.gradle 文件中的 dependencies 中添加 vePhoneSDK 的依赖，参考以下示例代码。

     说明

     vePhoneSDK 版本号持续更新中，获取最新版本号可参考获取 SDK 和 Demo。

     implementation 'com.volcengine.vephone:vephone:1.64.0'
     

   • 方式三：（非必须）在应用模块的 build.gradle 文件中的 dependencies 中添加 veGameSDK 以及插件包的依赖，参考以下示例代码。

     说明

     vePhoneSDK 版本号持续更新中，获取最新版本号可参考获取 SDK 和 Demo。

     implementation 'com.volcengine.vephone:vephone:1.64.0'
     implementation 'com.volcengine.vegame:core-full:1.64.0'
     

3. 设置 Java 版本到 1.8，参考以下示例代码。

   android {
       // ...
       compileOptions {
           sourceCompatibility JavaVersion.VERSION_1_8
           targetCompatibility JavaVersion.VERSION_1_8
       }
   }
   

4. 引用依赖注意事项。

   • 如果依赖了以下模块，则需要注意 Duplicate Class 等相关的编译错误：

     org.java-websocket:Java-WebSocket:x.x.x
     

   • 如果依赖了 3.37.0 或以上版本的 VolcEngineRTC 模块，则在使用 RTCVideo.startVideoCapture 接口时，需要引入 Kotlin 依赖。

权限声明

根据实际场景在 AndroidManifest.xml 文件中声明 SDK 需要的权限，参考以下示例：

//网络权限，使用场景：音视频传输等
<uses-permission android:name="android.permission.INTERNET" />

//WiFi网络状态，使用场景：用户手机网络状态变化监听
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

//录音权限，使用场景：[开启/关闭] 麦克风
<uses-permission android:name="android.permission.RECORD_AUDIO" />
//设置播放模式的权限：外放 / 听筒
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />

//同步定位信息，使用场景：当有些游戏需要获取用户的地理位置时，我们需要获取用户的地理位置信息
//并传送给远端Pod
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_LOCATION_EXTRA_COMMANDS" />

//读写存储
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

<manifest>
<application android:requestLegacyExternalStorage="true">
</application>
</manifest>

快速开始

获取临时鉴权密钥

1. 登录火山引擎控制台，点击页面右上角用户信息，选择账号 > API访问密钥，获取火山引擎账号对应的原始 Access Key ID（ak）和 Secret Access Key（sk）。
2. 参考调用 获取临时密钥（STS） 文档，获取用于鉴权的临时密钥。
3. 在 app/src/main/AndroidManifest.xml 文件的 meta-data 中填入注册的火山引擎用户账号。参考以下示例：

   <meta-data
       android:name="VOLC_ACCOUNT_ID"
       android:value="21000xxxxx" />
   

初始化 VePhoneEngine

调用 prepare 接口，初始化 VePhoneEngine，进行资源异步加载：

VePhoneEngine.prepare(Application application);

配置 PhonePlayConfig

配置启动云手机需要的参数：

PhonePlayConfig.Builder builder = new PhonePlayConfig.Builder();

builder.userId(userId) // 自定义客户端用户 ID
    .ak(ak) // 必填参数，临时鉴权 ak
    .sk(sk)  // 必填参数，临时鉴权 sk
    .token(token) // 必填参数，临时鉴权 token
    .container(mContainer) // 必填参数，用来承载画面的 Container, 参数说明: layout 需要是 FrameLayout 或者 FrameLayout 的子类
    .roundId(intent.getStringExtra(KEY_ROUND_ID)) // 必填参数，自定义当次启动云手机的生命周期标识
    .videoStreamProfileId(intent.getIntExtra(KEY_ClARITY_ID, 1)) // 选填参数，清晰度档位ID
    .podId(intent.getStringExtra(KEY_POD_ID)) // 必填参数, 云手机实例 ID
    .productId(intent.getStringExtra(KEY_PRODUCT_ID)) // 必填参数, 云手机业务 ID 
    .enableGravitySensor(true) // 打开重力传感器开关
    .enableGyroscopeSensor(true) // 打开陀螺仪开关
    .enableMagneticSensor(true) // 打开磁力传感器开关
    .enableOrientationSensor(true) // 打开方向传感器开关
    .enableVibrator(true) // 打开本地振动开关
    .enableLocationService(true) // 打开本地定位功能开关
    .enableLocalKeyboard(true) // 打开本地键盘开关
    .streamListener(IStreamListener streamListener); // 获取音视频流信息回调监听

PhonePlayConfig phonePlayConfig = builder.build();

启动云手机

调用 start 接口，启动云手机：

vePhoneEngine.start(phonePlayConfig, IPlayerListener playerListener);