Various Topics
Table of contents
Security Warnings
At initialization time the SDK performs several security checks. As a result it may produce a list of warning for the application to inspect and decide whether it would be safe to perform authentication on the device. The list of warnings is this:
Security Warning | Severity | Description |
---|---|---|
SW01 | HIGH | Jailbroken device |
SW02 | HIGH | The SDK has been tempered |
SW03 | HIGH | An emulator is being used to run the app |
SW04 | MEDIUM | Debugger is attached |
SW05 | HIGH | Unsupported OS version |
The application calls getWarnings as shown below:
List<Warning> warnings = threeDS2Service.getWarnings();
if (!warnings.isEmpty()) {
// got one or more warnings, inspect them:
for(Warning warning: warnings) {
// use warning.getID() or warning.getSeverity() to inspect
}
}
Directory servers
The SDK is bundled with the following directory servers:
DS Identifier (RID) | Provider Name | Key Expiration Date |
---|---|---|
A000000003 | Visa | 08/22/2024 |
A000000004 | Mastercard | 06/15/2026 |
A000000025 | American Express | 08/19/2023 |
A000000065 | JCB | 03/03/2051 |
A000000152 | Discover | 03/07/2027 |
A000000042 | Carte Bancaire | 03/10/2024 |
SANDBOX_DS | Sandbox DS | 11/13/2029 |
The application, can pass additional directory servers to the SDK.
Android
To pass an additional direcrtory server(s) to the SDK for Android:
ConfigParameters configParameters = new ConfigParameters();
DirectoryServer customDs = new DirectoryServer(
"DS Identifier", "DS key ID", "DS key", "DS certificate", "DS Name");
customDs.setDsLogo(dsLogo);
configParameters.addDirectoryServer(customDs)
Note, the example shows the pure 3DS interface, to do the same using the simplified interface, the ConfigParameters class needs to be prepared as shown above but passed to the SDK within InitSpec rather.
iOS
var configParams: UConfigParameters {
let params = UConfigParameters()
let newDS = UDirectoryServer(
dsid: "DS Identifier", publicKey: "DS Key",
keyID: "DS key ID", dsCACertificate: "DS certificate",
providerName: "DS Name", dsLogo: UIImage(name: "DS Logo"))
params.add(newDS)
return params
}
Note, to adjust the code sample to the simplified interface, just pass the UConfigParameters
in InitSpec
rather.
Customizing the challenge screen
The SDK lets the app to override the default look and feel of the challenge screen. When needed, the application developer passes an instance of UICustomization class to the SDK in ConfigParams at initialization time.
UICustomization
class is essentially a holder for a set of concrete customizations:
ButtonCustomization
- let’s to customize the UI of buttons on the challenge screenTextBoxCustomization
- customize text fieldsToolbarCustomization
- the toolbarLabelCustomization
- labels.
Each of the customizations have their own properties, it is recommended to inspect the classes to see their structures.
Simplified interface
UICustomization uiCustomization = new UICustomization();
// Configure textbox customization
TextBoxCustomization tbc = new TextBoxCustomization()
tbc.setBorderColor("#AAAAAA");
uiCustomization.setTextBoxCustomization(tbc);
// Put it in InitSpec
InitSpec initSpec = new InitSpec();
initSpec.setUiCustomization(); // if UICustomization is necessary
// Initialize the SDK
threeDS2Service.initialize(initSpec, ...);
Pure 3DS interface
UICustomization uiCustomization = new UICustomization();
// Configure label customization:
LabelCustomization lc = new LabelCustomization();
lc.setHeadingTextFontName("Verdana");
lc.setHeadingTextFontSize(18);
uiCustomization.setLabelCustomization(lc)
// Initialize the SDK
service.initialize(..., ..., ..., uiCustomization);
Best Practices
The EMVCo 3DS specification allows for the “empty” initialization of any of the Customization
objects. However, it is expected that if a Customization
object is created, then the properties of that object will be filled. If no UI customization is desired, then simply passing an “empty” UUiCustomization
object will indicate to the SDK to use preset defaults for all challenge screen UI.
Examples
If no customization of UI elements on challenge screens is desired, do this:
sdk.u_initialize(..., uiCustomization: UUiCustomization())
Do NOT do this:
sdk.u_initialize(..., uiCustomization: UUiCustomization(with: ULabelCustomization(), textBoxCustomization: UTextBoxCustomization(), toolbarCustomization: UToolbarCustomization()))
If customization of UI elements on challenge screens is desired, do this:
// Init objects
let customization = UUiCustomization()
let labelCustomization = ULabelCustomization()
let textBoxCustomization = UTextBoxCustomization()
let toolBarCustomization = UToolbarCustomization()ß
// Fill properties
labelCustomization.setTextFontName("<some font name (as listed within iOS)>")
labelCustomization.setTextColor("<some color hex code>")
labelCustomization.setTextFontSize(12) // whatever size you want
labelCustomization.setHeadingTextColor("<some color hex code>")
labelCustomization.setHeadingTextFontName("<some font name (as listed within iOS)>")
labelCustomization.setHeadingTextFontSize(18) // whatever size you want
textBoxCustomization.setTextColor("<some color hex code>")
textBoxCustomization.setBorderColor("<some color hex code>")
textBoxCustomization.setTextFontSize(12) // whatever size you want
textBoxCustomization.setTextFontName("<some font name (as listed within iOS)>")
textBoxCustomization.setCornerRadius(1) // whatever corner radius you want
textBoxCustomization.setBorderWidth(1) // whatever border width you want
for buttonType in [UButtonType.submit, UButtonType.cancel, UButtonType.resend] {
let buttonCustomization = UButtonCustomization()
buttonCustomization.setTextColor("<some color hex code>")
buttonCustomization.setTextFontName("<some font name (as listed within iOS)>")
buttonCustomization.setTextFontSize(12) // whatever size you want
buttonCustomization.setCornerRadius(1) // whatever corner radius you want
buttonCustomization.setBackgroundColor("<some color hex code>")
customization.setButton(buttonCustomization, with: buttonType)
}
customization.setLabel(labelCustomization)
customization.setTextBox(textBoxCustomization)
Crash Reporting
It is a recommended practice to integrate crash reporting software into your mobile app. This will capture any crashes of your app including any caused by mSIGNIA’s uSDK. Typically, crash reporting software will include a stack trace for crashes as well. At mSIGNIA, we use Sentry.io. The following documentation is based on Sentry, but any crash reporting software should be similar.
Android
To add Sentry.io SDK to your app update your build.gradle file as follows:
// Make sure mavenCentral is there.
repositories {
mavenCentral()
}
// Enable Java 1.8 source compatibility if you haven't yet.
android {
compileOptions {
sourceCompatibility = JavaVersion.VERSION_1_8
targetCompatibility = JavaVersion.VERSION_1_8
}
}
// Add Sentry's SDK as a dependency.
dependencies {
implementation 'io.sentry:sentry-android:5.2.1'
}
Add your DSN to the manifest file.
<application>
<meta-data android:name="io.sentry.dsn" android:value="your DSN here" />
</application>
iOS
Install via Cocoapods
platform :ios, '10.0'
use_frameworks!
target 'ThreeDS-Sample' do
pod 'Sentry', :git => 'https://github.com/getsentry/sentry-cocoa.git', :tag => '7.4.0'
end
Integrate into AppDelegate
import UIKit
import Sentry
@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
var window: UIWindow?
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
SentrySDK.start { options in
options.dsn = "YOUR_DSN_URL (Provided by Sentry)"
options.debug = true // Enabled debug when first installing is always helpful
}
return true
}
}