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:
- Install Cocoapods following the instructions on the Cocoapods website.
- In your Podfile add the 3DS SDK private spec repo as source, and add the ThreeDS SDK as dependency.
- 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
Extract the Netcetera iOS 3DS SDK zip archive that is part of the delivery. Inside there is a single XCFramework
ThreeDS_SDK.xcframework
In your project, add the XCFramework in the "Frameworks, Libraries, and Embedded Content" section in the General target's tab.
Static Framework
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 bundleThreeDS-SDK-Resources.bundle
In your project, add the XCFramework in the "Frameworks, Libraries, and Embedded Content" section in the General target's tab.
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:
Name | Description | Website | License | Version |
---|---|---|---|---|
ASN1Decoder | Used to parse keys and certificates in ASN1 structure | https://github.com/filom/ASN1Decoder | MIT license | 1.2 |
GMEllipticCurveCrypto | Security framework used for Elliptic Curve keys | https://github.com/ricmoo/GMEllipticCurveCrypto | BSD 2-Clause "Simplified" License | 1.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 been focused on two widely used hybrid frameworks: Flutter and React Native. The subsequent sections provide guidance on integrating the framework.
Flutter
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.
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.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, usesetMethodCallHandler()
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.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 callmethodChannel.invokeMethod("initSDK")
to initialize the SDK ormethodChannel.invokeMethod("createTransaction")
to create a transaction.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
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.
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 importThreeDS_SDK-Swift.h
andThreeDS_SDK.h
to be able to make 3DS SDK calls.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.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 callNativeModules.ThreeDSSDK.initializeSdk()
whereThreeDSSDK
is the name of the Objective-C module (name of the interface that imports the RCTBridgeModule) andinitializeSdk()
is the name of the exposed method.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.