iOS SDK quick start

This guide describes how to quickly integrate Detection and Response services into your iOS application to get started. This includes both the client-side integration using the iOS SDK, as well as the backend API integration required to complete the flow.

Check out our sample app

Requirements

  • iOS 13+
  • Xcode 11+

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. Add a client display name, and your website URL as a redirect URI (e.g., https://your-domain.com ).
    Note

    These fields are required for all Mosaic apps, but won’t be used for Detection and Response.

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

Step 2: Add SDK to project

Add the SDK to your project so your application can access all the detection and response functionality. To do this, install the SDK as a dependency using Swift Package Manager:

Copy
Copied
dependencies: [
    .package(url: "https://github.com/TransmitSecurity/accountprotection-ios-sdk.git", .upToNextMajor(from: "1.0.1"))

Step 3: Initialize SDK

Start monitoring your end-user risk levels by initializing and configuring the SDK.

Initialize using PLIST configuration (recommended)

To do this, create a plist file named TransmitSecurity.plist in your Application with the following content. The [CLIENT_ID] should be replaced with your client ID from step 1.

Copy
Copied
<?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>
		<key>clientId</key>
		<string>[CLIENT_ID]</string>
	</dict>
</dict>
</plist>

Add the code below to your Application Class

Note
  • Make sure to add the import AccountProtection at the top of the implementation class.
  • The SDK can be configured to work with an EU cluster by setting the baseUrl key within the TransmitSecurity.plist to https://api.eu.transmitsecurity.io/ .
UIKitSwiftUI
Copy
Copied
class AppDelegate: UIResponder, UIApplicationDelegate {

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

    init() {
        TSAccountProtection.initializeSDK()
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}
Initialize using SDK parameters

Add the code below to your Application Class. The [CLIENT_ID] should be replaced with your client ID from step 1.

Note
  • Make sure to add the import AccountProtection at the top of the implementation class.
  • The SDK can be configured to work with an EU cluster by setting the first initialization parameter to baseUrl : 'https://api.eu.transmitsecurity.io/' .

:::

UIKitSwiftUI
Copy
Copied
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        TSAccountProtection.initialize(clientId: [CLIENT_ID])
        return true
    }
}
Copy
Copied
struct ExampleApp: App {

    init() {
        TSAccountProtection.initialize(clientId: [CLIENT_ID])
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

Step 4: Set user

A user identifier must be reported to Mosaic after you've fully authenticated the user (including, for example, any required 2FA that was done). This will set the user for all subsequent events.

To do this, add the code below after your application has authenticated a user (or after SDK initialization if you already have the user context for the authenticated user). The [USER_ID] is an opaque identifier for the user in your system.

Note
  • Make sure to add the import AccountProtection at the top of the implementation class.
  • The user ID must not include personal user identifiers, such as email.
Copy
Copied
TSAccountProtection.setUserId([USER_ID])

Step 5: Report actions

To obtain risk recommendations for sensitive actions, your application should report these actions using the SDK. To do this, add the code below to relevant user interactions (e.g., the Login button click event handler). Replace [ACTION_TYPE] with the appropriate action type from our list of actions. ActionEventOptions and TransactionData objects are optional and could be set to null.

Note
  • Make sure to add the import AccountProtection at the top of the implementation class.
  • Make sure to pass the received actionToken to your backend along with the actual action invocation to ensure you can leverage the recommendation in the next step.
Copy
Copied
// Transaction data (optional, pass 'nil' if not used)
let payer = TSTransactionData.Payer(name: "PAYER_NAME",
                                    bankIdentifier: "PAYER_BANK_IDENTIFIER",
                                    branchIdentifier: "PAYER_BRANCH_IDENTIFIER",
                                    accountNumber: "PAYER_ACCOUNT_NUMBER")
        
let payee = TSTransactionData.Payee(name: "PAYEE_NAME",
                                    bankIdentifier: "PAYEE_BANK_IDENTIFIER",
                                    branchIdentifier: "PAYEE_BRANCH_IDENTIFIER",
                                    accountNumber: "PAYEE_ACCOUNT_NUMBER")
        
let transactionData = TSTransactionData(amount: "AMOUNT",
                                        currency: "CURRENCY",
                                        reason: "REASON",
                                        transactionDate: "TRANSACTION_DATE",
                                        payer: payer,
                                        payee: payee)

// Options (optional, pass 'nil' if not used)
let options = TSActionEventOption(correlationId:"CORRELATION_ID",  
                                  claimUserId: "CLAIM_USER_ID",
                                  referenceUserId: "REFERENCE_USER_ID",
                                  transactionData: transactionData)

TSAccountProtection.triggerAction([ACTION_TYPE, options: options) { result in
    DispatchQueue.main.async {
        switch result {
        case .success(let response):
          let actionToken: String = response.actionToken
        case .failure(let error):
            switch error {
            case .disabled:
              break
            case .connectionError:
              break
            case .internalError:
              break
            case .notSupportedActionError:
              break
            @unknown default:
              break
        }
    } 
}

Step 6: Fetch recommendation

You can fetch recommendations from your backend for the reported action using the Recommendation API. This is the same API that's also used for web integrations.

Mosaic APIs are authorized using an OAuth access token so you'll need to fetch a token using your client credentials (from step 1). The token should target the following resource: https://risk.identity.security. To do this, send the following request:

Copy
Copied
  const { access_token } = await fetch(
    `https://api.transmitsecurity.io/oidc/token`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
      }
      body: new URLSearchParams({
        grant_type: client_credentials,
        client_id: [CLIENT_ID],
        client_secret: [CLIENT_SECRET],
        resource: 'https://risk.identity.security'
      })
    }
  );

From your backend, invoke the Recommendation API by sending a request like the one below. The [ACCESS_TOKEN] is the authorization token you obtained using your client credentials and [ACTION_TOKEN] is the actionToken received from the SDK in step 5.

Copy
Copied
const query = new URLSearchParams({
  action_token: '[ACTION_TOKEN]',
}).toString();

const resp = await fetch(
  `https://api.transmitsecurity.io/risk/v1/recommendation?${query}`,
  {
    method: 'GET',
    headers: {
      Authorization: 'Bearer [ACCESS_TOKEN]',
    },
  }
);

Step 7: Clear user

After the user logs out or the user session expires, you should clear the set user so they are not associated with future actions. To clear the user, call the clearUser() method as shown below.

Note

Make sure to add the import AccountProtection at the top of the implementation class.

Copy
Copied
TSAccountProtection.clearUser()