HostService

Script-engine API for calling into the host application. The host app registers native functions with its platform SDK (see the Host Service API Reference); scripts call them by name through HostService.invokeFunction. Available in Journey Script steps, Journey Screen HTML, Rule script actions and Script-sourced MeData Definitions.

Functions

invokeFunction

HostService.invokeFunction(
    name: string,
    args?: object,
    callbacks?: object
): Promise<any>

Calls the host function registered under name and resolves with whatever the host passes to resolve. The Promise stays pending until the host settles the call, so a host handler that presents a native flow (payment, login, KYC) can take as long as it needs; the script simply awaits.

Parameters:

• name: string — Name the host app used in registerFunction.
• args?: object — Plain JSON object handed to the host handler. Defaults to {}. Functions, Date objects and other non-JSON values are not transferred.
• callbacks?: object — Object whose function-valued properties become named channels the host can fire while the call is in flight, e.g. { onProgress: (p) => … }. The host fires them with callbacks.call(name, value); a callback the script did not provide is a no-op on the host side.

Returns: a Promise resolving to the JSON-shaped value the host passed to resolve, or null when the host resolved with nothing. It rejects with an Error whose message is:

message	When
host_function_not_registered: <name>	No host function with that name is registered.
invalid_args: missing name	name is empty.
the string the host passed to reject	The host rejected the call.
journey_cancelled (or the reason given to cancelAllFunctions)	The journey was dismissed while the call was in flight.
Host function '<name>' did not settle within 60000 ms	Android only, Script steps only: the host neither resolved nor rejected within 60 seconds.

try {
  const cart = await HostService.invokeFunction("getShoppingCart");
  JourneyContext.putValue("cartTotal", cart.total);
  onSuccess(true);
} catch (err) {
  onError(err);
}

Passing arguments and listening to progress:

try {
  const result = await HostService.invokeFunction(
    "uploadDocument",
    { path: JourneyContext.getValue("documentPath") },
    { onProgress: (p) => console.log("upload " + p + "%") }
  );
  onSuccess(result.ok);
} catch (err) {
  onError(err);
}

Handling a missing registration without failing the step:

try {
  await HostService.invokeFunction("applyCoupon", { code: "WELCOME10" });
} catch (err) {
  if (err.message.indexOf("host_function_not_registered") === 0) {
    console.log("host app does not support coupons, continuing");
  } else {
    throw err;
  }
}
onSuccess(true);

pickImage

HostService.pickImage(
    options?: PickImageOptions
): Promise<string[]>

Presents the system image picker, resizes the selected images and resolves with their local file paths. Rejects with an error message string when the user cancels or processing fails.

Parameters:

• options?: PickImageOptions — Picker options, see PickImageOptions. All fields are optional.

const paths = await HostService.pickImage({ source: "camera", maxWidth: 1024, maxHeight: 1024 });
JourneyContext.putValue("photoPath", paths[0]);

Platform availability

On iOS pickImage is available in Script steps and Screen HTML. On Android it is available in Screen HTML only.

getHost

HostService.getHost(): Promise<Host>

Returns the identifiers the SDK uses for this installation, see Host.

Parameters: None.

Platform availability

On iOS getHost is available in Script steps and Screen HTML. On Android it is available in Screen HTML only.

Classes

PickImageOptions

{
  source?: "gallery" | "camera" | "choose", // defaults to "choose", which lets the user pick
  maxCount?: number,                        // maximum number of images, defaults to 1
  maxWidth?: number,                        // resize bound in pixels, defaults to 512
  maxHeight?: number,                       // resize bound in pixels, defaults to 512
  quality?: number                          // JPEG quality between 0 and 1, defaults to 0.7
}

Host

{
  deviceID: string,       // SDK-generated identifier of this installation
  hostID: string | null   // identifier assigned by the host app, null when none is set
}