SDK Integration

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

Gradle Setup

As a first step, the Netcetera Android 3DS SDK needs to be declared as dependency to the Application or Library. That can be done using Gradle, via Maven repository or referencing it as local artefact.

Via Maven Repository

The best way of including the 3DS SDK into your Android Application or Library can be done by publishing the AAR and POM files to a private Maven repository.

Once it has been published, in the Application's or Library's gradle.build declare dependency on it:

Via Local Artefact

To avoid publishing to Maven repository, the AAR artefact can be included as local library to the project. In this case, all the dependencies will need to be added manually.

Steps to be performed:

  • Add the provided 3ds-sdk-2.X.X.X.aar artefact to the libs/ directory of your Application or Library. For example, for Application module named app, this directory would be app/libs/.
  • Add the Netcetera Android 3DS SDK dependency in the Application or Library build.gradle file:
  • Add the external dependencies as described in Dependencies chapter.

Bundling Netcetera 3DS SDK into another Android Library

The Netcetera Android 3DS SDK can be bundled into another Android Library with the purpose of delivering the integration as a single artefact to a client.

The Android Gradle Plugin doesn't yet support official way of bundling an Android Library into another Android Library and there are no reliable third party plugins of performing such operation. The safest option is to do it manually with the steps described.

  1. Extract the Netcetera Android 3DS SDK by renaming the `.aar` artefact to `.zip`.
  2. Move the resulting `classes.jar` into the Android Library module's `libs` folder. Make sure artefacts in the `libs` are included as dependencies.

    Note: The classes.jar contains some additional binaries other than ".class" and will only be packaged correctly in the other library when using Android Gradle Plugin 3.5.0 or greater.

  3. Move the contents of the `jni` folder into the Android Library module's `src/main/jniLibs/`. Not all native compiled libraries (`.so`) have to be included, only the ones that the integrator Android Library wants to support. For example, `mips` and `armeabi` can be freely excluded since the market share is very low. The final result shall look similar to this:
    .
└── main
   └── jniLibs
      ├── arm64-v8a
      │   └── <contents from the `jni/arm64v8a`>
      ├── armeabi
      │   └── <contents from the `jni/armeabi`>
      ├── armeabi-v7a
      │   └── <contents from the `jni/armeabi-v7a`>
      ├── mips
      │   └── <contents from the `jni/mips`>
      ├── x86
      │   └── <contents from the `jni/x86`>
      └── x86_64
          └── <contents from the `jni/x84_64`>
  4. Add the DS Logos from `res/` into the Android Library drawable resources. The name of the resources have to stay the same in order to be referencable by the Netcetera Android 3DS SDK. Not needed logos can be removed, but the default configuration for the removed DS Logos will not work. Final structure shall look similar to this:
    .
└─ main
   └── res
       ├── drawable
       │   ├── ds_logo_amex.xml
       │   ├── ds_logo_mastercard.xml
       │   ├── ds_logo_visa.xml
       │   └── <Other Drawable resources>
       └── values
           └── values.xml
  5. Add the external dependencies as described in Dependencies chapter.
  6. Copy the proguard rules from `proguard.txt` into your consumer proguard rules.

As a result from all the steps, the Netcetera Android 3DS SDK classes will be able to be used in the integrating Android Library and once it is build, it will be included in the resulting .aar artefact.

Android Studio Javadoc Setup

In order for Android Studio to be able to show Javadoc for the API of the Netcetera Android 3DS SDK, it needs to include the 3ds-sdk-javadoc.jar that was delivered as part of the delivery package.

For including, please follow these steps:

  • Open the External Libraries in the Android Studio tree-view
  • Locate the Android Netcetera 3DS SDK library
  • Right click and open Library Properties...
  • Using the '+' button, add the delivered Javadoc. It will be automatically detected as Javadoc type.

Dependencies

Certain external dependencies need to be provided in order for the Netcetera Android 3DS SDK to work as intended. These required dependencies with their exact version are listed in the delivered Maven POM file.

If this SDK was included in the project Via Maven Repository, the gradle build system will include the external dependencies automatically and they don't need to be included in the build.gradle file. If the SDK is included via local artefact or bundled into other Android library check the Maven pom file for the dependencies that need to be included.

Third-party libraries

The following table contains all the third-party libraries that are used in the Android 3DS SDK.

The libraries that are marked as embedded are pre-bundled into the SDK codebase and therefore not needed to be added as dependencies by the Requestor application. Libraries that are not embedded must be added by the Requestor application as dependencies with the provided obfuscation exception rules.

