iOS SDK quick start with journeys

This guide describes how to quickly integrate Fraud Prevention into your iOS application and obtain real-time risk recommendations using Journeys. This guide covers the client-side integration (using the Fraud Prevention SDK and the Orchestration SDK) and the journey configuration needed to complete the flow.

How it works

The flow starts with the user navigating to your iOS app (1). The Fraud Prevention SDK and the Orchestration SDKs get initialized (2 & 3). The Fraud Prevention SDK starts streaming telemetry data to Mosaic (4). The application requests a device session token (5), the Fraud Prevention sends a request to the Mosaic server (6) and receives a device session token (7), which is then returned to the application (8).

When a user performs a high risk action (9), the application notifies the Orchestration SDK to start a journey (10). The Orchestration SDK invokes a journey (11). Mosaic reaches the risk recommendation step (12) and sends a request to the Fraud Prevention engine (13). As soon as a recommendation is returned (14), IDO processes the risk (15) and passes this data to the Orchestration SDK (16), which then forwards it to the application (17). The application proceeds depending on results (18).

Requirements

• iOS 13+
• Xcode 11+

Before you start

• Allow Mosaic IPs and domains on your network
  
• Extend the Content-Security-Policy header, if CSP is enabled on your web server
  

Step 1: Get client credentials

Client credentials are used to identify your app and generate access tokens for authorizing Mosaic requests. To obtain them, you'll need to create an application in the Admin Portal (if you don’t have one yet).

1. From Applications, click Add application.
2. Add the friendly application name to display in the Admin Portal.
3. Configure a client: its display name, and your website URL as a redirect URI (e.g., https://your-domain.com).

1. Click Add to create your client. This will automatically generate your client credentials.

Step 2: Orchestrate the backend logic

Journeys can handle the business logic responsible for obtaining risk recommendations for sensitive events. This includes the following configuration steps:

1. Store client credentials
2. Create a web function
3. Configure journey steps

1. Store client credentials

Start by saving the client credentials you've acquired in Step 1 with Mosaic Journeys. This step is required in order to authorize journey calls.

1. Navigate to Admin Portal > Journey Tools > Keys and Credentials > Credentials and select +Add credentials.
2. Provide an alias and input client ID and secret.

See Key and credentials for more details.

2. Create a web function

Create a new web function that calls the Trigger action endpoint. See Custom HTTP function for more details.

1. Navigate to Admin Portal > Management > Integration hub > Custom HTTP.
2. Provide a function name, e.g., trigger_action_for_user
3. Add function argument # 1:
   • Argument name: session_token
   • Argument description: Fraud Prevention SDK device session token
   • Type description: string
4. Add function argument # 2:
   • Argument name: action_type
   • Argument description: Client provided action type
   • Type description: string
5. Add function argument # 3:
   • Argument name: user_id
   • Argument description: Identifier of an authenticated user
   • Type description: string
6. Add function argument # 4:
   • Argument name: correlation_id
   • Argument description: Interaction ID in your app
   • Type description: string
7. Configure the format:
   • Request URI: https://api.transmitsecurity.io/risk/v1/action/trigger-action?get_recommendation=true
   • HTTP request method: POST
   • Request body:
     {
         "session_token": "${session_token}",
         "action_type": "${action_type}",
         "correlation_id": "${correlation_id}",
         "user_id": "${user_id}"
     }

   • Request header:
     • Name: Content-Type
     • Value: application/json
8. Configure authentication:
   • Authentication Type: OAuth 2 Client Credentials Grant
   • URL: https://api.transmitsecurity.com/oidc/token
   • Credentials alias: select the alias created in Step 2.1
   • Scope: offline_access
   • Resource: https://risk.identity.security
9. Set the response format to JSON object.
10. Save a function.

3. Configure journey steps

Configure an identity journey for obtaining risk recommendations and exporting a result.

1. In the Admin Portal, go to B2C or B2B Identity (based on your setup) > Journeys and create a new Client SDK journey. Provide a name, e.g., risk-recommendation, and save journey ID.
2. Add the Invoke Custom HTTP step and configure it to use the web function defined in Step 3.2.
   • Configure the step to set its result into the output variable (e.g.,risk_recommendation).
   • Configure the step to retrieve the input parameters provided by the client in the journey (see Step 6) as follows:
     • session_token: @policy.request().params["session_token"]
     • action_type: @policy.request().params["action_type"]
     • user_id: @policy.request().params["user_id"]
     • correlation_id: @policy.request().params["correlation_id"]
3. Add the Provide JSON Data step and set the Data to Send to:
    {
       "risk_recommendation": "risk_recommendation"
    }

4. Add the Complete Journey step.

Your journey will look as follows:

Step 3: Add SDKs to project

Add the SDKs to your project so your application can access all the Fraud Prevention functionality and invoke identity journeys. Install SDKs as dependencies using Swift Package Manager.

dependencies: [
    .package(url: "https://github.com/TransmitSecurity/accountprotection-ios-sdk.git", .upToNextMajor(from: "2.0.0")),
    .package(url: "https://github.com/TransmitSecurity/identityOrchestration-ios-sdk.git", .upToNextMajor(from: "1.0.0"))
]

Step 4: Initialize SDKs

Initializing the SDKs configures them to work with your client ID. It also allows setting the base URL for the SDKs to use, whether a Mosaic-provided path or your own proxy. In case of Fraud Prevention, it starts streaming telemetry data upon SDK initialization.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>credentials</key>
	<dict>
		<key>baseUrl</key>
		<string>https://api.transmitsecurity.io/</string> <!-- Default -->
		<key>clientId</key>
		<string>[CLIENT_ID]</string>
	</dict>
</dict>
</plist>

class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        TSAccountProtection.initializeSDK()
        TSIdo.initializeSDK()
        return true
    }
}

