原生Xposed服务集成指南

本文件適用於適配非 Xposed 標籤的原生映像，使用原生 Xposed 啟用元件，避免開源 Xposed 程式庫造成風控等問題。

一、適用範圍

本文件用於指導開發者在 FoxPhone 支援的原生映像中整合 Xposed 服務預啟或伴隨功能。目前支援以下 Android 系統：

AOSP 10
AOSP 12

請勿同時引入其他開源 Xposed Bridge 相依項目。本文件提供的 AAR 使用平台適配後的 API 命名空間，混用其他 Bridge 程式庫可能造成類別衝突、載入失敗或引入額外風控特徵。

二、下載整合依賴

下載平台提供的 AAR，並將檔案名稱保持為 xposed-bridge-debug.aar：

xposed-bridge-debug.aar 264.87 KB

檔案大小：271231 bytes（約 264.87 KB）
SHA-256：D9DC538315E875D83357B3986CC27D1F7535BE17D9F3F6E69C2F327C9A23FC98
最低 Android API：26

三、最佳 Android Demo 實作案例

步驟一：建立 Android 專案

在 Android Studio 中建立 Android 專案。
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.

在 Android Studio 中建立 No Activity 專案

步驟二：引入 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')
}

步驟三：設定模組進入點

Create an assets directory under app/src/main/.
在該目錄中建立無副檔名檔案 xposed_init。
每行填寫一個進入類別的完整類別名稱。範例：

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.

步驟四：實作進入類別

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.

步驟五：檢查專案結構

完成設定後，至少應包含以下檔案：

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

原生 Xposed 模組專案結構

步驟六：設定混淆規則

如果發布建置啟用了 R8 或 ProGuard，需要保留進入類別，避免類別名稱被修改或刪除：

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

如果修改了進入類別的套件名稱，請同步修改 xposed_init and the obfuscation rules.。

步驟七：建置與驗證

執行 Gradle Sync，確認 AAR 相依項目可正常解析。
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.

四、常見問題

1. 模組安裝後沒有執行

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 介面

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. Release 套件正常安裝但進入點沒有執行

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

4. 執行時出現重複類別或 Bridge 衝突

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

5. 模組影響了非目標應用程式

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