This section provides detailed information on how to integrate the Netcetera 3DS SDK into an Android Application or Library.
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.
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:
1 2 3 | dependencies { implementation 'com.netcetera.android-3dssdk:3ds-sdk:2.0.0'} |
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 adeded manually.
Steps to be performed:
1 2 3 | dependencies { implementation files('libs/3ds-sdk-1.0.0.aar')} |
The Netcetera Android 3DS SDK can be bundled into another Android Library with the purpose of delivering the integration as 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.
dependencies {
implementation fileTree(dir: 'libs', include: ['*.jar'])
}
. └── 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`>
. └─ main └── res ├── drawable-hdpi-v4 │ ├── ds_logo_amex.webp │ ├── ds_logo_mastercard.webp │ ├── ds_logo_visa.webp │ └── <Other Drawable resources> ├── drawable-mdpi-v4 │ ├── ds_logo_amex.webp │ ├── ds_logo_mastercard.webp │ ├── ds_logo_visa.webp │ └── <Other Drawable resources> ├── drawable-xhdpi-v4 │ ├── ds_logo_amex.webp │ ├── ds_logo_mastercard.webp │ ├── ds_logo_visa.webp │ └── <Other Drawable resources> ├── drawable-xxhdpi-v4 │ ├── ds_logo_amex.webp │ ├── ds_logo_mastercard.webp │ ├── ds_logo_visa.webp │ └── <Other Drawable resources> └── drawable-xxxhdpi-v4 ├── ds_logo_amex.webp ├── ds_logo_mastercard.webp ├── ds_logo_visa.webp └── <Other Drawable resources>
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.
The EMVCo 3DS Specification mandates that TLS 1.2 is used for secure communication between the 3DS Components. From Android 4.1, TLS 1.2 is supported, but due to the nature of the Android OS, there are devices where this is not the case.
To ensure support for TLS 1.2 on Android 4.4, the Security Provider of the Android device needs to be patched with Google Play GMS Security Provider. If it is required, the Netcetera 3DS SDK will try to perform the patch.
In order the Netcetera 3DS SDK to be able to perform this patch, it requires Google Play Services API. Least intrusive way to do this, is to include Google Play Service Base.
To define the license, use the ConfigParameters.addParam(...) with the following arguments:
| Argument | Value |
|---|---|
| group | null |
| paramName | "license-key" |
| paramValue | The content of the license file. |
1 | configParameters.addParam(null, "license-key", "eyJhbGciOiJ..."); |
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 this steps:
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.
| Name | Website | License | |
|---|---|---|---|
| Findbugs JSR305 | https://github.com/findbugsproject/findbugs/ | Apache 2.0 | |
| Apache Commons | http://www.apache.org/ | Apache 2.0 | |
| Simple Logging Facade for Java | https://www.slf4j.org/ | MIT license | |
| jose.4.j | https://bitbucket.org/b_c/jose4j/ | Apache 2.0 | |
| Bouncy Castle | https://www.bouncycastle.org/ | MIT license | |
| OkHttp | https://github.com/square/okhttp/ | Apache 2.0 | |
| Android-TiffBitmapFactory | https://github.com/Beyka/Android-TiffBitmapFactory/ | MIT license |
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 in the Dependencies shall be added.
Sample Proguard configuration can be found in the Netcetera Demo Merchant and the source code of it.
Starting with Android 9 (API level 28), cleartext support is disabled by default. This means that Applications targeting this or higher version of Android will not allow HTTP requests by default (HTTPS calls are unaffected). While EMVCo 3DS Specification requires the communication between the 3DS SDK and the ACS to go through HTTPS, 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 Behavior changes: apps targeting API level 28+: Network TLS enabled by default