Link Search Menu Expand Document

Various Topics

Table of contents
  1. Security Warnings
  2. Directory servers
    1. Android
    2. iOS
  3. Customizing the challenge screen
    1. Simplified interface
    2. Pure 3DS interface
    3. Best Practices
      1. Examples
  4. Crash Reporting
    1. Android
    2. iOS
      1. Install via Cocoapods
      2. Integrate into AppDelegate

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:

  1. ButtonCustomization - let’s to customize the UI of buttons on the challenge screen
  2. TextBoxCustomization - customize text fields
  3. ToolbarCustomization - the toolbar
  4. LabelCustomization - 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
    }
}