Skip to main content

Android Host Service

info

This documentation is for Android SDK 2.1.x

Host Service lets the host application register named native functions that journey JavaScript can call with await HostService.invokeFunction(name, args, callbacks). It also provides host-side utilities such as the image picker.

Functions​

registerFunction​

fun registerFunction(
    name: String,
    handler: HostFunctionHandler
): Unit

Registers a named host function callable from journey JavaScript as await HostService.invokeFunction(name, args, callbacks). Re-registering the same name replaces the previous handler and logs a warning.

Parameters:

  • name: String — Unique function name as seen from JavaScript.
  • handler: HostFunctionHandler — Invoked when a script calls this function, see HostFunctionHandler.

unregisterFunction​

fun unregisterFunction(name: String): Unit

Removes a registered host function. No-op if not present.

Parameters:

  • name: String — Name of the function to remove.

cancelAllFunctions​

fun cancelAllFunctions(reason: String = "journey_cancelled"): Unit

Rejects every in-flight HostService.invokeFunction call with the given reason. Called when the journey hosting the JavaScript runtime is dismissed or cancelled.

Parameters:

  • reason: String — Rejection reason delivered to the scripts. Defaults to "journey_cancelled".

pickImage​

fun pickImage(
    activity: Activity,
    source: ImagePickerSource = ImagePickerSource.CHOOSE,
    maxCount: Int = 1,
    maxWidth: Int = 512,
    maxHeight: Int = 512,
    quality: Double = 0.7,
    onSuccess: (List<String>) -> Unit,
    onError: (Throwable) -> Unit
): Unit

Presents the system image picker (gallery, camera, or a chooser), resizes the selected images, and returns their local file paths.

Parameters:

  • activity: Activity — Activity used to present the picker UI.
  • source: ImagePickerSource — Image source, see ImagePickerSource. Defaults to CHOOSE.
  • maxCount: Int — Maximum number of images the user can select. Defaults to 1.
  • maxWidth: Int — Maximum width of the resized images. Defaults to 512.
  • maxHeight: Int — Maximum height of the resized images. Defaults to 512.
  • quality: Double — JPEG compression quality between 0 and 1. Defaults to 0.7.
  • onSuccess: (List<String>) -> Unit — Called with local file paths of the processed images.
  • onError: (Throwable) -> Unit — Called when picking fails or the user cancels.

Classes​

HostFunctionHandler​

typealias HostFunctionHandler = (
    args: HostFunctionArgs,
    callbacks: HostCallbacks,
    resolve: (Any?) -> Unit,
    reject: (String) -> Unit,
) -> Unit

Handler signature registered with Host Service. Exactly one of resolve / reject must be called: resolve fulfills the script's promise with the given value, reject rejects it with the given message.

HostFunctionArgs​

class HostFunctionArgs(
    val raw: Map<String, Any?>,
) {
    operator fun get(key: String): Any?
    inline fun <reified T> value(key: String): T?
    inline fun <reified T> require(key: String): T
    inline fun <reified T> decode(key: String): T
}

Wraps the JSON args map delivered to a host function handler. value returns the value cast to T or null; require throws HostFunctionError if absent or the wrong type; decode deserializes a JSON-compatible field into a typed object.

HostCallbacks​

class HostCallbacks {
    fun call(name: String, value: Any? = null)
    fun has(name: String): Boolean
}

Proxy passed to host handlers for the callback functions the script supplied. call fires a named callback with an optional value (no-op if the script did not provide it); has returns whether the script provided a callback with this name.

HostFunctionError​

sealed class HostFunctionError(message: String) : Exception(message) {
    class InvalidArgs(detail: String) : HostFunctionError("invalid_args: $detail")
}

Errors a host function handler can throw before invoking resolve/reject.

ImagePickerSource​

enum class ImagePickerSource {
    GALLERY,
    CAMERA,
    CHOOSE,
}