From 4274f357c4e7a20a6556352958a251dadf181d3a Mon Sep 17 00:00:00 2001 From: kanaodnd <188126396+kanaodnd@users.noreply.github.com> Date: Fri, 10 Apr 2026 01:15:37 +0000 Subject: [PATCH 1/2] docs: add API integration documentation Added comprehensive documentation on how to integrate AxManager to third-party client applications for executing commands with elevated privileges. Included setup for: - Axerish with libsu - Direct Axeron API Updated website documentation and `api/README.md` in both English and Indonesian/Chinese respectively. --- website/docs/.vitepress/config.mts | 2 + website/docs/guide/api-integration.md | 119 +++++++++++++++++++++++ website/docs/zh/guide/api-integration.md | 119 +++++++++++++++++++++++ 3 files changed, 240 insertions(+) create mode 100644 website/docs/guide/api-integration.md create mode 100644 website/docs/zh/guide/api-integration.md diff --git a/website/docs/.vitepress/config.mts b/website/docs/.vitepress/config.mts index 5ea6a9b..c56790f 100644 --- a/website/docs/.vitepress/config.mts +++ b/website/docs/.vitepress/config.mts @@ -29,6 +29,7 @@ export default defineConfig({ text: "What is Axeron Manager?", link: "/guide/what-is-axeron-manager", }, + { text: "API Integration", link: "/guide/api-integration" }, { text: "User Manual", link: "/guide/user-manual" }, { text: "FAQ", link: "/guide/faq" }, ], @@ -70,6 +71,7 @@ export default defineConfig({ text: "什么是 Axeron Manager？", link: "/zh/guide/what-is-axeron-manager", }, + { text: "API 集成", link: "/zh/guide/api-integration" }, { text: "用户手册", link: "/zh/guide/user-manual" }, { text: "常见问题", link: "/zh/guide/faq" }, ], diff --git a/website/docs/guide/api-integration.md b/website/docs/guide/api-integration.md new file mode 100644 index 0000000..47650a3 --- /dev/null +++ b/website/docs/guide/api-integration.md @@ -0,0 +1,119 @@ +# API Integration + +AxManager allows third-party client applications to execute shell commands with elevated privileges (ADB or Root) using the **Axeron API**. + +There are two primary methods for integrating AxManager into your app: +1. **Using Axerish with libsu** (Recommended for most apps that already use `libsu`) +2. **Using the Direct Axeron API** (Lower level, no `libsu` dependency) + +--- + +## 1. Using Axerish + libsu + +Axerish is a shell wrapper provided by AxManager that seamlessly integrates with the popular `libsu` library by topjohnwu. It allows your app to use AxManager's execution context transparently. + +### Step 1: Add Dependencies + +Add `libsu` and the Axeron API to your `build.gradle.kts`: + +```kotlin +dependencies { + implementation("com.github.topjohnwu.libsu:core:") + // Make sure to check GitHub releases for the latest version + implementation("com.github.fahrez182.AxManager:api:") +} +``` + +### Step 2: Initialize in Application + +In your custom `Application` class, initialize `Axerish` and set it as the default shell builder for `libsu`: + +```kotlin +import android.app.Application +import com.topjohnwu.superuser.Shell +import frb.axeron.Axerish + +class MyApplication : Application() { + override fun onCreate() { + super.onCreate() + + // 1. Initialize Axerish by passing your application's package name + Axerish.initialize(packageName) + + // 2. Configure libsu to use Axerish as its shell + Shell.setDefaultBuilder( + Shell.Builder.create() + .setCommands("sh", Axerish.axrun_path.absolutePath) + ) + } +} +``` + +### Step 3: Execute Commands + +Now you can use `Shell.cmd()` normally. The execution is automatically routed to AxManager's elevated environment! + +```kotlin +import com.topjohnwu.superuser.Shell + +// Run any command with elevated privileges +val result = Shell.cmd("uname -r").exec() + +if (result.isSuccess) { + println("Kernel version: ${result.out.joinToString("\n")}") +} +``` + +--- + +## 2. Using Direct Axeron API + +If your app requires lower-level integration or you prefer not to include the `libsu` library, you can bind directly to the Axeron service. + +### Step 1: Add Dependencies + +Add the Axeron API and Provider to your `build.gradle.kts`: + +```kotlin +dependencies { + implementation("com.github.fahrez182.AxManager:api:") + implementation("com.github.fahrez182.AxManager:provider:") +} +``` + +### Step 2: Declare the Provider + +Add the `AxeronProvider` to your app's `AndroidManifest.xml`. This enables AxManager to send the IPC binder to your application. + +```xml + +``` + +### Step 3: Listen for Binder & Execute + +Wait for the AxManager service to connect using `Axeron.addBinderReceivedListenerSticky`, and then use `Axeron.newProcess` to run commands. + +```kotlin +import frb.axeron.api.Axeron + +// Listen for the connection to the AxManager service +Axeron.addBinderReceivedListenerSticky { + // We are now connected to AxManager! + + // Execute a command directly + val process = Axeron.newProcess("uname -r") + + // Read the output + process.inputStream.bufferedReader().useLines { lines -> + lines.forEach { println("Output: $it") } + } + + // Wait for the command to finish + val exitCode = process.waitFor() + println("Command finished with exit code: $exitCode") +} +``` diff --git a/website/docs/zh/guide/api-integration.md b/website/docs/zh/guide/api-integration.md new file mode 100644 index 0000000..2a651b1 --- /dev/null +++ b/website/docs/zh/guide/api-integration.md @@ -0,0 +1,119 @@ +# API 集成 + +AxManager 允许第三方客户端应用程序使用 **Axeron API** 在提权环境（ADB 或 Root）下执行 Shell 命令。 + +目前有两种主要方法将 AxManager 集成到您的应用中： +1. **使用 Axerish 与 libsu**（推荐，适用于大多数已使用 `libsu` 的应用） +2. **直接使用 Axeron API**（底层方法，无需依赖 `libsu`） + +--- + +## 1. 使用 Axerish + libsu + +Axerish 是 AxManager 提供的一个 Shell 包装器，它可以无缝集成到流行的 `libsu` 库中。这使得您的应用可以透明地使用 AxManager 的执行环境。 + +### 第一步：添加依赖 + +在您的 `build.gradle.kts` 中添加 `libsu` 和 Axeron API： + +```kotlin +dependencies { + implementation("com.github.topjohnwu.libsu:core:<最新版本>") + // 请在 GitHub Releases 页面查看最新版本 + implementation("com.github.fahrez182.AxManager:api:<最新版本>") +} +``` + +### 第二步：在 Application 中初始化 + +在您自定义的 `Application` 类中，初始化 `Axerish` 并将其设置为 `libsu` 的默认 Shell 构建器： + +```kotlin +import android.app.Application +import com.topjohnwu.superuser.Shell +import frb.axeron.Axerish + +class MyApplication : Application() { + override fun onCreate() { + super.onCreate() + + // 1. 传入您的应用包名来初始化 Axerish + Axerish.initialize(packageName) + + // 2. 配置 libsu 以使用 Axerish 作为其 Shell + Shell.setDefaultBuilder( + Shell.Builder.create() + .setCommands("sh", Axerish.axrun_path.absolutePath) + ) + } +} +``` + +### 第三步：执行命令 + +现在您可以像往常一样使用 `Shell.cmd()`。所有的执行命令都会自动路由到 AxManager 的提权环境中！ + +```kotlin +import com.topjohnwu.superuser.Shell + +// 运行具有提升权限的任何命令 +val result = Shell.cmd("uname -r").exec() + +if (result.isSuccess) { + println("内核版本: ${result.out.joinToString("\n")}") +} +``` + +--- + +## 2. 直接使用 Axeron API + +如果您的应用需要更底层的集成，或者您不想引入 `libsu` 库，您可以直接绑定到 Axeron 服务。 + +### 第一步：添加依赖 + +在您的 `build.gradle.kts` 中添加 Axeron API 和 Provider： + +```kotlin +dependencies { + implementation("com.github.fahrez182.AxManager:api:<最新版本>") + implementation("com.github.fahrez182.AxManager:provider:<最新版本>") +} +``` + +### 第二步：声明 Provider + +在您的 `AndroidManifest.xml` 中添加 `AxeronProvider`。这允许 AxManager 将 IPC binder 发送到您的应用程序。 + +```xml + +``` + +### 第三步：监听 Binder 并执行 + +使用 `Axeron.addBinderReceivedListenerSticky` 等待 AxManager 服务连接，然后使用 `Axeron.newProcess` 来运行命令。 + +```kotlin +import frb.axeron.api.Axeron + +// 监听与 AxManager 服务的连接状态 +Axeron.addBinderReceivedListenerSticky { + // 我们现在已连接到 AxManager！ + + // 直接执行命令 + val process = Axeron.newProcess("uname -r") + + // 读取输出 + process.inputStream.bufferedReader().useLines { lines -> + lines.forEach { println("输出: $it") } + } + + // 等待命令完成 + val exitCode = process.waitFor() + println("命令完成，退出码为: $exitCode") +} +``` From 227a37004b60ccb05101810a868fa0b2b6754146 Mon Sep 17 00:00:00 2001 From: kanaodnd <188126396+kanaodnd@users.noreply.github.com> Date: Fri, 10 Apr 2026 01:28:45 +0000 Subject: [PATCH 2/2] docs: add unified API integration guide in Indonesian Replaced individual integration documents with a single comprehensive guide (`Panduan_Dokumentasi_Integrasi_AxManager.md`) as requested. This guide explains how to execute elevated commands using both `Axerish + libsu` and the `Direct Axeron API`. --- Panduan_Dokumentasi_Integrasi_AxManager.md | 127 +++++++++++++++++++++ website/docs/.vitepress/config.mts | 2 - website/docs/guide/api-integration.md | 119 ------------------- website/docs/zh/guide/api-integration.md | 119 ------------------- 4 files changed, 127 insertions(+), 240 deletions(-) create mode 100644 Panduan_Dokumentasi_Integrasi_AxManager.md delete mode 100644 website/docs/guide/api-integration.md delete mode 100644 website/docs/zh/guide/api-integration.md diff --git a/Panduan_Dokumentasi_Integrasi_AxManager.md b/Panduan_Dokumentasi_Integrasi_AxManager.md new file mode 100644 index 0000000..f07f372 --- /dev/null +++ b/Panduan_Dokumentasi_Integrasi_AxManager.md @@ -0,0 +1,127 @@ +# Panduan Dokumentasi Integrasi AxManager + +AxManager memungkinkan aplikasi klien (pihak ketiga) untuk mengeksekusi perintah shell dan skrip dengan hak akses tinggi (Privilege - ADB/Root) melalui layanan AxManager. + +Ada dua cara utama yang bisa Anda gunakan untuk mengintegrasikan layanan ini agar bisa menjalankan perintah seperti `uname -r` dan sebagainya: + +1. **Menggunakan Axerish dengan libsu** (Direkomendasikan untuk aplikasi yang mengandalkan penggunaan shell standar) +2. **Menggunakan Axeron API Langsung** (Lebih mendasar, tanpa harus bergantung pada `libsu`) + +Berikut ini adalah langkah-langkah implementasinya: + +--- + +## 1. Menggunakan Axerish + libsu + +Axerish adalah *shell wrapper* bawaan AxManager yang akan otomatis menghubungkan aplikasi Anda ke antarmuka populer `libsu` buatan *topjohnwu*. Metode ini sangat mudah karena Anda bisa menggunakan gaya eksekusi `libsu` secara transparan namun berjalan di konteks AxManager. + +### Langkah 1: Persiapan Dependensi + +Tambahkan pustaka `libsu` dan Axeron API ke dalam file `build.gradle.kts` (pada tingkat *app*): + +```kotlin +dependencies { + // Pustaka libsu + implementation("com.github.topjohnwu.libsu:core:") + + // Axeron API + implementation("com.github.fahrez182.AxManager:api:") +} +``` + +### Langkah 2: Inisialisasi di dalam `Application` + +Buat atau modifikasi kelas `Application` kustom Anda untuk melakukan inisialisasi `Axerish` dan mengubah konfigurasi bawaan `Shell.Builder` milik `libsu` supaya diarahkan menggunakan Axerish. + +```kotlin +import android.app.Application +import com.topjohnwu.superuser.Shell +import frb.axeron.Axerish + +class MyApplication : Application() { + override fun onCreate() { + super.onCreate() + + // 1. Inisialisasi Axerish untuk aplikasi Anda + Axerish.initialize(packageName) + + // 2. Atur libsu untuk menggunakan eksekutor Axerish sebagai ganti 'su' atau 'sh' + Shell.setDefaultBuilder( + Shell.Builder.create() + .setCommands("sh", Axerish.axrun_path.absolutePath) + ) + } +} +``` + +### Langkah 3: Eksekusi Perintah + +Setelah terkonfigurasi, jalankan saja fungsi `Shell.cmd()` seperti biasa. Segala perintah akan diteruskan dan dieksekusi dengan *privilege* tinggi milik AxManager! + +```kotlin +import com.topjohnwu.superuser.Shell + +// Menjalankan perintah dengan hak akses tinggi (misal: cek kernel) +val result = Shell.cmd("uname -r").exec() + +if (result.isSuccess) { + println("Versi Kernel: ${result.out.joinToString("\n")}") +} +``` + +--- + +## 2. Menggunakan Axeron API Langsung + +Apabila Anda membutuhkan tingkat integrasi yang lebih mendalam, atau jika Anda memang tidak menggunakan pustaka `libsu`, Anda dapat langsung terhubung (*bind*) ke layanan IPC milik AxManager. + +### Langkah 1: Persiapan Dependensi + +Tambahkan pustaka Axeron API dan Axeron Provider di dalam file `build.gradle.kts` Anda: + +```kotlin +dependencies { + implementation("com.github.fahrez182.AxManager:api:") + implementation("com.github.fahrez182.AxManager:provider:") +} +``` + +### Langkah 2: Deklarasi Provider + +Tambahkan *provider* ini di dalam file `AndroidManifest.xml` aplikasi Anda. Hal ini dilakukan agar AxManager dapat mendeteksi aplikasi Anda dan mengirimkan koneksi (*IPC binder*) secara langsung. + +```xml + +``` + +### Langkah 3: Dengarkan Koneksi & Eksekusi Perintah + +Tunggu hingga layanan AxManager terkoneksi dengan memantau fungsi `Axeron.addBinderReceivedListenerSticky`, kemudian gunakan kelas `Axeron.newProcess` untuk menjalankan perintah yang diinginkan. + +```kotlin +import frb.axeron.api.Axeron + +// Dengarkan status koneksi ke layanan AxManager +Axeron.addBinderReceivedListenerSticky { + // Di sini aplikasi kita telah berhasil terhubung ke AxManager! + + // Eksekusi sebuah perintah secara langsung + val process = Axeron.newProcess("uname -r") + + // Membaca luaran/output secara stream + process.inputStream.bufferedReader().useLines { lines -> + lines.forEach { println("Output: $it") } + } + + // Tunggu proses perintah hingga tuntas + val exitCode = process.waitFor() + println("Perintah selesai dengan kode keluaran (exit code): $exitCode") +} +``` + +--- +*Catatan:* Pastikan untuk memperbarui kode `` pada bagian dependensi dengan versi rilis API yang mutakhir. diff --git a/website/docs/.vitepress/config.mts b/website/docs/.vitepress/config.mts index c56790f..5ea6a9b 100644 --- a/website/docs/.vitepress/config.mts +++ b/website/docs/.vitepress/config.mts @@ -29,7 +29,6 @@ export default defineConfig({ text: "What is Axeron Manager?", link: "/guide/what-is-axeron-manager", }, - { text: "API Integration", link: "/guide/api-integration" }, { text: "User Manual", link: "/guide/user-manual" }, { text: "FAQ", link: "/guide/faq" }, ], @@ -71,7 +70,6 @@ export default defineConfig({ text: "什么是 Axeron Manager？", link: "/zh/guide/what-is-axeron-manager", }, - { text: "API 集成", link: "/zh/guide/api-integration" }, { text: "用户手册", link: "/zh/guide/user-manual" }, { text: "常见问题", link: "/zh/guide/faq" }, ], diff --git a/website/docs/guide/api-integration.md b/website/docs/guide/api-integration.md deleted file mode 100644 index 47650a3..0000000 --- a/website/docs/guide/api-integration.md +++ /dev/null @@ -1,119 +0,0 @@ -# API Integration - -AxManager allows third-party client applications to execute shell commands with elevated privileges (ADB or Root) using the **Axeron API**. - -There are two primary methods for integrating AxManager into your app: -1. **Using Axerish with libsu** (Recommended for most apps that already use `libsu`) -2. **Using the Direct Axeron API** (Lower level, no `libsu` dependency) - ---- - -## 1. Using Axerish + libsu - -Axerish is a shell wrapper provided by AxManager that seamlessly integrates with the popular `libsu` library by topjohnwu. It allows your app to use AxManager's execution context transparently. - -### Step 1: Add Dependencies - -Add `libsu` and the Axeron API to your `build.gradle.kts`: - -```kotlin -dependencies { - implementation("com.github.topjohnwu.libsu:core:") - // Make sure to check GitHub releases for the latest version - implementation("com.github.fahrez182.AxManager:api:") -} -``` - -### Step 2: Initialize in Application - -In your custom `Application` class, initialize `Axerish` and set it as the default shell builder for `libsu`: - -```kotlin -import android.app.Application -import com.topjohnwu.superuser.Shell -import frb.axeron.Axerish - -class MyApplication : Application() { - override fun onCreate() { - super.onCreate() - - // 1. Initialize Axerish by passing your application's package name - Axerish.initialize(packageName) - - // 2. Configure libsu to use Axerish as its shell - Shell.setDefaultBuilder( - Shell.Builder.create() - .setCommands("sh", Axerish.axrun_path.absolutePath) - ) - } -} -``` - -### Step 3: Execute Commands - -Now you can use `Shell.cmd()` normally. The execution is automatically routed to AxManager's elevated environment! - -```kotlin -import com.topjohnwu.superuser.Shell - -// Run any command with elevated privileges -val result = Shell.cmd("uname -r").exec() - -if (result.isSuccess) { - println("Kernel version: ${result.out.joinToString("\n")}") -} -``` - ---- - -## 2. Using Direct Axeron API - -If your app requires lower-level integration or you prefer not to include the `libsu` library, you can bind directly to the Axeron service. - -### Step 1: Add Dependencies - -Add the Axeron API and Provider to your `build.gradle.kts`: - -```kotlin -dependencies { - implementation("com.github.fahrez182.AxManager:api:") - implementation("com.github.fahrez182.AxManager:provider:") -} -``` - -### Step 2: Declare the Provider - -Add the `AxeronProvider` to your app's `AndroidManifest.xml`. This enables AxManager to send the IPC binder to your application. - -```xml - -``` - -### Step 3: Listen for Binder & Execute - -Wait for the AxManager service to connect using `Axeron.addBinderReceivedListenerSticky`, and then use `Axeron.newProcess` to run commands. - -```kotlin -import frb.axeron.api.Axeron - -// Listen for the connection to the AxManager service -Axeron.addBinderReceivedListenerSticky { - // We are now connected to AxManager! - - // Execute a command directly - val process = Axeron.newProcess("uname -r") - - // Read the output - process.inputStream.bufferedReader().useLines { lines -> - lines.forEach { println("Output: $it") } - } - - // Wait for the command to finish - val exitCode = process.waitFor() - println("Command finished with exit code: $exitCode") -} -``` diff --git a/website/docs/zh/guide/api-integration.md b/website/docs/zh/guide/api-integration.md deleted file mode 100644 index 2a651b1..0000000 --- a/website/docs/zh/guide/api-integration.md +++ /dev/null @@ -1,119 +0,0 @@ -# API 集成 - -AxManager 允许第三方客户端应用程序使用 **Axeron API** 在提权环境（ADB 或 Root）下执行 Shell 命令。 - -目前有两种主要方法将 AxManager 集成到您的应用中： -1. **使用 Axerish 与 libsu**（推荐，适用于大多数已使用 `libsu` 的应用） -2. **直接使用 Axeron API**（底层方法，无需依赖 `libsu`） - ---- - -## 1. 使用 Axerish + libsu - -Axerish 是 AxManager 提供的一个 Shell 包装器，它可以无缝集成到流行的 `libsu` 库中。这使得您的应用可以透明地使用 AxManager 的执行环境。 - -### 第一步：添加依赖 - -在您的 `build.gradle.kts` 中添加 `libsu` 和 Axeron API： - -```kotlin -dependencies { - implementation("com.github.topjohnwu.libsu:core:<最新版本>") - // 请在 GitHub Releases 页面查看最新版本 - implementation("com.github.fahrez182.AxManager:api:<最新版本>") -} -``` - -### 第二步：在 Application 中初始化 - -在您自定义的 `Application` 类中，初始化 `Axerish` 并将其设置为 `libsu` 的默认 Shell 构建器： - -```kotlin -import android.app.Application -import com.topjohnwu.superuser.Shell -import frb.axeron.Axerish - -class MyApplication : Application() { - override fun onCreate() { - super.onCreate() - - // 1. 传入您的应用包名来初始化 Axerish - Axerish.initialize(packageName) - - // 2. 配置 libsu 以使用 Axerish 作为其 Shell - Shell.setDefaultBuilder( - Shell.Builder.create() - .setCommands("sh", Axerish.axrun_path.absolutePath) - ) - } -} -``` - -### 第三步：执行命令 - -现在您可以像往常一样使用 `Shell.cmd()`。所有的执行命令都会自动路由到 AxManager 的提权环境中！ - -```kotlin -import com.topjohnwu.superuser.Shell - -// 运行具有提升权限的任何命令 -val result = Shell.cmd("uname -r").exec() - -if (result.isSuccess) { - println("内核版本: ${result.out.joinToString("\n")}") -} -``` - ---- - -## 2. 直接使用 Axeron API - -如果您的应用需要更底层的集成，或者您不想引入 `libsu` 库，您可以直接绑定到 Axeron 服务。 - -### 第一步：添加依赖 - -在您的 `build.gradle.kts` 中添加 Axeron API 和 Provider： - -```kotlin -dependencies { - implementation("com.github.fahrez182.AxManager:api:<最新版本>") - implementation("com.github.fahrez182.AxManager:provider:<最新版本>") -} -``` - -### 第二步：声明 Provider - -在您的 `AndroidManifest.xml` 中添加 `AxeronProvider`。这允许 AxManager 将 IPC binder 发送到您的应用程序。 - -```xml - -``` - -### 第三步：监听 Binder 并执行 - -使用 `Axeron.addBinderReceivedListenerSticky` 等待 AxManager 服务连接，然后使用 `Axeron.newProcess` 来运行命令。 - -```kotlin -import frb.axeron.api.Axeron - -// 监听与 AxManager 服务的连接状态 -Axeron.addBinderReceivedListenerSticky { - // 我们现在已连接到 AxManager！ - - // 直接执行命令 - val process = Axeron.newProcess("uname -r") - - // 读取输出 - process.inputStream.bufferedReader().useLines { lines -> - lines.forEach { println("输出: $it") } - } - - // 等待命令完成 - val exitCode = process.waitFor() - println("命令完成，退出码为: $exitCode") -} -```