快速开始

2026-10-28评分加载中…

一、开始之前

本文带你从零搭建一个空白的 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 开发者注册页open in new window 完成注册。注册过程中需要你提供电子邮件、手机号信息用于验证。

1.3 生成 App Key

每个插件 App 都需要一个唯一的 App Key 来激活 SDK。前往 DJI 开发者中心open in new window 创建:

  1. 点击左侧导航栏「应用」。
  2. 点击右侧的「创建应用」按钮。
  3. 填写 App Type、App 名称、开发平台、Package Name 等信息。
  4. 提交后你会收到一封应用激活邮件,激活成功后返回开发者中心即可获得 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 包提供,需要以源码模块的形式引入。

  1. 从 Mobile SDK V5 Sample 工程open in new window 获取 android-sdk-v5-uxsdk 目录,整个复制到工程根目录下,与 app 文件夹同级。
  2. 修改 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 与资源文件提供(见第四节)。


六、编译、安装与验证

  1. 在 Android Studio 中选择 Sync Now 同步工程,然后编译。
  2. 把带屏遥控器通过 USB 连接电脑,打开遥控器的开发者选项与 USB 调试,在 Android Studio 中选择该设备并运行,将插件 App 安装到遥控器上。
  3. 首次启动插件 App,保持遥控器联网,等待 App Key 激活完成。
  4. 打开 Pilot 的插件管理页面,如果列表中出现了你的插件,且状态显示为已连接,说明空白工程已经跑通。

Pilot 插件管理页面

如果插件管理页面中的状态不符合预期,可以通过日志辅助定位。正常情况下 logcat 会依次输出:

PluginSdkInitializer: App Key 激活成功
PluginSdkInitializer: 与 Pilot 的连接状态:CONNECTED

七、下一步

空白工程跑通后,你可以继续了解:

  • 模块示例:各开放能力模块的最小可运行示例。

八、常见问题(FAQ)

Pilot 的插件管理页面中找不到我的插件

按下列顺序排查:

  1. 确认 res/xml/dji_open_pilot_plugin.xml 存在,且路径是 app/src/main/res/xml/ 而不是其他目录。
  2. 确认合约中 dop:name、dop:version、dop:developer、dop:description 四项都已填写。缺任意一项,Pilot 都会静默跳过整个插件。
  3. 确认 xmlns:dop 的取值是 https://dji.com/open-pilot,命名空间不匹配时属性读取不到,效果等同于缺失。
  4. 确认插件 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 激活失败

  1. 确认 gradle.properties 中的 PLUGIN_API_KEY 已替换为真实 App Key,并已在开发者中心完成邮件激活。
  2. 确认工程的 applicationId 与申请 App Key 时填写的 Package Name 完全一致,包括大小写。
  3. 确认遥控器已联网。首次激活需要访问 DJI 注册服务器,INTERNET 权限不可省略。
  4. 通过 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 配置,见「三、配置工程依赖」。

最近修改: