Skip to main content

Journey Service

Journey Service is the main entry point for extending your applications's capabilities with Journeys & Exchanges.

Journey & Exchange Execution​

Journey Service lets querying available Journeys & Exchanges that this SDK instance was targeted by (via their Audience selection).

Execution of a Journey (or an Exchange which is a lightweight Journey) requires running its steps. Eeach step can be one of:

  • Screen Step: Screens are defined by a JSON structure that contains array of UI elements inside. There are two main types of UI components: view and input oriented.
    • View oriented UI elements support Markdown for rich text format and allow displaying variables from Journey Context that were produced by previous steps in the Journey.
    • Input oriented UI elements are various and standard set of inputs including single / multiline text input, radio / check boxes, buttons etc are available. Input from these UI elements can be bind to variables from Journey Context to be consumed by following steps in the Journey.
  • Script Step: Contains a script authored in JavaScript. Scripts have access to Journey Context, Mobile SDK Services and subset of standard JavaScript APIs such as Fetch API.
  • MeData Step: These steps allow accesing / collecting MeData via MeData Service and set their value to Journey Context to be available for rest of the Journey.

Mobile SDK Provided UI​

When Journey / Exchange execution is fully delegated to Mobile SDK; whole UI of the Journey is displayed using WebView. Screens displayed by Screen Steps are fully stylable to match your native screens and design system inplace perfectly.

With Mobile SDK provided UI it is enough for your host application to start the execution with a single function call.

tip

We recommend using Mobile SDK Provided UI and styling screens on DataSapien Orchestrator to match your host application.

Host App Provided UI​

If you do not wish to use WebView based UI provided by Mobile SDK, you can choose to do all UI display in your host application. The data underlying a Journey or Exchange is an XML document that describes its steps and step contents in BPMN format.

In case you want to provide your own UI in your host app:

  • You must request the Execution object from Journey Service which provides access to underlying BPMN XML.
  • Parse XML according to BPMN spec considering DataSapien extensions, one of those extensions are JSON based screen definitions.
  • For Screen Steps you should develop a mechanism to display UI elements according to JSON screen definition and provide their interactions with Journey Context.
  • Drive execution steps using the Execution object functions.

Journey Service Functions​

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

Fetch Journeys​

Journeys Fetch
// Signature
public func fetchJourneys(
    onSuccess: @escaping ([Journey]) -> Void,
    onError: ((Error) -> Void)? = nil

// Usage
DataSapien.getJourneyService().fetchJourneys { journeys in
    
} onError: { error in
    
}
Journeys Fetch by tag
// Signature
public func getJourneysByTag(
    tag: String,
    onSuccess: @escaping ([Journey]) -> Void,
    onError: ((Error) -> Void)? = nil

// Usage
DataSapien.getJourneyService().getJourneysByTag(tag: "tag") { journeys in
    
} onError: { error in
    
}

Executing Journeys​

Each journey has a context. Context can be set before the journey executing. And data can be added to journey and they can be accessed on the JavaScript execution. New data can be added to context on the Script part. When journey is finished new context is pushed to the completion block.

Executing Journeys
// Signature
public func executeJourney(
    _ viewController: UIViewController,
    context: JourneyContext = JourneyContext(),
    journey: Journey,
    onComplete: @escaping (([String: Any]) -> Void)

// Usage
DataSapien.getJourneyService().executeJourney(self, journey: journey) { context in
    // Journey completed
}

// Usage with context
DataSapien.getJourneyService().executeJourney(self, context: context, journey: journey) { context in
    // Journey completed
}

Get Journey results​

Journeys can be completed multiple times. To get the journey results getLatestJourneyTransactionInfo function can be used.

Get Journey results
// Signature
public func getLatestJourneyTransactionInfo(id: String) -> JourneyTransactionInfo?

// Usage
DataSapien.getJourneyService().getLatestJourneyTransactionInfo(id: journey.id)