Download

Start

How extensions work

These pages show how to write one with the Katari SDK and offer it in an extension store of your own.

What an extension is #

An extension is an Android app with no screens. Katari finds it among the installed apps, loads its code, and asks it for sources. On Linux, Katari converts the APK when it installs it and runs its code on stand-ins for the parts of Android it uses. A source is one site, usually in one language, and Katari calls these methods on it:

suspend fun getPopularContent(page: Int): EntryPageResult<SEntry>
For the source's Popular list, one page at a time.
suspend fun getLatestUpdates(page: Int): EntryPageResult<SEntry>
For the source's Latest list, one page at a time.
suspend fun getSearchContent(page: Int, query: String, filters: EntryFilterList): EntryPageResult<SEntry>
For a search in the source, with the user's filters.
suspend fun refresh(entry: SEntry, existingChapters: List<SEntryChapter>, fetchDetails: Boolean, fetchChapters: Boolean): EntryRefresh
When a title's page opens or is refreshed, for its details, its chapters or both, and when library updates look for new chapters.
suspend fun getMedia(chapter: SEntryChapter, selection: PlaybackSelection = PlaybackSelection()): EntryMedia
When a chapter or episode opens or is downloaded.

The source covers each of them. One source can serve comics, video and books, even mixed in one list, since every title it returns says which kind it is.

The SDK #

Extensions are written in Kotlin against the Katari SDK. Latest published version is 4.0.0. It is published on JitPack from the sdk-4.0.0 tag of Katari's repository:

The SDK changelog lists what each release added, and every interface and field is also documented where the SDK declares it.

Which Katari loads it #

An extension's versionName is the SDK's major and minor version, a dot, and the extension's own release number: 4.0.4 is the fourth release of an extension built with SDK 4.0. Unless the manifest names the SDK in tachiyomix.extensionLib, Katari reads everything before the last dot as the SDK, so a versionName of 4.0 alone reads as SDK 4 and isn't loaded.

Katari loads extensions built with SDK 4.0, whatever their patch version. SDK 4.0 moved the book classes to a new package, so an extension built with SDK 3.x shows under Not loaded until it is rebuilt. One built with a newer SDK shows there as Unsupported SDK until the user updates Katari.

Building with the SDK that has what you need, and no newer, keeps the extension working on the most copies of Katari.

Katari also loads Mihon and Tachiyomi extensions built with extensions-lib 1.6, Aniyomi extensions built with their extensions-lib 14, 16 or 17, and LNReader plugins for lnreader-plugins 3.0. Extension compatibility is the same list for users.

What users see before it runs #

An extension runs inside Katari with all of its access, so Katari checks every one before loading it. It is trusted straight away when one of the keys its APK is signed with is the key of an extension store the user added. Otherwise the user has to trust it, and Katari remembers that for this package, version code and key only, so each update asks again.

Under Browse › Extensions, an extension that fails a check is listed under Not loaded. Katari checks in this order and stops at the first that fails:

Reason Cause
Unreadable A private APK, installed by Katari itself, that couldn't be read.
Missing information The APK has no meta-data or no versionName.
Torrents only An Aniyomi extension whose manifest says it finds episodes as torrents, which Katari can't play.
Unsupported SDK The SDK, read from tachiyomix.extensionLib or else from the versionName, isn't one this Katari loads, as above.
Unsigned The APK has no signature.
Untrusted No store's key signs it and the user hasn't trusted this version. The user selects the shield and Trust.
Filtered Its content warning isn't among Allowed content warnings under Settings › Browse. All are allowed at first, and installed extensions are filtered only while Also apply to installed extensions is on.
Missing information The manifest has no tachiyomi.extension.class.
Failed Creating one of its classes or sources threw. The extension's info button shows the error and its stack trace, which also go to adb logcat on Android, and on Linux to standard error and ~/.local/state/katari/logs/katari.log.
LinuxNot on desktop yet It uses a class or member of Android that Katari doesn't provide on Linux yet. The info button names it. The extension still loads on Android.
Conflict Other installed extensions already provide all of its sources. See a source's id.

Unsupported SDK, Torrents only, Untrusted, Filtered and Conflict are labelled in the list; the info button explains the others. Publish an extension store shows how to sign extensions so that users of your store never see Untrusted.