Skip to main content

iOS Host Service

info

This documentation is for iOS 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​

public func registerFunction(
    _ name: String,
    handler: @escaping HostFunctionHandler
)

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​

public func unregisterFunction(_ name: String)

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

Parameters:

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

cancelAllFunctions​

public func cancelAllFunctions(reason: String = "journey_cancelled")

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​

public func pickImage(
    source: ImagePickerSource = .choose,
    maxCount: Int = 1,
    maxWidth: Int = 512,
    maxHeight: Int = 512,
    quality: Double = 0.7,
    onSuccess: @escaping ([String]) -> Void,
    onError: ((Error) -> Void)? = nil
)

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

Parameters:

  • 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: ([String]) -> Void — Called with local file paths of the processed images.
  • onError: ((Error) -> Void)? — Called when picking fails or the user cancels.

Classes​

HostFunctionHandler​

public typealias HostFunctionHandler = (
    _ args: HostFunctionArgs,
    _ callbacks: HostCallbacks,
    _ resolve: @escaping (Any?) -> Void,
    _ reject: @escaping (String) -> Void
) -> Void

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​

public struct HostFunctionArgs {
    public let raw: [String: Any]

    public subscript(key: String) -> Any? { get }
    public func value<T>(_ key: String) -> T?
    public func require<T>(_ key: String) throws -> T
    public func decode<T: Decodable>(_ key: String, as type: T.Type = T.self) throws -> T
}

Wraps the JSON args dictionary delivered to a host function handler. value returns the value cast to T or nil; require throws HostFunctionError if absent or the wrong type; decode decodes a JSON-compatible field into a Decodable type.

HostCallbacks​

public final class HostCallbacks {
    public func call(_ name: String, _ value: Any? = nil)
    public func has(_ name: String) -> Bool
}

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​

public enum HostFunctionError: Error {
    case invalidArgs(String)
}

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

ImagePickerSource​

public enum ImagePickerSource: String {
    case gallery
    case camera
    case choose
}