快速开始
一、开始之前
本文带你从零搭建一个空白的 Pilot 插件工程,跑通「被 Pilot 发现 → 建立连接」这条最小链路。完成后你会得到一个能被 Pilot 识别并连上的插件 App,具体开放能力的调用不在本文范围内,见模块示例。
插件 App 是一个独立安装在带屏遥控器上的 Android 应用,与 Pilot 运行在两个进程中,通过 SDK 建立跨进程连接。因此搭建插件工程 = 搭建一个普通 Android 工程 + 集成 MSDK 5.20 + 声明插件身份。
1.1 推荐环境
- Android Studio:
Narwhal 3 Feature Drop | 2025.1.3 - Java Runtime:
17 - Kotlin:
2.1.0 - Gradle:
8.12 - Android Gradle Plugin:
8.7.0 - NDK:
28.0.13004108 - minSdkVersion:
24 - targetSdkVersion:
35 - compileSdkVersion:
35
如果你使用非推荐版本,需要根据实际版本自行适配整个集成过程。Android Studio Narwhal 3 Feature Drop 默认集成 Java Runtime 17,一般无需额外配置。
1.2 注册成为 DJI 开发者
访问 DJI 开发者注册页 完成注册。注册过程中需要你提供电子邮件、手机号信息用于验证。
1.3 生成 App Key
每个插件 App 都需要一个唯一的 App Key 来激活 SDK。前往 DJI 开发者中心 创建:
- 点击左侧导航栏「应用」。
- 点击右侧的「创建应用」按钮。
- 填写 App Type、App 名称、开发平台、Package Name 等信息。
- 提交后你会收到一封应用激活邮件,激活成功后返回开发者中心即可获得 App Key。
注意: 插件场景下有四个值必须完全一致:工程的
applicationId、APK 包名、App Key 的 Package Name、Pilot 侧的插件 ID。Pilot 直接用 APK 包名作为插件 ID,因此包名一旦确定就不要再改,否则 Pilot 会把它当成另一个插件。
本文后续以 com.example.pilotplugin 作为包名示例,请替换为你自己申请 App Key 时填写的 Package Name。
二、新建空白工程
2.1 创建工程
在 Android Studio 启动页选择 New Project > Phone and Tablet > Empty Views Activity,按下列配置创建:
- Name:
PilotPlugin - Package name:
com.example.pilotplugin - Minimum SDK:
24或更高 - Build configuration language:
Groovy DSL (build.gradle)

