Orchestration quickstart: Cordova

This guide describes how to quickly integrate Journeys into your Cordova application.

Read the Cordova Orchestration SDK reference for the full method list, including mobile approve and steps that need another Mosaic SDK.

The Orchestration SDK enables client-side developers to build user experiences that interact with Client SDK journeys.

Each journey contains a business workflow, such as login or secure user onboarding. It consists of backend steps, such as data processing or invoking external systems, and client-facing steps, such as a login form or identity verification. The SDK allows the client application to present screens and prompt for user input, and then send this information back to the journey for further processing.

Whenever the client-side interaction requires additional Mosaic platform capabilities, such as passkeys or risk detection, the developer needs to activate the appropriate SDK module to perform the step and collect the required input. This allows separation of concerns between the journey workflow handling, and the specific capability used.

This guide will use the "Hello World" journey template and instruct you how to build a client side application that works with it.

Before the SDK can start running journeys, make sure to:

• Create a journey for this tutorial. In the Admin Portal, go to B2C Identity or B2B Identity (based on your setup) > Journeys. From there click Templates, and choose the Level 0 tutorials / Hello world template. Create a journey from this template, set the name to hello-world-quickstart, and save the journey ID.
• Create a Mosaic application and obtain the auto-generated Client ID as described here.
• Allow Mosaic IPs and domains on your network. If you use a custom domain, configure your network accordingly.

Install the plugin, add your client credentials, and initialize it before the app starts a journey. The Cordova Orchestration SDK reference has the commands and configuration files. Do the following, in order:

1. Confirm the requirements, then install the plugin and apply the platform configuration.
2. Add the client ID and base URL to the native credential files.
3. On deviceready, register a journey listener, then call initializeSDK(). See Initialization. Journey steps arrive on that listener. They are not the return value of startJourney(). This guide defines the listener as onJourneyEvent in Select handler.

Starting a journey is usually a response to some user interaction, such as clicking a login or sign-up button. Call startJourney() with the journey ID saved from the Hello World template. A resolved promise means the SDK accepted the request. The first step is delivered to the listener from Step 1.

function startHelloWorld() {
  cordova.tsido.startJourney('JOURNEY_ID') // Replace with the hello-world-quickstart journey ID
    .catch(function (error) {
      console.error(error.code, error.message);
    });
}

After starting the journey, the client app waits for a listener event whose type is response. The response object contains what the client needs in order to determine what to do next. An event whose type is error is a journey failure, with error.code and error.message.

To handle the service response, the client app needs to:

1. Select a handler based on the step
2. Implement the hello world form handler
3. Implement the display information step handler

When the listener receives a response, select a handler by switching on response.journeyStepId. In the hello-world-quickstart journey, handle these steps:

1. A Collect information step. This step expects the client to collect data and send it back. The step ID is the custom string hello_world_form, which is the value of journeyStepId.
2. A Display information step that presents text based on the data collected in the first step. Its journeyStepId is cordova.tsido.STEPS.INFORMATION.
3. Handlers for Success and Rejection completion.

function onJourneyEvent(event) {
  if (event.type === 'error') {
    console.error(event.error.code, event.error.message);
    return;
  }
  if (event.type === 'response') {
    handleJourneyServiceResponse(event.response);
  }
}

function handleJourneyServiceResponse(response) {
  switch (response.journeyStepId) {
    case cordova.tsido.STEPS.SUCCESS:
      console.log('Journey completed successfully');
      break;
    case cordova.tsido.STEPS.REJECTION:
      console.log('Journey rejected');
      break;
    case cordova.tsido.STEPS.INFORMATION:
      handleDisplayInformation(response);
      break;
    case 'hello_world_form':
      handleHelloWorldForm(response);
      break;
    default:
      console.warn('Unknown journey step: ' + response.journeyStepId);
      break;
  }
}

Each case processes the data, displays whatever UI is needed, and calls submitClientResponse() when the interaction is concluded.

The following handler collects information from the user, as described in the Collect information step. The Hello World form collects two strings and sends them back as username and password. This matches the schema on the journey's Collect information step, under Schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "username": {
      "type": "string"
    },
    "password": {
      "type": "string",
      "format": "password"
    }
  }
}

Display a form that collects these fields. On submit, send them back to Mosaic. cordova.tsido.RESPONSE_OPTIONS.CLIENT_INPUT is the standard response for this step:

function handleHelloWorldForm(response) {
  // Display a form and collect the required values.
  var userData = {
    username: collectedUserName,
    password: collectedPassword
  };
  cordova.tsido.submitClientResponse(
    cordova.tsido.RESPONSE_OPTIONS.CLIENT_INPUT,
    userData
  );
}

The Display information step shows an information screen, as described in the Display information step. Read the server payload from response.data. In this journey, text contains the data collected in the previous step:

{
  "data": {
    "title": "Collected client information",
    "text": "Here is what we got from the client side: {...}",
    "button_text": "OK"
  }
}

function handleDisplayInformation(response) {
  var actionData = response.data;
  var title = actionData.title;
  var text = actionData.text;
  var buttonText = actionData.button_text;
  // Display the title and text. When the user taps the button, continue the journey.
  cordova.tsido.submitClientResponse(cordova.tsido.RESPONSE_OPTIONS.CLIENT_INPUT);
}

Mosaic signals journey completion by setting journeyStepId to cordova.tsido.STEPS.SUCCESS or cordova.tsido.STEPS.REJECTION. The handlers are in Select handler. This example expects a successful response.

For authenticated journeys, successful completion can return an opaque code that your client passes to your backend. Your backend then exchanges that code for user tokens and enriched context, allowing it to establish a session, call downstream services, or run additional business logic with the authenticated user context. For details, see Journey completion for SDK journeys.