API 使用指南

dependencies {
    implementation "dev.rikka.shizuku:api:13.1.5"
    implementation "dev.rikka.shizuku:provider:13.1.5"
}

// settings.gradle
include ':aidl', ':shared', ':api', ':provider'
project(':aidl').projectDir = file('api/aidl')
project(':shared').projectDir = file('api/shared')
project(':api').projectDir = file('api/api')
project(':provider').projectDir = file('api/provider')

// app/build.gradle
dependencies {
    implementation project(':api')
    implementation project(':provider')
}

<application ...>

    <provider
        android:name="rikka.shizuku.ShizukuProvider"
        android:authorities="${applicationId}.shizuku"
        android:multiprocess="false"
        android:exported="true"
        android:permission="android.permission.INTERACT_ACROSS_USERS_FULL" />

</application>

// 收到 binder（sticky：注册时若 binder 已在，会立刻回调一次）
Shizuku.addBinderReceivedListenerSticky(() -> {
    // binder 可用，可以开始 checkSelfPermission / bindUserService 了
});

// binder 死亡（用户停掉了 Shizako 服务、设备重启等）
Shizuku.addBinderDeadListener(() -> {
    // 提示用户重新启动服务，禁用相关功能入口
});

if (Shizuku.pingBinder()) {   // 轻量探测，binder 存活且可用
    ...
}
IBinder b = Shizuku.getBinder(); // 拿原始 binder（transactRemote 高级用法才需要）

if (Shizuku.checkSelfPermission() == PackageManager.PERMISSION_GRANTED) {
    // 已授权，直接干活
} else if (Shizuku.shouldShowRequestPermissionRationale()) {
    // 用户之前拒绝过，先解释一下你要用特权干嘛
} else {
    Shizuku.requestPermission(requestCode); // 弹出 Shizako 的授权对话框
}

Shizuku.addRequestPermissionResultListener((requestCode, result) -> {
    if (resultCode == PackageManager.PERMISSION_GRANTED) { ... }
});

package com.example.myapp;

interface IHelperService {

    // Shizuku 服务端保留的销毁方法，事务码必须一致
    void destroy() = 16777114;

    // 以下是你自己的方法，事务码从 1 开始编号
    String whoami() = 1;
    int installApk(String apkPath) = 2;
}

package com.example.myapp;

import android.content.Context;
import android.os.RemoteException;
import android.system.Os;

import androidx.annotation.Keep;

public class HelperService extends IHelperService.Stub {

    // 必须保留无参构造器
    public HelperService() {}

    // API v13 起支持带 Context 的构造器（需 @Keep 防 ProGuard 混淆删除）
    @Keep
    public HelperService(Context context) {
        // 这个 context 是以特权身份 createPackageContextAsUser 出来的
    }

    @Override
    public void destroy() {
        System.exit(0); // 服务端要求：destroy 即退出进程
    }

    @Override
    public String whoami() throws RemoteException {
        // 在特权进程里执行！uid 是 2000(adb) 或 0(root)
        return "uid=" + Os.getuid() + ", pid=" + Os.getpid();
    }

    @Override
    public int installApk(String apkPath) throws RemoteException {
        // 这里跑的是特权代码：pm install、am、settings……
        Process p;
        try {
            p = Runtime.getRuntime().exec(new String[]{"pm", "install", "-r", apkPath});
            return p.waitFor();
        } catch (Exception e) {
            throw new RemoteException(e.toString());
        }
    }
}

private final UserServiceArgs serviceArgs = new Shizuku.UserServiceArgs(
        new ComponentName("com.example.myapp", "com.example.myapp.HelperService"))
        .processNameSuffix("helper")   // 进程名变成 com.example.myapp:helper
        .version(BuildConfig.VERSION_CODE) // 服务代码变了就换个号，服务端会重建进程
        .debuggable(BuildConfig.DEBUG)
        .daemon(true);                     // 见下文

private final ServiceConnection serviceConnection = new ServiceConnection() {
    @Override
    public void onServiceConnected(ComponentName name, IBinder service) {
        IHelperService helper = IHelperService.Stub.asInterface(service);
        // 现在可以跨进程调特权方法了
        String s = helper.whoami();
    }

    @Override
    public void onServiceDisconnected(ComponentName name) {
        // 特权进程死了（stopService / 服务端被杀）
    }
};

// 绑定（内部会先检查权限，未授权会抛 SecurityException）
Shizuku.bindUserService(serviceArgs, serviceConnection);

// 解绑；第三个参数 true 表示同时让服务端销毁这个特权进程
Shizuku.unbindUserService(serviceArgs, serviceConnection, true);

// 只探测服务是否已在运行，不创建：返回 code 见 UserService 泛型常量
int code = Shizuku.peekUserService(serviceArgs, serviceConnection);

public class ShizakoHelper {

    public interface Callback {
        void onReady();
        void onNeedUser(String reason); // 引导用户去启动/授权
    }

    public static void connect(Context context, Callback cb) {
        Shizuku.addBinderReceivedListenerSticky(() -> {
            if (Shizuku.checkSelfPermission() == PackageManager.PERMISSION_GRANTED) {
                cb.onReady();
            } else {
                Shizuku.addRequestPermissionResultListener((requestCode, result) -> {
                    if (result == PackageManager.PERMISSION_GRANTED) cb.onReady();
                    else cb.onNeedUser("授权被拒绝");
                });
                Shizuku.requestPermission(101);
            }
        });

        Shizuku.addBinderDeadListener(() ->
                cb.onNeedUser("Shizako 服务未运行"));
    }
}