Skip to main content

Journey Service

Journey Service is the main entry point for extending your application's capabilities with Journeys. It keeps the list of published Journeys that target this device in sync with the Orchestrator, lets you query and display them in your app, executes them with a single function call, and — when a Journey explicitly requests it — submits the resulting Zero-Party Data back to the Orchestrator.

Journey Structure​

A Journey is a flow of steps authored on the Orchestrator. Each step can be one of:

  • Screen Step: Screens are defined by a JSON structure that contains an array of UI elements. View-oriented elements support Markdown for rich text and can display variables from Journey Context produced by previous steps. Input-oriented elements (text inputs, radio / check boxes, buttons etc.) bind user input to variables inside Journey Context to be consumed by following steps.
  • Question Step: Displays an answer screen for a question. The answer becomes available in the Journey Context.
  • Script Step: Contains a script authored in JavaScript. Scripts have access to the Journey Context, Mobile SDK Services and external web APIs via Managed APIs.
  • MeData Step: Accesses / collects MeData via MeData Service and sets the values into the Journey Context for the rest of the Journey.

The whole Journey UI is rendered by the Mobile SDK in a WebView, either full screen (runJourney) or inside a view you provide (runJourneyEmbedded). Screens are fully stylable on the Orchestrator to match your design system, so starting a Journey is a single function call in your host application.

tip

Style your Journey screens on the DataSapien Orchestrator to match your host application. No UI code is required in the host app.

Journey Lifecycle​

  1. A Journey is created and published on the Orchestrator, where its steps, screens and Audience targeting are defined.
  2. The Mobile SDK synchronizes published Journeys to the device (via DataSapien.setup or syncJourneys).
  3. The host application runs the Journey; the SDK renders the UI and executes each step in the flow.
  4. On completion, values collected by MeData steps are saved or updated in the on-device Data Vault.
  5. If the Journey has a ZPD request, the requested values are pushed to the Orchestrator; otherwise nothing leaves the device.

Use Cases​

Discovering Journeys​

Journey definitions are synchronized from the Orchestrator by DataSapien.setup on every launch. If you need a fresher list while the app is running (for example on pull-to-refresh), call syncJourneys explicitly.

To query the locally stored Journeys use getJourneys. Three filters shape the result:

  • tags — Journeys are tagged on the Orchestrator. Use tags to route different Journeys to different surfaces of your app: e.g. a home-carousel tag for the home screen, a campaigns tag for the campaigns page.
  • statuses — Filter by execution state (NOT_STARTED, COMPLETED, SENT). Query NOT_STARTED to show only new Journeys, or COMPLETED / SENT for a "history" section.
  • onlyInAudience — When true, only Journeys whose Audience currently includes this device are returned. This is how Orchestrator-side targeting reaches the device; the audience evaluation happens locally against the on-device data. Pass false to list all Journeys on the device regardless of Audience targeting.
DataSapien.getJourneyService().getJourneys(
    tags: ["home-carousel"],
    statuses: [.notStarted],
    onlyInAudience: true,
    onSuccess: { journeys in
    },
    onError: { error in
    }
)

Displaying a Journey​

There are two ways to display a Journey:

  • runJourney — the SDK presents the Journey UI full screen over your current screen. This is the simplest option: one function call, no layout work.
  • runJourneyEmbedded — the SDK renders the Journey inside a container view you provide, so the Journey lives within your own screen layout (for example as a section of a page).

In both cases the SDK drives the whole flow and the same completion callbacks apply.

Running a Journey and Handling Completion​

Start a Journey with runJourney. The SDK presents the Journey UI, drives the flow, and returns the final Journey Context when the user completes the last step:

DataSapien.getJourneyService().runJourney(
    self,                            // presenting UIViewController
    name: "onboarding_journey",
    data: ["customerTier": "gold"],  // optional initial Journey Context values
    onSuccess: { journeyContext in
        // Journey completed. journeyContext contains all values
        // produced during the flow (answers, script outputs, etc.)
    },
    onError: { error in
        // Journey failed or was interrupted
    }
)

The optional data parameter seeds the Journey Context, so your host app can pass values (user tier, entry point, etc.) that steps and scripts inside the Journey can read.

When the user completes a Journey:

  1. An execution record is persisted on device. You can read it later with getLastJourneyExecutionRecord or getJourneyExecutionRecords — for example to grant a reward once, or to show the answers a user gave.
  2. The Journey's status changes to COMPLETED (and to SENT after a Zero-Party Data submission, see below).
  3. onSuccess is called with the final Journey Context, so the host app can react immediately — unlock a feature, navigate to a screen, show a thank-you state.

Zero-Party Data (ZPD) Submission​

By default everything a Journey produces stays on the device. A Journey shares data with your backend only if it was explicitly configured on the Orchestrator to request specific values — this is the Journey's ZPD request.

When a Journey with a ZPD request is completed:

  1. The SDK takes only the requested values from the final Journey Context. Nothing else — neither other context values nor anything from the Data Vault — is included.
  2. After a successful submission the execution record is marked as SENT.

For Journeys with a ZPD request, onSuccess fires after the submission completes, so a successful callback means the data has reached the Orchestrator.

This is the consent-first model of DataSapien: the user sees and produces the data inside the Journey, and only the values the Journey was authored to request ever leave the device.

Journey Service Functions​

To access JourneyService functions, get its instance from the DataSapien object: DataSapien.getJourneyService().

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