原生Xposed服务集成指南

This guide is for native images adapted without the Xposed tag. It uses the native Xposed activation component to avoid the risk-control issues that may be caused by open-source Xposed libraries.

1. Scope

Use this guide to integrate Xposed service preloading or companion capabilities into native images supported by FoxPhone. The following Android systems are currently supported:

AOSP 10
AOSP 12

Do not add another open-source Xposed Bridge dependency at the same time. The AAR provided here uses the platform-adapted API namespace; mixing in another Bridge library may cause class conflicts, load failures, or additional risk-control signals.

2. Download the integration dependency

Download the AAR provided by the platform and keep the file name as xposed-bridge-debug.aar：

xposed-bridge-debug.aar 264.87 KB

File size: 271231 bytes (about 264.87 KB)
SHA-256：D9DC538315E875D83357B3986CC27D1F7535BE17D9F3F6E69C2F327C9A23FC98
Minimum Android API: 26

3. Android demo integration

Step 1: Create an Android project

Create an Android project in Android Studio.
Choose the No Activity template to avoid generating unrelated screen code.
The example can use Java; when using Kotlin, implement the entry class with the same interfaces.

Create a No Activity project in Android Studio

Step 2: Add the AAR

Create a libs directory under the App module.
Place xposed-bridge-debug.aar in app/libs/.
Reference it with compileOnly in app/build.gradle.kts so the Bridge implementation is not packaged into the APK again.

dependencies {
    compileOnly(files("libs/xposed-bridge-debug.aar"))
}

For projects using the Groovy DSL, configure it in app/build.gradle:

dependencies {
    compileOnly files('libs/xposed-bridge-debug.aar')
}

Step 3: Configure the module entry point

Create an assets directory under app/src/main/.
Create the extensionless file xposed_init。
Enter the fully qualified name of one entry class per line. Example:

com.example.myapplication.Main

The package and class name in xposed_init must exactly match the source code; otherwise the native component cannot find the entry class.

Step 4: Implement the entry class

The API package in the AAR is de.robv.android.examed, not the de.robv.android.xposed package commonly used by open-source Xposed libraries. Entry class example:

package com.example.myapplication;

import de.robv.android.examed.IXposedHookLoadPackage;
import de.robv.android.examed.XposedBridge;
import de.robv.android.examed.callbacks.XC_LoadPackage;

public class Main implements IXposedHookLoadPackage {
    @Override
    public void handleLoadPackage(XC_LoadPackage.LoadPackageParam loadPackageParam)
            throws Throwable {
        // 必须先限制目标包，避免在所有应用进程中执行初始化逻辑。
        if (!"com.example.target".equals(loadPackageParam.packageName)) {
            return;
        }

        XposedBridge.log("Native Xposed module loaded: "
                + loadPackageParam.packageName);

        // 在此处实现经过授权的服务预启或伴随逻辑。
    }
}

Replace com.example.target with the actual target application package, and keep business logic limited to authorized applications and scenarios.

Step 5: Check the project structure

After configuration, the project should contain at least the following files:

app/libs/xposed-bridge-debug.aar
app/src/main/assets/xposed_init
app/src/main/java/.../Main.java or the corresponding Kotlin file
app/src/main/AndroidManifest.xml
app/build.gradle.kts or app/build.gradle

Native Xposed module project structure

Step 6: Configure obfuscation rules

If the release build enables R8 or ProGuard, keep the entry class so its name is not changed or removed:

-keep class com.example.myapplication.Main { *; }

If you change the entry class package, update xposed_init and the obfuscation rules.。

Step 7: Build and verify

Run Gradle Sync and confirm that the AAR dependency resolves correctly.
Build the APK and confirm that it contains assets/xposed_init.
Install the APK on a supported native image instance.
Enable the module through the FoxPhone native Xposed activation component.
Launch the target application, check the logs for entry-class output, and verify that the business logic runs only in the target package.

4. Frequently asked questions

1. The module does not run after installation

Confirm that the instance uses a supported AOSP 10 or AOSP 12 native image, that the module is activated by the native component, and that the fully qualified class name in xposed_init is correct.

2. Xposed interfaces cannot be found during compilation

Check that the AAR is in app/libs/, verify the path in the Gradle file, and confirm that the de.robv.android.examed namespace is imported.

3. The release package installs, but the entry point does not run

Check whether R8 or ProGuard changed or removed the entry class, and verify that the obfuscation rules match xposed_init.

4. Duplicate classes or a Bridge conflict appears at runtime

Remove other Xposed Bridge dependencies and confirm that the platform AAR is added with compileOnly and is not packaged into the APK twice.

5. The module affects a non-target application

Filter by packageName at the very start of the entry method and return immediately for non-target processes.