Integration Guides

iOS SDK

Suggest Edits

Installation

Forter3DS SDK provides flexible integration options, supporting both Swift Package Manager and CocoaPods. Choose the integration method that aligns with your project preferences and workflows add follow the steps below.

🚧

Ensure to select only one integration method and refrain from using both, as combining them may result in build conflicts

Swift Package Manager

  1. In your Xcode menu, go to File > Swift Packages > Add Package dependency
  2. Add the Forter3DS repository, the press Next
https://bitbucket.org/forter-mobile/forter-ios.git
  1. Click Next to keep the default setting to use the latest version
  2. Following the dependency resolution , choose Forter3DS and press Finish:

CocoaPods

Ensure that your Podfile includes the use_frameworks! flag

  1. In your Podfile add Forter3DS dependency to your target
platform :ios, '10.0'
use_frameworks!

target 'YourProjectName' do
	pod 'Forter3DS', :git => 'https://bitbucket.org/forter-mobile/forter3ds-ios.git'
end
  1. Run pod install

Dependencies

Forter3DS SDK uses external libraries that are already embedded in the SDK

  • ASN1Decoder - Certificate parsing in ASN1 structure. MIT License
  • SwCrypt - Crypto library for JWS validation (used only in iOS 10 devices) MIT license
  • GMEllipticCurveCrypto - Security framework used for Elliptic-Curve keys Crypto library. License

Initialization

The Forter3DS SDK should be initialized from the Application Delegate during application launch. This ensures that it is loaded correctly as soon as the app becomes active.

Step 1: Import the SDK

import Forter3DS

#import <Forter3DS/Forter3DS.h>

Step 2: Setup

To initialize theForter3DS SDK, you need to add the following line to your application delegate's didFinishLaunchingWithOptions method. This is a critical step to ensure the proper functioning of the Forter 3DS SDK within your iOS application. Make sure to replace <your-site-id> with the unique site ID assigned to you by Forter.

NOTE: In development mode, In order to present a native challenge Forter3DS SDK should load the test servers before calling the setup method, and use a dedicated test card. This is only for testing purposes and should NOT be used in production.

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
#if DEBUG
	  Forter3DS.loadTestServers() // Only for testing
#endif
    Forter3DS.setup(siteID: "<your-site-id>")
}

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
#if DEBUG
     [Forter3DS loadTestServers];
#endif
     [Forter3DS setupWithSiteID:@"<your-site-id>"];
}

Step 3 (Optional): Debugging

Adding developer logs to your code is a good practice for enhancing the diagnostic process and error detection within your application.

Forter3DS.enableDevLogs(true)

[Forter3DS enableDevLogs:YES];

Create a Transaction

Upon completion of the Init stage, Forter can collect the necessary data to create an FTRTransaction object.

To create the object, utilize the createTransaction method to create an FTRTransaction object which contains the data required for the server in order to create a transaction.

Arguments

  • dsId: the specific directory identifier, retrieved from the init call made to the server.
  • version: 3DS version, retrieved from the init call made to the server.

Usage

  • In 3DS1 flow - the directory server identifier is not required
  • In 3DS2 flow - both parameters are required
Forter3DS.createTransaction(withDsId: "A000000004", version: "2.2.0")

[Forter3DS enableDevLogs:YES];

Optional version is deprecated in v2.0.2. Version is a required parameter.

Return Value

createTransaction method returns a FTRTransaction object which contains the properties seen on the right.

These parameters are required for creating a challenge in 3DS2 flows if needed. In the case of 3DS1, all the fields will be null.

The following parameters should be used to create the threeDSMobileAppSDKData object in the Adaptive Auth Transaction API call, which is usually called from the server:

  • sdkEncData: A string that represents the encrypted device data.
  • sdkAppID: The 3DS SDK uses a secure random function to generate the App ID in UUID format. This ID is unique and is generated during installation and update of the app.
  • sdkEphemeralPubKey: Returns the SDK Ephemeral Public Key. For each transaction the createTransaction method will generate a fresh ephemeral key pair as this property will hold the public key component as a String representation.
  • sdkTransID: Returns the SDK transaction ID. For each transaction the createTransaction method will generate a transaction ID in UUID format.
  • sdkReferenceNumber: A string that represents the SDK reference number.

The server needs to send this params encoded in base64 format to the server. You can use the toBase64 to convert this object to the required format.

NOTE: When making the doChallenge call, the acsTransId, threeDSServerTransId, and version parameters are mandatory (if this is the required flow). It's crucial to pass these parameters "as is" without any parsing when calling the doChallenge method.

While it's recommended to get these parameters from your server before calling doChallenge, it's advised not to store them locally. This approach helps ensure that the most up-to-date parameters are used in the doChallenge call.

Do Challenge

If Forter's decision is to decline the transaction and verification is required, a challenge flow must be initiated. To do so, the app should call the doChallenge method.

Parameters

The doChallenge method requires different params for presenting a challenge depends on the challenge type (Native/Webview). Additional details can be found here

Notes

presentationStyle default value is FTR3DSChallengePresentModally

viewController argument passed is the currently presented UIViewController

delegate argument passed is the object that will implement the Forter3DSDelegate protocol callback methods

Return Value

doChallenge method does not return any value.

Callbacks

Forter3DSDelegate must be implemented for notifying the app about the challenge status:

onChallengeFinished: This callback will be called in case the challenge was completed

onChallengeFail: This callback will be called in case the challenge failed

Updated about 1 month ago