NameWebsiteArtifactEmbedded in the SDKLicense
jose.4.jhttps://bitbucket.org/b_c/jose4j/org.bitbucket.b_c:jose4j
✔
Apache 2.0
Bouncy Castlehttps://www.bouncycastle.org/org.bouncycastle:bcprov-jdk15to18
✘
MIT license
Simple Logging Facade for Javahttps://www.slf4j.org/org.slf4j:slf4j-api
✘
MIT license
* Google Play Services Basehttps://maven.google.com/web/index.html?#com.google.android.gms:play-services-basecom.google.android.gms:play-services-base
✘
Android Software Development Kit License
* AndroidX AppCompat Libraryhttps://maven.google.com/web/index.html?#androidx.appcompat:appcompatandroidx.appcompat:appcompat
✘
Apache 2.0

Dependencies marked with * are optional, however it is strongly recommended that they be included

Code Optimizing and Obfuscating

In order the Netcetera Android 3DS SDK to work as intended, the bytecode of the provided SDK shall not be modified in any way. The simplest way of achieving this is to exclude everything from optimization and obfuscation in the com.netcetera.threeds.sdk package.

Besides configuring the optimization and obfuscation for the SDK, a configuration optimization and obfuscation for the dependencies of the SDK shall be added. A configuration for each dependency that is not embedded in the SDK shall be added. Use the table above to check which dependencies are embedded in the SDK.

Below are some popular obfuscation tools and the rules with which they need to be configured in order for the Netcetera Android 3DS SDK to function properly.

ProGuard

The Netcetera Android 3DS SDK comes pre-bundled with the relevant ProGuard rules, so integrators do not have to include any additional rules in their own ProGuard configuration.

DexGuard

For integrators relying on DexGuard, the following DexGuard rules need to be included in order for the Netcetera Android 3DS SDK to function properly.

Integration in Hybrid Frameworks

This section details the integration of the 3DS SDK Android library 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 Android libraries, 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 library.

Flutter

This section outlines the steps required to integrate the Netcetera 3DS SDK into a Flutter app for Android. This integration allows developers to leverage the functionalities of the 3DS SDK within their Flutter applications seamlessly.

  1. SDK Integration: Begin by adding the Netcetera Android 3DS SDK as a dependency in your Flutter project. You can achieve this by including the SDK in your build.gradle file using Gradle, or by referencing it from a Maven repository. Alternatively, if you have the SDK files locally, you can add it as a local artifact.

  2. Create Native Method Channel: To communicate between your Dart code and the native Android 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 Android code that interacts with the 3DS SDK. 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 between Dart and native code, as Java objects cannot be sent directly to Dart. Use JSON or HashMap values for this purpose.

React Native

This section outlines the steps to integrate the Netcetera Android 3DS SDK into a React Native project.

  1. SDK Integration: To integrate the Netcetera Android 3DS SDK into your React Native project, start by adding the SDK as a dependency. You can do this by including the SDK in your project's build.gradle file using Gradle, or by referencing it from a Maven repository. Alternatively, you can add the SDK as a local artifact if you have the SDK files available locally.

  2. Create Native Module: Next, create a native module in Java or Kotlin to handle the 3DS SDK functionality. This native module will serve as a bridge between your React Native JavaScript code and the native Android code that interacts with the 3DS SDK. You can create the native module file (e.g., ThreeDSModule.java or ThreeDSModule.kt) inside the android/app/src/main/java/com/your-app-name/ folder. The native module should extend ReactContextBaseJavaModule and implement the necessary functionality required by JavaScript. All native module methods meant to be invoked from JavaScript must be annotated with @ReactMethod.

  3. Register Native Module: After creating the native module, you need to register it with React Native. To do this, create a ReactPackage (e.g., ThreeDSPackage) that includes your native module and register the package with React Native. In the createNativeModules method of your ThreeDSPackage class, instantiate and add your ThreeDSModule to the list of native modules. Finally, in your MainApplication.java or MainApplication.kt file, add your ThreeDSPackage to the list of packages returned by the getPackages method.

  4. Invoke Native Methods: With the native module registered, you can now use its methods in your React Native JavaScript code. Import the NativeModules module from React Native and access your ThreeDSModule using NativeModules.ThreeDSModule. You can then call the methods exposed by your native module, such as initializeThreeDSService, passing appropriate callbacks to handle success and error cases.