Quick Start

2026-10-28Loading rating…

1. Before You Start

This guide walks you through building a blank Pilot plugin project from scratch and getting the minimal path—"discovered by Pilot → connection established"—working. When done, you will have a plugin app that Pilot can recognize and connect to; calling the specific open capabilities is out of scope here—see the Module Example.

A plugin app is a standalone Android app installed on a remote controller with a screen. It runs in a separate process from Pilot and establishes an inter-process connection through the SDK. So building a plugin project = building an ordinary Android project + integrating MSDK 5.20 + declaring the plugin identity.

  • 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

If you use non-recommended versions, you need to adapt the whole integration process to your actual versions. Android Studio Narwhal 3 Feature Drop bundles Java Runtime 17 by default, so no extra configuration is usually needed.

1.2 Register as a DJI Developer

Visit the DJI Developer registration pageopen in new window to register. During registration you need to provide an email and phone number for verification.

1.3 Generate an App Key

Every plugin app needs a unique App Key to activate the SDK. Create one in the DJI Developer Centeropen in new window:

  1. Click "Apps" in the left navigation bar.
  2. Click the "Create App" button on the right.
  3. Fill in App Type, App name, development platform, Package Name, and other information.
  4. After submitting, you will receive an app activation email. Once activated, return to the Developer Center to get your App Key.

Note: In the plugin scenario, four values must be identical: the project's applicationId, the APK package name, the App Key's Package Name, and the plugin ID on the Pilot side. Pilot uses the APK package name directly as the plugin ID, so once the package name is set, do not change it—otherwise Pilot will treat it as a different plugin.

The rest of this guide uses com.example.pilotplugin as the example package name; replace it with the Package Name you filled in when applying for your App Key.


2. Create a Blank Project

2.1 Create the Project

On the Android Studio start page, choose New Project > Phone and Tablet > Empty Views Activity, and create it with the following configuration:

  • Name: PilotPlugin
  • Package name: com.example.pilotplugin
  • Minimum SDK: 24 or higher
  • Build configuration language: Groovy DSL (build.gradle)

Create a blank project

2.2 Import the UXSDK Source Module

Capabilities such as the plugin's custom components and AR drawing are provided by the dji.v5.ux package, which must be imported as a source module.

  1. Get the android-sdk-v5-uxsdk directory from the Mobile SDK V5 Sample projectopen in new window, and copy the whole directory to the project root, alongside the app folder.
  2. Edit settings.gradle to include it in the project:
rootProject.name = "PilotPlugin"
include ':app'
include ':android-sdk-v5-uxsdk'

Even if you don't plan to use custom components for now, it's recommended to import it now. The plugin's drawing capabilities on Pilot's UI all depend on this module.


3. Configure Project Dependencies

3.1 Edit build.gradle (Project)

The DJI SDK is published on Maven Central; keeping mavenCentral() in the repository configuration is enough, with no need to add a private repository:

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 Edit 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"          // must match the App Key's Package Name
        minSdkVersion Integer.parseInt(project.ANDROID_MIN_SDK_VERSION)
        targetSdkVersion Integer.parseInt(project.ANDROID_TARGET_SDK_VERSION)
        versionCode 1
        versionName "1.0"

        // Inject the App Key into the AndroidManifest placeholder to keep the key out of version control
        manifestPlaceholders["API_KEY"] = project.PLUGIN_API_KEY

        ndk {
            abiFilters 'arm64-v8a'                       // the SDK currently supports only the arm64-v8a architecture
        }
    }

    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 {
        // Several aars pulled in by the SDK contain a so with the same name; just pick the first
        pickFirst 'lib/arm64-v8a/libc++_shared.so'
        pickFirst 'lib/armeabi-v7a/libc++_shared.so'
    }
}

dependencies {
    implementation "com.dji:dji-sdk-v5-aircraft:$SDK_VERSION"           // runtime implementation, includes so and resources
    compileOnly "com.dji:dji-sdk-v5-aircraft-provided:$SDK_VERSION"     // compile-time symbols, not packaged into the APK
    implementation project(':android-sdk-v5-uxsdk')                     // provides the dji.v5.ux capabilities

    implementation 'androidx.appcompat:appcompat:1.6.1'
    implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
}

You don't need to declare networking libraries, Gson, RxJava, Room, etc. manually. The POM of dji-sdk-v5-aircraft already declares them as transitive dependencies, and Gradle pulls them automatically.

