Shizuku-API

The API and the developer guide for Shizuku and Sui.

The concept is "same API, different implementation", Shizuku and Sui shares the API design. As the application developer, you only need to write the code once to support both Shizuku and Sui.

Requirements

To use apps using Shizuku API, the user needs to install Shizuku or Sui first.

Sui

• Requires two Magisk modules, "Riru" and "Riru - Sui"

Shizuku

• Requires root or adb
• For adb, it's required to manually restart with adb every time on boot
• For adb, of course, only has limited permissions of adb
• Requires the user to install a standalone app, Shizuku

Make a choice

For root-only apps, continue to support the old school "su" or not, you may have to make this choice.

Since Sui is possible to be bundled in Magisk in the future (Riru is already in Magisk), abandon old school "su" is not a bad choice.

For existing applications, there is an API that allows you to create a "sh" as root (or adb), so you can always do what was previously possible.

Migrating from "su"

• Simple applications which only use commands like pm am

Use "Remote binder call".

• Complicated applications such as root file managers

Use "User service".

• Complicated applications which heavily depend on commands in Linux world

Use "User service" with JNI or continue to use shell.

Guide

Note, something is not mentioned below, please be sure to read the demo.

Add dependency

def shizuku_version = '11.0.3'
implementation "dev.rikka.shizuku:api:$shizuku_version"

// Add this line if you want to support Shizuku
implementation "dev.rikka.shizuku:provider:$shizuku_version"

Since all root users using Shizuku will eventually switch to Sui, if your application requires root, it's better not to support Shizuku from the begining.

Acquire the Binder

The only API difference of Shizuku and Sui is the method of acquiring the Binder. If this step is not done, methods from Shizuku class will throw a IllegalStateException with "binder haven't been received".

Sui

Call Sui.init(packageName) before using Shizuku class. This method only needs to be called once.

If this method returns true, means Sui is installed and available. If not, Sui maybe not installed or the user hide the application in Sui.

For multi-process applications, call this method in every process which needs to use Shizuku API.

Shizuku

DO NOT this if your app only supports Sui.

Add ShizukuProvider to AndroidManifest.xml.

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

For multi-process applications, call ShizukuProvider.enableMultiProcessSupport( /* is current process the same process of ShizukuProvider's */ ) in every process which needs to use Shizuku API.

Request permission

Requesting the permission of Shizuku/Sui is similar to requesting runtime permissions. The only difference is you need to use methods from Shizuku class. See demo for more.

Use

See demo.

Introduction

First of all, please read the README of Shizuku and Sui, so that you will have a basic understanding of how Shizuku and Sui works.

The most important functions provided by Shizuku API is "remote binder call" and "user service".

Remote binder call

Call any Android APIs which uses binder (such as getInstalledPackages) as the identity of root (or adb).

User service

Similar to Bound services, but the service runs as the identity of root (or adb). JNI is also supported.

Changelog

12.1.0

• Automatically initialize Sui if you are using Shizuku

You can opt-out this behavior by calling ShizukuProvider#disableAutomaticSuiInitialization() before ShizukuProvider#onCreate() is called

• Add a lot more detailed document for most APIs
• Drop pre-v11 support

You don't need to worry about this problem, just show a "not supported" message if the user really uses pre-v11.

• Sui was born after API v11, Sui users are not affected at all.
• For Shizuku, according to Google Play statistics, more than 95% of users are on v11+. Shizuku drops Android 5 support from v5, many of the remaining 5% are such people who stucking at super old versions.
• A useful API, UserService, is added from v11 and stable on v12. I belive that many Shizuku apps already have a "version > 11" check.
• I really want to drop pre-v11 support since a possible system issue that may cause system soft reboot (system server crash) on uninstalling Shizuku.

12.0.0

• Add Shizuku#peekUserService that allows you to check if a specific user service is running
• Add Shizuku.UserServiceArgs#daemon that allows you to control if the user service should be run in the "Daemon mode"

Migration guide for existing applications use Shizuku pre-v11

Click to expand

Changes

• Dependency changed (see Guide below)
• Self-implemented permission is used from v11, the API is same to runtime permission (see demo, and existing runtime permission still works)
• Package name is rename to rikka.shizuku (replace all moe.shizuku.api. to rikka.shizuku.)
• ShizukuService class is renamed to Shizuku
• Methods in Shizuku class now throw RuntimeException rather than RemoteException like other Android APIs
• Listeners are moved from ShizukuProvider class to Shizuku class

Add support for Sui

• Call Sui#init()
• It's better to use check Sui with Sui#isSui before using Shizuku only methods in ShizukuProvider