SDK Integration

This section provides detailed information on how to integrate the Netcetera 3DS SDK into an iOS Application or Library.

Cocoapods Setup

Steps to include the SDK into the project:

  1. Install Cocoapods following the instructions on the Cocoapods website.
  2. In your Podfile add the 3DS SDK private spec repo as source, and add the ThreeDS SDK as dependency.
  1. To install the pods run pod install.

Swift Package Manager Setup

To add 3DS SDK as dependency to your Xcode project, select File > Add Packages and enter the repository URL: https://github.com/ios-3ds-sdk/SPM.git. Proceed by selecting which version of the SDK you want to integrate.

You can also navigate to your target’s General pane, and in the “Frameworks, Libraries, and Embedded Content” section, click the + button, select Add Other, and choose Add Package Dependency.

Manual Setup

Dynamic Framework

  1. Extract the Netcetera iOS 3DS SDK zip archive that is part of the delivery. Inside there is a single XCFramework ThreeDS_SDK.xcframework

  2. In your project, add the XCFramework in the "Frameworks, Libraries, and Embedded Content" section in the General target's tab.

Static Framework

  1. Extract the Netcetera iOS 3DS SDK Static zip archive that is part of the delivery. Inside there is an XCFramework ThreeDS_SDK.xcframework and a bundle ThreeDS-SDK-Resources.bundle

  2. In your project, add the XCFramework in the "Frameworks, Libraries, and Embedded Content" section in the General target's tab.

  3. Add the resources bundle in "Copy Bundle Resources" of the "Build Phases" section.

Dependencies

Several external dependencies are used by the Netcetera iOS 3DS SDK. These libraries are integrated inside the SDK. The full list of dependencies is:

NameDescriptionWebsiteLicenseVersion
ASN1DecoderUsed to parse keys and certificates in ASN1 structurehttps://github.com/filom/ASN1DecoderMIT license1.2
GMEllipticCurveCryptoSecurity framework used for Elliptic Curve keyshttps://github.com/ricmoo/GMEllipticCurveCryptoBSD 2-Clause "Simplified" License1.1

App Transport Security - HTTP Loads

The EMVCo 3DS Specification requires the communication between the 3DS SDK and the ACS to go through HTTPS, but there is no such requirement for what protocol to be used when downloading the Payment System and Issuer logo images that shall be shown in the challenge screens. The URLs of these images are provided as parameters by the ACS in the CRes and it is expected they will be HTTPS URLs. The SDK doesn't have influence over this and if HTTP URLs are provided, the images will not be shown on the challenge screens.

More information about this and how to ensure that these images will be downloaded and shown on the challenge screen even if they are served using unsecured connection, please check Preventing Insecure Network Connections

Integration in Hybrid Frameworks

This section details the integration of the Netcetera iOS 3DS SDK into hybrid frameworks. The primary goal is to provide support for numerous applications already utilizing these frameworks. Integration is performed in a manner similar to other native iOS framewors, though awareness of potential limitations specific to each hybrid framework is crucial.

Our testing efforts have focused on two widely used hybrid frameworks: Flutter and React Native. The subsequent sections provide guidance on integrating the framework.

Flutter

  1. SDK Integration: Begin by adding the Netcetera iOS 3DS SDK as a dependency in your Flutter project. You can achieve this by either including the SDK manually to the project or by adding it as a Pod dependency.

  2. Create Native Method Channel: To communicate between your Dart code and the native iOS code that interacts with the 3DS SDK, you'll use Flutter's MethodChannel. This bridge allows you to call native methods from Dart and receive responses back.

  3. Implement Native Methods: Write the native iOS code that interacts with the 3DS SDK. First, create a FlutterMethodChannel object provided by the Flutter dependency. Once the object is created, use setMethodCallHandler() to expose native coded methods to Dart via the established channel. This code will handle the initialization of the SDK, creation of transactions, and any other functionality required by your Flutter app.

  4. Invoke Native Methods from Dart: In your Dart code, use the MethodChannel to call the native methods implemented in the previous step. For example, you might call methodChannel.invokeMethod("initSDK") to initialize the SDK or methodChannel.invokeMethod("createTransaction") to create a transaction.

  5. Serialization of Data: Ensure proper serialization of parameters and results, as objects cannot be sent directly to Dart. Use JSON or HashMap values for this purpose.

React Native

  1. SDK Integration: Begin by adding the Netcetera iOS 3DS SDK as a dependency in your React Native project. You can achieve this by either including the SDK manually to the project or by adding it as a Pod dependency.

  2. Create Native Module: React Native expects the bridging module to be written in Objective-C. Our SDK supports Objective-C, therefore there are no problems with the integration itself. To write the module, you will need to create a header file (.h) that imports the React RCTBridgeModule header where you can define the methods that will be exposed to React Native. You should also import ThreeDS_SDK-Swift.h and ThreeDS_SDK.h to be able to make 3DS SDK calls.

  3. Implement Native Module: To implement the bridge, you will need to create a methods file (.m) where you should import the previously created header file and implement the defined methods. Use RCT_EXPORT_METHOD(MethodDefinition) to define a method that will be exposed to React Native. Unless the native module provides its own method queue, it shouldn't make any assumptions about what thread it's being called on. Currently, if a native module doesn't provide a method queue, React Native will create a separate GCD queue for it and invoke its methods there.

  4. Invoke Native Methods: With the native module implemented, you can now use its methods in your React Native JavaScript code. Import the NativeModules module from React Native and access your exposed methods. For example, you might call NativeModules.ThreeDSSDK.initializeSdk() where ThreeDSSDK is the name of the Objective-C module (name of the interface that imports the RCTBridgeModule) and initializeSdk() is the name of the exposed method.

  5. Serialization of Data: Ensure proper serialization of parameters and results, as objects cannot be sent directly to React Native. Use JSON or HashMap values for this purpose.