2.2 引入 UXSDK 源码模块
插件的自定义组件、AR 绘制等能力由 dji.v5.ux 包提供,需要以源码模块的形式引入。
- 从 Mobile SDK V5 Sample 工程 获取
android-sdk-v5-uxsdk目录,整个复制到工程根目录下,与app文件夹同级。 - 修改
settings.gradle,把它加入工程:
rootProject.name = "PilotPlugin"
include ':app'
include ':android-sdk-v5-uxsdk'
即使你暂时不打算使用自定义组件,也建议现在就引入。插件在 Pilot 界面上的绘制能力都依赖这个模块。
三、配置工程依赖
3.1 修改 build.gradle (Project)
DJI SDK 发布在 Maven Central 上,仓库配置中保留 mavenCentral() 即可,无需额外添加私有仓库:
buildscript {
repositories {
google()
mavenCentral()
}
dependencies {
classpath "com.android.tools.build:gradle:8.7.0"
classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$KOTLIN_VERSION"
}
}
allprojects {
repositories {
google()
mavenCentral()
}
}
3.2 修改 build.gradle (Module: app)
apply plugin: 'com.android.application'
apply plugin: 'kotlin-android'
android {
namespace 'com.example.pilotplugin'
compileSdkVersion Integer.parseInt(project.ANDROID_COMPILE_SDK_VERSION)
defaultConfig {
applicationId "com.example.pilotplugin" // 必须与 App Key 的 Package Name 一致
minSdkVersion Integer.parseInt(project.ANDROID_MIN_SDK_VERSION)
targetSdkVersion Integer.parseInt(project.ANDROID_TARGET_SDK_VERSION)
versionCode 1
versionName "1.0"
// 把 App Key 注入 AndroidManifest 的占位符,避免把密钥写进版本管理
manifestPlaceholders["API_KEY"] = project.PLUGIN_API_KEY
ndk {
abiFilters 'arm64-v8a' // SDK 当前只支持 arm64-v8a 架构
}
}
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
kotlinOptions {
jvmTarget = JavaVersion.VERSION_1_8
freeCompilerArgs += ["-Xjvm-default=all"]
}
buildFeatures {
viewBinding true
}
packagingOptions {
// SDK 引入的多个 aar 均包含同名 so,取第一个即可
pickFirst 'lib/arm64-v8a/libc++_shared.so'
pickFirst 'lib/armeabi-v7a/libc++_shared.so'
}
}
dependencies {
implementation "com.dji:dji-sdk-v5-aircraft:$SDK_VERSION" // 运行期实现,含 so 与资源
compileOnly "com.dji:dji-sdk-v5-aircraft-provided:$SDK_VERSION" // 编译期符号,不打包进 APK
implementation project(':android-sdk-v5-uxsdk') // 提供 dji.v5.ux 系列能力
implementation 'androidx.appcompat:appcompat:1.6.1'
implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
}
你不需要手动声明网络库、Gson、RxJava、Room 等库。dji-sdk-v5-aircraft 的 POM 已把这些声明为传递依赖,Gradle 会自动拉取。
3.3 修改 gradle.properties
android.useAndroidX=true
android.enableJetifier=true
android.nonTransitiveRClass=false
ANDROID_MIN_SDK_VERSION=24
ANDROID_TARGET_SDK_VERSION=35
ANDROID_COMPILE_SDK_VERSION=35
KOTLIN_VERSION=2.1.0
# MSDK 版本,插件能力需要 5.20.1 及以上
SDK_VERSION=5.20.1
# 你在开发者中心申请到的 App Key
PLUGIN_API_KEY=Please add your app key here.
四、声明插件身份
前三节做的都是集成 MSDK 的通用工作。这一节是插件工程独有的:只有正确声明了插件身份,Pilot 才能在扫描时发现你的 APK。
Pilot 通过查询系统中声明了插件注册服务的 APK 来发现插件,再读取该 APK 的合约文件获取插件的名称、版本、开发者等信息。注册用的 Service 已经在 SDK 的 AndroidManifest.xml 中声明,并会自动合并到你的工程,你不需要自己编写任何 Service,只需要提供合约文件。
4.1 编写插件合约 XML
新建 app/src/main/res/xml/dji_open_pilot_plugin.xml:
<?xml version="1.0" encoding="utf-8"?>
<plugin xmlns:dop="https://dji.com/open-pilot"
dop:name="My Pilot Plugin"
dop:version="1.0.0"
dop:developer="Example Inc."
dop:description="A blank plugin project built from the quick start guide." />
四个属性的含义:
| 属性 | 含义 |
|---|---|
dop:name | 插件显示名称,Pilot 的插件列表中展示 |
dop:version | 插件版本号 |
dop:developer | 开发者名称 |
dop:description | 插件描述 |
插件 ID 固定取 APK 包名,不需要也无法通过合约声明。
注意: 四个属性全部必填。任意一项缺失,Pilot 会判定合约无效并跳过整个插件,插件列表中不会出现你的 App,且没有任何报错提示。
4.2 提供多语言插件信息
合约 XML 中的 dop:name、dop:developer、dop:description 是兜底值。如果你在 strings.xml 中定义了下列三个固定名称的字符串,Pilot 会优先使用它们,并按遥控器当前语言取对应翻译:
<!-- res/values/strings.xml -->
<string name="dji_open_pilot_plugin_name">My Pilot Plugin</string>
<string name="dji_open_pilot_plugin_developer">Example Inc.</string>
<string name="dji_open_pilot_plugin_description">A blank plugin project built from the quick start guide.</string>
<!-- res/values-zh-rCN/strings.xml -->
<string name="dji_open_pilot_plugin_name">我的 Pilot 插件</string>
<string name="dji_open_pilot_plugin_developer">示例公司</string>
<string name="dji_open_pilot_plugin_description">按快速开始搭建的空白插件工程。</string>
字符串名称必须与上面完全一致,Pilot 按固定名称查找,改名后会回退到合约 XML 中的兜底值。
4.3 提供插件图标
| 图标 | 来源 | 说明 |
|---|---|---|
| 插件列表图标 | APK 的应用图标(android:icon) | Pilot 在扫描阶段自动提取,无需额外声明 |
| Toolbar 图标 | 名为 dji_toolbar_icon 的 drawable 资源 | 可选,未提供时跳过 |
如果需要 Toolbar 图标,在 res/drawable/ 下放置 dji_toolbar_icon.png 即可。
4.4 修改 AndroidManifest.xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.example.pilotplugin">
<!-- 首次激活 DJI SDK 需要联网访问注册服务器 -->
<uses-permission android:name="android.permission.INTERNET" />
<application
android:name=".PluginApplication"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:extractNativeLibs="true"
android:theme="@android:style/Theme.NoTitleBar.Fullscreen">
<!-- DJI SDK 激活 Key,值由 build.gradle 的 manifestPlaceholders 注入 -->
<meta-data
android:name="com.dji.sdk.API_KEY"
android:value="${API_KEY}" />
<activity
android:name=".MainActivity"
android:configChanges="orientation|screenSize|keyboardHidden"
android:exported="true"
android:launchMode="singleTask"
android:screenOrientation="landscape">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
</application>
</manifest>
带屏遥控器为横屏设备,插件页面建议统一声明 android:screenOrientation="landscape"。Pilot 需要跨进程拉起插件页面,被拉起的 Activity 必须声明 android:exported="true"。
五、初始化插件 SDK
5.1 编写 Application
在 com.example.pilotplugin 下新建 PluginApplication.kt,与 MainActivity.kt 同级:
package com.example.pilotplugin
import android.app.Application
import android.content.Context
class PluginApplication : Application() {
override fun attachBaseContext(base: Context?) {
super.attachBaseContext(base)
// 加载 SDK 的解密加固包,调用 install 前请勿调用任何 SDK 接口
com.cySdkyc.clx.Helper.install(this)
}
override fun onCreate() {
super.onCreate()
PluginSdkInitializer.init(this)
}
}
警告: 漏掉
Helper.install(this)会导致 App 启动即崩溃,抛出 SDK 相关类的ClassNotFoundException。这一步必须放在attachBaseContext中,且在任何 SDK 调用之前。
5.2 初始化 SDK 并建立连接
新建 PluginSdkInitializer.kt:
package com.example.pilotplugin
import android.content.Context
import android.util.Log
import dji.open.pilot.base.manager.PluginAPPConfig
import dji.open.pilot.base.ui.NavigateAction
import dji.open.pilot.client.manager.ServerState
import dji.v5.common.error.IDJIError
import dji.v5.common.register.DJISDKInitEvent
import dji.v5.common.register.InitSettings
import dji.v5.common.register.SDKLinKMode
import dji.v5.manager.SDKManager
import dji.v5.manager.interfaces.SDKManagerCallback
object PluginSdkInitializer {
private const val TAG = "PluginSdkInitializer"
fun init(context: Context) {
val settings = InitSettings(SDKLinKMode.REMOTE_PILOT).also {
it.pluginAppConfig = PluginAPPConfig().apply {
// 用户在 Pilot 中点击插件卡片时,跳转回插件的哪个页面
homePageOnClickAction = NavigateAction(
NavigateAction.Value.SELF_DEFINE,
"com.example.pilotplugin.MainActivity" // TODO: 替换为你的 Activity 全类名
)
}
}
SDKManager.getInstance().init(context, settings, object : SDKManagerCallback {
override fun onInitProcess(event: DJISDKInitEvent, totalProcess: Int) {
if (event == DJISDKInitEvent.INITIALIZE_COMPLETE) {
SDKManager.getInstance().registerApp() // 初始化完成后才能发起激活
}
}
override fun onRegisterSuccess() {
Log.i(TAG, "App Key 激活成功")
}
override fun onRegisterFailure(error: IDJIError) {
Log.e(TAG, "App Key 激活失败:${error.errorCode()}")
}
override fun onRemoteServerStateUpdated(state: ServerState) {
// 与 Pilot 的跨进程连接状态,CONNECTED 表示插件已就绪
Log.i(TAG, "与 Pilot 的连接状态:$state")
}
override fun onRemoteServerCompatibleError(error: IDJIError) {
Log.e(TAG, "插件与 Pilot 版本不兼容:${error.errorCode()}")
}
override fun onProductConnect(productId: Int) {}
override fun onProductDisconnect(productId: Int) {}
override fun onProductChanged(productId: Int) {}
@Deprecated("Deprecated in SDKManagerCallback")
override fun onDatabaseDownloadProgress(current: Long, total: Long) {}
})
}
}
三个关键点:
SDKLinKMode.REMOTE_PILOT是插件模式的链接模式,与普通 MSDK App 的链接模式不同,必须显式指定。- 连接由 SDK 初始化流程自动驱动,插件不需要手动发起,你只需要通过
onRemoteServerStateUpdated观察结果。 PluginAPPConfig只需要设置homePageOnClickAction,插件版本信息由 SDK 自动填充。
ServerState 有四个取值:
| 枚举 | 含义 |
|---|---|
UNINITIALIZED | 服务未初始化 |
CONNECTED | 已连接,可以开始调用开放能力 |
DISCONNECT | 已断开 |
INCOMPATIBLE | 插件与 Pilot 版本不兼容 |
说明:
PluginAPPConfig上的setTitle、setDescription、setIconResFileName已废弃,插件的名称、描述、图标统一改由合约 XML 与资源文件提供(见第四节)。
六、编译、安装与验证
- 在 Android Studio 中选择
Sync Now同步工程,然后编译。 - 把带屏遥控器通过 USB 连接电脑,打开遥控器的开发者选项与 USB 调试,在 Android Studio 中选择该设备并运行,将插件 App 安装到遥控器上。
- 首次启动插件 App,保持遥控器联网,等待 App Key 激活完成。
- 打开 Pilot 的插件管理页面,如果列表中出现了你的插件,且状态显示为已连接,说明空白工程已经跑通。

