Skip to main content

Host Service

DataSapien services are callable from journey JavaScript — Host Service makes the integration work in the other direction too. The host application registers its own native functions (shopping cart, payment, profile, navigation, ...) and journey scripts call them like any other service function. This turns Journeys from isolated flows into flows that can read from and act on your app.

How It Works​

The host app registers a named function once:

DataSapien.getHostService().registerFunction("getShoppingCart") { args, callbacks, resolve, reject in
    resolve(["items": ShoppingCart.shared.items, "total": ShoppingCart.shared.total])
}

Journey JavaScript — both in Script steps and in JS embedded in Screen step HTML — calls it through a single global:

const cart = await HostService.invokeFunction("getShoppingCart");
  • args — a plain JSON object of values passed from the script to the handler.
  • callbacks — an optional object of functions; each becomes a named channel the host can fire during the call.
  • The handler completes the call with exactly one of resolve(value) / reject(message): resolve fulfills the script's promise with a JSON-shaped value, reject turns into a JavaScript Error.
  • await suspends the script step until the host resolves — no special pause/resume mechanism is needed, however long the host side takes.

If the journey is dismissed while calls are in flight, the SDK rejects them (cancelAllFunctions), so the host never resolves into a dead screen.

Use Cases​

The same primitive supports four shapes of host integration:

Reading Data from the App​

The journey needs something only the app knows — the cart contents, the logged-in user's tier, the current screen context. The handler reads it and resolves immediately:

const cart = await HostService.invokeFunction("getShoppingCart");
console.log("cart total: " + cart.total);

The journey can then personalize its flow on real app state — for example skipping a step if the cart is empty.

Triggering an Action in the App​

The journey asks the app to do something — add a product to the cart, apply a coupon, toggle a setting. Arguments go in, an acknowledgment comes back:

await HostService.invokeFunction("addToCart", { productId: "sku-123", quantity: 1 });

Handing Over to a Native Flow​

The journey hands control to a full native experience — a payment sheet, a KYC flow, a login screen. The handler presents the UI and calls resolve only when the flow finishes; the journey stays suspended at await and continues with the result:

const receipt = await HostService.invokeFunction("gotoPayment", { amount: 49.90 });

On the host side, resolve is simply called from the payment flow's completion handler — minutes later if needed.

Streaming Progress Back to the Journey​

For long operations the host can fire named callbacks during the call and resolve at the end. The script passes functions in the third argument; the handler fires them with callbacks.call(name, value):

const result = await HostService.invokeFunction("uploadDocument", { path: doc }, {
  onProgress: (p) => console.log("upload " + p + "%")
});

Firing a callback the script did not provide is a safe no-op, so the host can always report progress without knowing what the script listens to.

Host Service Functions​

To access HostService functions, get its instance from the DataSapien object: DataSapien.getHostService().

See the full function list per platform in the Host Service API Reference.