Various Topics

Table of contents

Security Warnings
Directory servers
1. Android
2. iOS
Customizing the challenge screen
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:

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