class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        TSAccountProtection.initialize(clientId: [CLIENT_ID])
        TSIdo.initialize(
            clientId: Env.clientId,
            options: .init(serverPath: Env.baseUrl)
        )
        return true
    }
}

Step 5: Create session token

Obtain a Fraud Prevention device session token by executing the code below. Save the received device session token in order to obtain risk recommendations in the next step (Step 6).

TSAccountProtection.getSessionToken { token in
    debugPrint("[DEBUG]: Fraud Prevention device session token: \(token)")
}

Step 6: Invoke journey

To obtain risk recommendations, the journey (created in Step 2) should start in response to sensitive user interactions, such as payments. Your application should present a button and call the below on user click. Along with the journey invocation, pass:

• session_token received in Step 5
• action_type from our list of actions that represents a high risk action the user attempts to perform
• user_id that represents a hash of the user logged into the app. The actual user ID should not be sent (this journey assumes the user has already authenticated in your app)
• correlation_id of the interaction

let params: [String: Any] = [
    "user_id": "[USER_ID]",
    "action_type": "[ACTION_TYPE]",
    "session_token": "[SESSION_TOKEN]",
    "correlation_id": "[CORRELATION_ID]"
]

// Start the journey
do {
    try TSIdo.startJourney(journeyId: "[JOURNEY_ID]",
                           options: .init(additionalParams: params,
                                          flowId: "[FLOW_ID]"))
} catch {
    debugPrint("[DEBUG] Failed to start journey: \(error)")
}

// Handle start journey response:
func TSIdoDidReceiveResult(_ result: Result<IdentityOrchestration.TSIdoServiceResponse, IdentityOrchestration.TSIdoJourneyError>) {
    isLoading.send(false)

    switch result {
    case .success(let response):
        handleIdoResponse(response)
    case .failure(let error):
        handleJourneyError(error)
    }
}

private func handleIdoResponse(_ response: IdentityOrchestration.TSIdoServiceResponse) {
    // Get journey step id
    guard let responseStepId = response.journeyStepId else { debugPrint("[DEBUG]: No step id found in response"); return }
    // Get response data
    guard let actionData = response.data else { debugPrint("[DEBUG]: No data found in response object"); return }

    ...
    // Handle UI based on the step id
}

Step 7: Handle recommendation

Mosaic signals journey completion by setting the journeyStepId property to Rejection.type or Success.type. The Orchestration SDK returns recommendation data (idoServiceResponse.data.json_data) to the application to proceed accordingly.