Develop with Orchestration SDK: Web

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

See SDK reference

Introduction

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 document 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.

SDK lifecycle

Regardless of journey logic, the SDK lifecycle consists of the following:

𝟷.   Initialization via initialize() (done only once for each app instance)
𝟸.   Activate startJourney() and wait for the server response
𝟹.   Check IdoServiceResponse and present the appropriate UX. If needed, operate additional Mosaic SDKs.
𝟺.   Return client input via submitClientResponse() (allows selecting a journey branch if supported by journey step)
𝟻.   Repeat 3 and 4 until receiving Success or Rejection

The above is reflected in the following workflow diagram:

UserClientOrchestration SDKMosaicopt[If not initialized]Step 1Step 2Step 3Step 4Step 5loop[while the response is not "success" or "rejection"]click logininitialize()startJourney(journey-id, optional parameters)forward start-journey parametersprocess server-sidejourney stepsjourney service responseidoServiceResponse objectdescribes required client stepor journey completionpresent UI per idoServiceResponse.journeyStepIduse additional SDK modules if needed (eg passkey)interact as neededsubmitClientResponse(selected-option, data)selected-option affects journey branchif multiple options are availableforward client responseprocess incoming dataand further stepsjourney service responseidoServiceResponse objectdescribes required client stepor journey completionpost journey UX, if completedUserClientOrchestration SDKMosaic

Before you start

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

☐   Coordinate with the journey developer (regarding journey ID, steps, expected data, etc).
☐   Obtain the Client ID that identifies the app, from the app settings in the Admin Portal
☐   Allow Mosaic IPs and domains on your network
☐   Extend the Content-Security-Policy header, if CSP is enabled on your web server

Step 1: Load SDK

Start by loading the SDK. You can load the SDK in one of two ways:

  • Using npm (recommended) :
    Copy
    Copied
    npm install @transmitsecurity/platform-web-sdk@1

    alternatively, use Yarn:

    Copy
    Copied
    yarn add @transmitsecurity/platform-web-sdk@1
  • Using a script tag (CDN) :
    Copy
    Copied
    <script type="text/javascript" src="https://platform-websdk.transmitsecurity.io/platform-websdk/1.x/ts-platform-websdk.js" defer="true" id="ts-platform-script"></script>
    info

    When using the script tag, all functions must be invoked inside window.tsPlatform.
    This applies only to the CDN method.

For more details about available options and customizations, see the SDK reference.

Step 2: Initialize SDK

Import the Orchestration and Authentication modules, and then initialize the SDK by calling the SDK's initialize() method. The [CLIENT_ID] should be replaced with your client ID.

Important

By default, the SDK is initialized for US-based (global) cluster. To use EU or Canada clusters, update serverPath in ido object.

Copy
Copied
import { ido, webauthn, initialize } from '@transmitsecurity/platform-web-sdk';

// If SDK was loaded via script tag, invoke functions inside 'window.tsPlatform'
initialize({
  clientId: 'my-client-id',  // Client ID from app settings in the Admin Portal
  ido: {
    serverPath: 'https://api.transmitsecurity.io/ido' // Base URL, default is for US region
  }
});

Step 3: Start journey

Starting a journey is usually a response to some user interaction, such as clicking a login or sign-up button. The start parameters indicate which journey to start, and optionally pass additional parameters if the journey expects them.

For example, if the client app uses email as the user identifier and caches it locally after sign-up, it can pass it to the journey as userEmail. The journey can reference it using this expression @policy.request().params.userEmail

Copy
Copied
// Start a journey
try {
  const idoResponse = await ido.startJourney(
      'JOURNEY_ID',   // Journey ID
      {
        'additionalParams': { userEmail: <locally-stored-email> }
      }
  );
  // Handle service response below
  ...
} catch(error) {
  switch(sdkError.errorCode) ...
}

Step 4: Handle service response

After starting the journey, the client app waits for the IdoServiceResponse. It will contains all the information the client needs in order to determine what to do next.

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

  1. Select a handler based on the step
  2. Use the data provided by the journey
  3. Respond to the journey with requested input

1. Select handler

Upon receiving the IdoServiceResponse, launch a handler that executes the relevant step by switching/selecting on the IdoServiceResponse.journeyStepId parameter. It will either contain one of these enums, or the Step ID configured in the Login Form or Collect information step. Each handler should process the data, display whatever UI is needed, and call submitClientResponse() when the interaction is concluded.

This is how the app code would dispatch handlers based on this property:

Copy
Copied
switch (idoServiceResponse.journeyStepId) {
    case IdoJourneyActionType.Information:
        handleInformationStep(idoServiceResponse);
        break;
    case IdoJourneyActionType.EmailOTPAuthentication:
        handleEmailOTP(idoServiceResponse);
        break;
    case 'main_login_form': // custom identifier for main Login Form step
        handleMainLoginForm(idoServiceResponse);
        break;
    case 'user_info_form': // custom identifier for a collect information step
        handleUserInfoForm(idoServiceResponse);
        break;
    case etc ...
}

2. Use data sent from journey

Inside the handler function, the app code should render a UI that fits the specific step, and use information from the data property if it was provided in the idoServiceResponse object. This data is described in each step guide.

Let's see an example for a Register Passkeys step. IdoServiceResponse will include journeyStepId set to WebAuthnRegistration and a data object containing the user identifier and other WebAuthn configuration. This data can be used for calling the webauthn (passkey) registration module, as shown below:

Copy
Copied
let data = idoServiceResponse.data;
// Registers passkey credentials on the device using data provided by the journey
let registrationResult = await webauthn.register(
    data.username,
    {
        allowCrossPlatformAuthenticators: data.allow_cross_platform_authenticators,
        registerAsDiscoverable: data.register_as_discoverable,
        displayName: data.display_name
    }
);

3. Respond with collected data

Once the user interaction is concluded, the handler should collect the response data and submit it using submitClientResponse(). This call yields control back to the journey, and returns with a new IdoServiceResponse once the journey reaches the next client-facing step.

The call parameters are the collected data, and a response option identifier. We’ll talk more about these below. For now, let's follow the Register Passkeys example of making this call from each SDK.

Copy
Copied
let data = { "webauthn_encoded_result": encodedRegistrationResult };

let idoResponse = await ido.submitClientResponse(


    ClientResponseOptionType.ClientInput,
    data
);
About response data schema

Each journey step expects specific fields to be sent back in the data object. The details of the expected fields are described in the relevant step guide. As seen above, when we use the example of the Register Passkeys step, the expected data is a field called webauthn_encoded_result which is the output of the Passkey registration SDK.

For most journey steps, the client response schema is fixed. However, there are two steps that expect a dynamic schema. The Login Form step allows presenting multiple authentication options and collects input for one of them. The Collect information step allows presenting an arbitrary data collection form to the end user. For both steps, the expected data schema is configured in the step. The client developer must coordinate with the journey author for the expected schema for each Step ID.

About alternate branches and response options

Certain steps support multiple response options. These options are passed in the IdoServiceResponse object in the clientResponseOptions property. These represents possible replies that the client can provide as a response to a journey step, and affect the branch that is taken when the step is completed.

Three of these replies have a standard type (per SDK):

  • ClientInput represents a typical reply to a step that has a main or single output path. See above the example for Register Passkeys is using this reply option. This would be the common reply option to most steps.
  • Cancel chooses the cancel branch in actions that support it
  • Fail chooses the failure branch in actions that support it

Apart from those, some journey steps support alternate (custom) branches. The Branch ID is configured by the journey author, and should be used to identify the branch when calling submitClientResponse(). The example below submits a response to the Login Form step, where one of the alternate branches proceeds to passkey authentication. This branch also expects a specific schema (that can be customized by the journey author) - the default is getting the encoded result after activating the authentication SDK.

Copy
Copied
let data = { "webauthn_encoded_result": encodedAuthenticationResult };

let idoResponse = await ido.submitClientResponse(
    'passkey',
    data
);

Step 5: Complete journey

Mosaic signals journey completion by setting the journeyStepId property to Rejection or Success. The specific enum for each SDK is described in the Step 3.1 above. If successful, the token property contains a token as a proof of journey completion.

Next steps

The SDK also supports the features below. For more info, talk to your Transmit Security representative.

  • Generating a debug pin for the journey debugger
  • State management - allows saving and restoring the SDK state. This allow handling refreshes, as well as page redirects as part of the Document Verification step and Invoke External IDP.
  • Local console logs
  • Resources URIs as part of SDK initialization (see SDK reference )