如果插件管理页面中的状态不符合预期,可以通过日志辅助定位。正常情况下 logcat 会依次输出:
PluginSdkInitializer: App Key 激活成功
PluginSdkInitializer: 与 Pilot 的连接状态:CONNECTED
七、下一步
空白工程跑通后,你可以继续了解:
- 模块示例:各开放能力模块的最小可运行示例。
八、常见问题(FAQ)
Pilot 的插件管理页面中找不到我的插件
按下列顺序排查:
- 确认
res/xml/dji_open_pilot_plugin.xml存在,且路径是app/src/main/res/xml/而不是其他目录。 - 确认合约中
dop:name、dop:version、dop:developer、dop:description四项都已填写。缺任意一项,Pilot 都会静默跳过整个插件。 - 确认
xmlns:dop的取值是https://dji.com/open-pilot,命名空间不匹配时属性读取不到,效果等同于缺失。 - 确认插件 APK 已经安装成功,且 Pilot 版本支持插件能力。
<!-- ❌ 缺少 dop:description,整个插件会被跳过 -->
<plugin xmlns:dop="https://dji.com/open-pilot"
dop:name="My Pilot Plugin"
dop:version="1.0.0"
dop:developer="Example Inc." />
<!-- ✅ 四项齐全 -->
<plugin xmlns:dop="https://dji.com/open-pilot"
dop:name="My Pilot Plugin"
dop:version="1.0.0"
dop:developer="Example Inc."
dop:description="A blank plugin project." />
回调 onRegisterFailure,App Key 激活失败
- 确认
gradle.properties中的PLUGIN_API_KEY已替换为真实 App Key,并已在开发者中心完成邮件激活。 - 确认工程的
applicationId与申请 App Key 时填写的 Package Name 完全一致,包括大小写。 - 确认遥控器已联网。首次激活需要访问 DJI 注册服务器,
INTERNET权限不可省略。 - 通过
error.errorCode()获取具体错误码进一步定位。
激活成功,但连接状态一直不是 CONNECTED
Pilot 在建立连接时会向插件发起一次注册,注册超时或失败都会导致连接被断开:
| 错误码常量 | 触发场景 | 处理建议 |
|---|---|---|
PLUGIN_REGISTER_TIMEOUT | 注册超过 5 秒未回调 | 检查 Application.onCreate 中是否有耗时操作阻塞了主线程 |
PLUGIN_REGISTER_FAILED | 注册流程返回失败 | 确认插件进程存活,未被系统省电策略杀死 |
回调 onRemoteServerCompatibleError
插件使用的 SDK 版本与遥控器上的 Pilot 版本不匹配。根据错误信息把两者对齐到相互兼容的版本:插件版本偏低时升级 gradle.properties 中的 SDK_VERSION,Pilot 版本偏低时升级遥控器上的 Pilot。
App 启动即崩溃,提示 ClassNotFoundException
Application.attachBaseContext 中漏调了 com.cySdkyc.clx.Helper.install(this),或者在它之前调用了 SDK 接口。
// ❌ 顺序错误,install 之前调用了 SDK
override fun attachBaseContext(base: Context?) {
super.attachBaseContext(base)
SDKManager.getInstance()
com.cySdkyc.clx.Helper.install(this)
}
// ✅ install 放在最前
override fun attachBaseContext(base: Context?) {
super.attachBaseContext(base)
com.cySdkyc.clx.Helper.install(this)
}
编译报错,提示 so 库重复
在 build.gradle (Module: app) 的 packagingOptions 中补上 pickFirst 配置,见「三、配置工程依赖」。