3.3 Edit 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 version; plugin capabilities require 5.20.1 or above
SDK_VERSION=5.20.1

# The App Key you obtained from the Developer Center
PLUGIN_API_KEY=Please add your app key here.

4. Declare the Plugin Identity

The first three sections are all generic work for integrating MSDK. This section is unique to a plugin project: only when the plugin identity is declared correctly can Pilot discover your APK during a scan.

Pilot discovers plugins by querying APKs in the system that declare the plugin registration service, then reads that APK's contract file to obtain the plugin's name, version, developer, and other information. The registration Service is already declared in the SDK's AndroidManifest.xml and is merged into your project automatically—you don't need to write any Service yourself, only provide the contract file.

4.1 Write the Plugin Contract XML

Create 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." />

Meanings of the four attributes:

AttributeMeaning
dop:namePlugin display name, shown in Pilot's plugin list
dop:versionPlugin version number
dop:developerDeveloper name
dop:descriptionPlugin description

The plugin ID is always the APK package name and cannot (and need not) be declared through the contract.

Note: All four attributes are required. If any one is missing, Pilot deems the contract invalid and skips the entire plugin: your app won't appear in the plugin list, with no error prompt at all.

4.2 Provide Multilingual Plugin Info

The dop:name, dop:developer, and dop:description in the contract XML are fallback values. If you define the following three fixed-name strings in strings.xml, Pilot uses them first and picks the translation matching the remote controller's current language:

<!-- 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>

The string names must match the above exactly; Pilot looks them up by fixed name, and renaming falls back to the fallback values in the contract XML.

4.3 Provide the Plugin Icon

IconSourceDescription
Plugin list iconThe APK's app icon (android:icon)Extracted automatically by Pilot during the scan; no extra declaration needed
Toolbar iconA drawable resource named dji_toolbar_iconOptional; skipped when not provided

If you need a Toolbar icon, place dji_toolbar_icon.png under res/drawable/.

4.4 Edit AndroidManifest.xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.pilotplugin">

    <!-- The first activation of the DJI SDK needs network access to the registration server -->
    <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 activation Key; value injected by manifestPlaceholders in build.gradle -->
        <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>

A remote controller with a screen is a landscape device, so it's recommended to declare android:screenOrientation="landscape" uniformly for plugin pages. Pilot launches plugin pages across processes, so the launched Activity must declare android:exported="true".


5. Initialize the Plugin SDK

5.1 Write the Application

Create PluginApplication.kt under com.example.pilotplugin, alongside 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)
        // Load the SDK's decryption/hardening package; do not call any SDK interface before install
        com.cySdkyc.clx.Helper.install(this)
    }

    override fun onCreate() {
        super.onCreate()
        PluginSdkInitializer.init(this)
    }
}

Warning: Missing Helper.install(this) causes the app to crash on startup with a ClassNotFoundException for SDK-related classes. This step must be in attachBaseContext and before any SDK call.

5.2 Initialize the SDK and Establish the Connection

Create 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 {
                // Which plugin page to navigate back to when the user taps the plugin card in Pilot
                homePageOnClickAction = NavigateAction(
                    NavigateAction.Value.SELF_DEFINE,
                    "com.example.pilotplugin.MainActivity"  // TODO: replace with your Activity's fully qualified name
                )
            }
        }

        SDKManager.getInstance().init(context, settings, object : SDKManagerCallback {

            override fun onInitProcess(event: DJISDKInitEvent, totalProcess: Int) {
                if (event == DJISDKInitEvent.INITIALIZE_COMPLETE) {
                    SDKManager.getInstance().registerApp()   // activation can only start after init completes
                }
            }

            override fun onRegisterSuccess() {
                Log.i(TAG, "App Key activated successfully")
            }

            override fun onRegisterFailure(error: IDJIError) {
                Log.e(TAG, "App Key activation failed: ${error.errorCode()}")
            }

            override fun onRemoteServerStateUpdated(state: ServerState) {
                // Inter-process connection state with Pilot; CONNECTED means the plugin is ready
                Log.i(TAG, "Connection state with Pilot: $state")
            }

            override fun onRemoteServerCompatibleError(error: IDJIError) {
                Log.e(TAG, "Plugin and Pilot versions are incompatible: ${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) {}
        })
    }
}

Three key points:

  • SDKLinKMode.REMOTE_PILOT is the link mode for plugin mode, different from an ordinary MSDK app's link mode, and must be specified explicitly.
  • The connection is driven automatically by the SDK initialization flow; the plugin doesn't need to initiate it manually—just observe the result through onRemoteServerStateUpdated.
  • PluginAPPConfig only needs homePageOnClickAction; the plugin version info is filled in automatically by the SDK.

ServerState has four values:

EnumMeaning
UNINITIALIZEDService not initialized
CONNECTEDConnected; you can start calling the open capabilities
DISCONNECTDisconnected
INCOMPATIBLEPlugin and Pilot versions are incompatible

Note: setTitle, setDescription, and setIconResFileName on PluginAPPConfig are deprecated; the plugin's name, description, and icon are now provided by the contract XML and resource files (see Section 4).


6. Build, Install, and Verify

  1. In Android Studio, choose Sync Now to sync the project, then build.
  2. Connect the remote controller with a screen to the computer via USB, enable the controller's developer options and USB debugging, select the device in Android Studio, and run to install the plugin app onto the controller.
  3. On first launch of the plugin app, keep the controller connected to the network and wait for App Key activation to complete.
  4. Open Pilot's plugin management page. If your plugin appears in the list with a connected status, the blank project is working.

Pilot plugin management page

If the status on the plugin management page is not as expected, you can use logs to help locate the issue. Normally, logcat outputs the following in order:

PluginSdkInitializer: App Key activated successfully
PluginSdkInitializer: Connection state with Pilot: CONNECTED

7. Next Steps

After the blank project works, you can continue learning:

  • Module Example: minimal runnable examples of each open capability module.

8. FAQ

My plugin doesn't appear in Pilot's plugin management page

Troubleshoot in the following order:

  1. Confirm res/xml/dji_open_pilot_plugin.xml exists and is under app/src/main/res/xml/ rather than some other directory.
  2. Confirm all four items—dop:name, dop:version, dop:developer, dop:description—are filled in the contract. If any one is missing, Pilot silently skips the entire plugin.
  3. Confirm xmlns:dop is set to https://dji.com/open-pilot; a mismatched namespace makes the attributes unreadable, which is equivalent to them being missing.
  4. Confirm the plugin APK is installed successfully and the Pilot version supports plugin capabilities.
<!-- ❌ Missing dop:description; the entire plugin will be skipped -->
<plugin xmlns:dop="https://dji.com/open-pilot"
    dop:name="My Pilot Plugin"
    dop:version="1.0.0"
    dop:developer="Example Inc." />

<!-- ✅ All four items present -->
<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 is called; App Key activation fails

  1. Confirm PLUGIN_API_KEY in gradle.properties is replaced with the real App Key and has been activated via email in the Developer Center.
  2. Confirm the project's applicationId exactly matches the Package Name you filled in when applying for the App Key, including case.
  3. Confirm the remote controller is connected to the network. The first activation needs to reach the DJI registration server, and the INTERNET permission cannot be omitted.
  4. Get the specific error code via error.errorCode() to locate the issue further.

Activation succeeds, but the connection state never becomes CONNECTED

Pilot initiates a registration to the plugin when establishing the connection; a registration timeout or failure causes the connection to drop:

Error code constantTriggerSuggested handling
PLUGIN_REGISTER_TIMEOUTRegistration doesn't call back within 5 secondsCheck whether time-consuming operations in Application.onCreate block the main thread
PLUGIN_REGISTER_FAILEDThe registration flow returns failureConfirm the plugin process is alive and not killed by the system's power-saving policy

onRemoteServerCompatibleError is called

The SDK version used by the plugin doesn't match the Pilot version on the remote controller. Align the two to mutually compatible versions per the error message: if the plugin version is too low, upgrade SDK_VERSION in gradle.properties; if the Pilot version is too low, upgrade Pilot on the controller.

The app crashes on startup with ClassNotFoundException

com.cySdkyc.clx.Helper.install(this) was omitted in Application.attachBaseContext, or an SDK interface was called before it.

// ❌ Wrong order; SDK is called before install
override fun attachBaseContext(base: Context?) {
    super.attachBaseContext(base)
    SDKManager.getInstance()
    com.cySdkyc.clx.Helper.install(this)
}

// ✅ install goes first
override fun attachBaseContext(base: Context?) {
    super.attachBaseContext(base)
    com.cySdkyc.clx.Helper.install(this)
}

Build error about duplicate so libraries

Add the pickFirst configuration in packagingOptions of build.gradle (Module: app); see "3. Configure Project Dependencies".

Last Updated: