# Orchestration quickstart: React Native
This guide describes how to quickly integrate Journeys into your React Native application.
## 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 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. Here is a short video that describes this journey, and how a sample web application interacts with it.
## Before you start
Before the SDK can start running journeys, make sure to:
- Create a journey for this tutorial. In the admin portal, go to **B2C** or **B2B Identity** (based on your setup) > **Journeys**. From there click on **Templates**, and choose the **Level 0 tutorials / Hello world** template. Click to create a journey from this template. Set the name to `hello-world-quickstart` and save journey ID
- Create an application and obtain the auto-generated Client ID as defined [here](/guides/user/create_new_application)
- Allow Mosaic IPs and [domains](/guides/quick_start/enable_communication) on your network (if using a [custom domain](/guides/deployment/custom_domains), configure your network accordingly)
- Extend the `Content-Security-Policy` header, if [CSP](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) is enabled on your web server (if using a [custom domain](/guides/deployment/custom_domains), update your CSP to include your custom domain)
## Step 1: Installation
### 1. Install React Native module
Install the Mosaic React Native Orchestration module in your project folder.
npm
```shell
npm install react-native-ts-identity-orchestration
```
yarn
```shell
yarn add react-native-ts-identity-orchestration
```
### 2. Install iOS native dependencies
The react module requires the Mosaic iOS SDK to be installed using Cocoa Pods in your project's iOS folder.
```shell
cd YOUR_PROJECT_PATH/ios
pod install
```
### 3. Install Android native dependencies
Add the following lines in the shared build.gradle file ("allprojects" scope):
```groovy
dependencyResolutionManagement {
repositories {
maven {
url('https://transmit.jfrog.io/artifactory/transmit-security-gradle-release-local/')
}
mavenCentral()
google()
}
}
```
details
summary
b
Try to compile your app in Android Studio
If you get a compile error:
`Manifest merger failed : Attribute application@allowBackup value=(false)`
1. Open your `AndroidManifest.xml` file
2. Add `xmlns:tools="http://schemas.android.com/tools"` to the main manifest tag
3. Add `tools:replace="android:allowBackup"` to the top of the `application` tag.
## Step 2: Initialize the SDK
Initializing the SDK configures it to work with your client ID, which is the context under which the entire journey is executed. It also allows setting the base URL for the SDK to use, whether a Mosaic-provided path or your own proxy.
### 1. iOS initialization configuration
1. Open your project's `.xcworkspace` found under `YOUR_PROJECT_PATH/iOS` in Xcode.
2. Create a plist file named `TransmitSecurity.plist` in your Application with the following content. CLIENT_ID is configured in your Mosaic server. Make sure to add the file to your iOS project.
Here's an example of the plist file:
```xml
credentials
baseUrl
[BASE_URL]
clientId
[CLIENT_ID]
```
Note
If you're using a [custom domain](/guides/deployment/custom_domains) for your application, set `baseUrl` to your custom domain instead of the default Transmit domain.
### 2. Android initialization configuration
1. Open your Android manifest XML file, usually located at `android/app/src/main`.
2. Update the strings.xml file in your Application with the following content. The CLIENT_ID should be replaced with your client ID.
```xml
[CLIENT_ID]
[BASE_URL]
```
The Android SDK is required to be initialized in your App's Main Application class. To do that, open your MainApplication.kt file and add the following to the bottom of the function `onCreate()`:
```kotlin
TsIdentityOrchestrationModule.initializeAndroidSDK(this)
```
Note
If you're using a [custom domain](/guides/deployment/custom_domains) for your application, set `transmit_security_base_url` to your custom domain instead of the default Transmit domain.
### 3. Initialize React module
```javascript
import RNTSIdentityOrchestration, { TSIDOModule } from 'react-native-ts-identity-orchestration';
/**
Creates a new Orchestration SDK instance with your client context.
Credentials are configured from TransmitSecurity.plist file (iOS) or manifest file (Android).
*/
try {
if (Platform.OS === 'ios') {
this.idoSDK.initializeSDK();
} else {
// Initialize Android SDK on MainApplication.kt (see details above)
}
} catch (error) {
console.error('Error initializing IDO service', error);
}
```
## Step 3: Start journey
Starting a journey is usually a response to some user interaction, such as clicking a login or sign-up button. Your application should present a button and call the below on user click. Note we use the name we provided for the journey we created from the template:
```javascript
import RNTSIdentityOrchestration, { TSIDOModule } from 'react-native-ts-identity-orchestration';
const idoSDK = RNTSIdentityOrchestration;
idoSDK.setResponseHandler({
success: (results: TSIDOModule.ServiceResponse) => {
handleJourneyServiceResponse(results); // defined in Select Handler step
},
error: (error: TSIDOModule.JourneyErrorType) => {
logger.warn(`React Native IdoSDK error: ${error}`);
}
});
idoSDK.startJourney('JOURNEY_ID', null); // Replace with hello-world-quickstart journey ID
```
## Step 4: Handle service response
After starting the journey, the client app waits for the `TSIDOModule.ServiceResponse`. It will contain 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](#1-select-handler)
2. [Implement the hello world form handler](#2-implement-the-hello-world-form-handler)
3. [Implement the display information step handler](#3-implement-the-display-information-handler)
### 1. Select handler
Upon receiving the `TSIDOModule.ServiceResponse`, launch a handler that executes the relevant step by switching/selecting on the `TSIDOModule.ServiceResponse.journeyStepId` parameter. In the `hello-world-quickstart` journey we created, there are two steps that we will have to handle:
1. A [Collect information](/guides/orchestration/journeys/get_info_from_client) step. This step expects the client side to collect some data and send back. The step is configured with the Step ID property set to `hello_world_form` custom string. This will be the value of the `journeyStepId` attribute.
2. A [Display Information](/guides/orchestration/journeys/display_information) step that sends presentable text based data collected from the first step. This will have a fixed ID, so the value of the `journeyStepId` is `TSIDOModule.JourneyActionType.information`.
3. In addition, add handlers for **Success** and **Rejection** completions
```javascript
private handleJourneyServiceResponse = (results: TSIDOModule.ServiceResponse) => {
switch (results.journeyStepId) {
case TSIDOModule.JourneyActionType.success: console.log('Journey completed successfully!'); break;
case TSIDOModule.JourneyActionType.rejection: console.log('Journey rejected with error'); break;
case TSIDOModule.JourneyActionType.information:
// show information screen; See Implement the Display Information handler section.
break;
case `hello_world_form`:
this.handleHelloWorldForm(results);
break;
default: logger.warn(`handleJourneyServiceResponse: Unknown journey step: ${results.journeyStepId}`); break;
}
}
```
Each case will process the data, display whatever UI is needed, and call `submitClientResponse()` when the interaction is concluded, more on this in the next sections. This is how the app code would dispatch the above handlers:
### 2. Implement the Hello World form handler
The following handler is used to get information from the user as described in [Collect information](/guides/orchestration/journeys/get_info_from_client) step documentation. Specifically, the Hello world form handler should allow the user to enter two strings that should be sent back as `username` and `password`. This matches the expected schema as you can see in the journey's **Collect information** step, under **Schema** field configuration:
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"username": {
"type": "string"
},
"password": {
"type": "string",
"format": "password"
}
}
}
```
You need to display a form that collects these fields, and on user submit sent back to Mosaic as demonstrated below. Note the response type `TSIDOModule.ClientResponseOptionType.clientInput` is standard for almost all journey steps:
```javascript
// display form to user and collect the required values
let user_data = { // compose data that matches the expected schema
"username": collectedUserName,
"password": collectedPassword
}
idoSDK.submitClientResponse(TSIDOModule.ClientResponseOptionType.clientInput, user_data);
```
NOTE
The completion of `submitClientResponse()` will invoke the same response handlers set in the [Start Journey](#step-3-start-journey) section.
### 3. Implement the Display Information handler
The **Display Information** step is used to display an information screen, as described in the [Display Information](/guides/orchestration/journeys/display_information) step guide.
Your handler code should show a screen that displays the information sent from the server, using the `data` property provided in the `TSIDOModule.ServiceResponse` object. The specific structure of the data that will be sent for this step is described below, as well as in the step guide. Note that in our journey, the `text` attribute will contain data collected from the user in the previous step:
```json
{
"data": {
"title": "Collected client information",
"text": "Here is what we got from the client side: {...}",
"button_text": "OK"
}
}
```
The above data is exposed and used as seen here:
```javascript
// The actionData is taken from the TSIDOModule.ServiceResponse results object
let actionData = results.data;
let title = actionData.title;
let text = actionData.text;
let buttonText = actionData.button_text;
// display UI based the above, and on button click call the the below
idoSDK.submitClientResponse(TSIDOModule.ClientResponseOptionType.clientInput);
```
## Step 5: Complete journey
Mosaic signals journey completion by setting the `journeyStepId` property to `TSIDOModule.JourneyActionType.success` or `TSIDOModule.JourneyActionType.rejection`. The specific enum for each SDK is described in the [select handler](#1-select-handler) above. In this example, we expect 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](/guides/orchestration/getting-started/journey_completion).
## Next steps
You can now proceed to read the in-depth [React Native guide](/guides/orchestration/sdk/react_native_guide).
style
section article ol li {
margin-top: 6px !important;
}
.lifecycleSteps {
line-height: 30px !important;
}