iOS SDK

Suggest Edits

Integration

The Forter3DS SDK supports Swift Package Manager and CocoaPods. Follow the steps below to integrate the Forter SDK into your project:

Swift Package Manager

To add the Forter3DS package select File > Swift Packages > Add Package dependency

Add the Forter3DS repository, see screenshots below for a step by step process:

CocoaPods

Ensure that your Podfile includes the use_frameworks! flag

Add the Forter3DS Pod to the Podfile next to the rest of the frameworks you're using, using the code on the right.Run pod install

Notes

  1. Credentials need to be specified and committed to your Git. Although they are not sensitive, this step will keep bots and search engines away from the repository.

  2. Forter 3DS 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 licenseGMEllipticCurveCrypto - Crypto library for Elliptic-curve keys BSD 2-Clause “Simplified” License

Initialization

To ensure that the Forter3DS SDK loads correctly when the app is active, it must be initialized from the Application Delegate. The app delegate object is the primary root of an iOS app and is created early in the app's launch cycle. Therefore, initializing the Forter 3DS SDK within the app delegate is essential.

For more information on the app delegate, please refer to the Official iOS developer documentation.

  1. Import the SDK (see code on right)

  2. Initialize the Forter3DS SDK from the application delegate by adding the following line to your application delegate's:  didFinishLaunchingWithOptions (see code on right)

  3. Debugging (optional step) - To assist with troubleshooting and root cause analysis in the event of an error, it is recommended to enable dev logs by adding the code provided on the right.

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

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 the parameters provided on the right, with the mandatory params for each version marked with ✅ and optional values marked with '?'.

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 4 months ago