V 2.2.1 : Cardinal Mobile SDK iOS Documentation Overview

Overview

The Cardinal Mobile SDK for iOS makes it easy for you to activate and integrate Cardinal Consumer Authentication (CCA) into your checkout flow. In just a few simple steps, you will be able to create a great user experience for your consumers, while utilizing the benefits of CCA.

Minimum Requirements 

  • Requires iOS 9 & XCode 8

Prerequisites

Within the Cardinal Mobile SDK ecosystem, authentication between the Merchant and Cardinal is handled via a JWT (JSON Web Token). To initialize the system for processing, a JWT must be generated server-side and passed into the first call in the chain.

Within the JWT, you will need to specify your Org Unit Id, API Key & API Identifier. If you weren't given these values upon registration, please contact your account manager.

For more information on generating a JWT, please see the following instructions:

Generating a Server JWT

API Documentation

We have two implementation options :

1. Cardinal Implementation 

This is a simple 6-Step process to get your application up and running 3DS 2.0 transactions, with the option to customize challenge screens using UI Customization.

Link to documentation: Cardinal Implementation with Optional UI Customization

2. /wiki/spaces/STAG/pages/875298817

This is a 7-Step process to get your application up and running our Quick Auth frictionless flow based on 3DS 1.0 transactions.

Link to documentation: /wiki/spaces/STAG/pages/875298817

Tutorial and Examples

Quick Start guide is available to help you set up your build environment and get started with the Cardinal Mobile SDK by leading you through the creation of a simple application that connects to Cardinal. Within the download package, you will also find a demo app with full source code to help get you started.

Links to our demo application can be obtained by reaching out to your Client Manager or Implementation Manager.

Issues

Please report bugs, comments, or concerns to your Cardinal Implementation Manager

Frequently Asked Questions

iOS Frequently Asked Questions
General FAQs

 Does the SDK support Objective-C/Swift?

Yes, CardinalMobileSDK supports both Objective-C as well as Swift. Code snippets of each programming language can be found in the documentation.

 Does the SDK have any third party SDK/Library dependencies?

No, CardinalMobileSDK does not use any third-party SDK/Library.

 Does the Cardinal Mobile SDK support xcframework?

Yes, Cardinal Mobile SDK is available in both .framework and .xcframework format. Follow the Setting up Cardinal Mobile SDK guide to download and integrate using xcframework.

 Should I Embed & Sign xcframework?

Yes, you should choose Embed & Sign when integrating CardinalMobile.xcframeworkIt adds a copy of the framework into your final bundle while releasing your application.

 What is the size of the SDK 2.2.5-6?

The downloaded framework file size is >3MBOnce integrated with the app that has bitcode support, it adds 774KB if the app is built for both x86 and x64 architecture. 

 How do I remove unused architectures from the app to publish my application?

Cardinal Mobile SDK comes with both device and simulator architectures in it, so merchants can develop, test their application in both simulator and device. Unfortunately, AppStore does not allow publishing applications with simulator architectures in it. To publish the app into AppStore developer must remove unused(simulator) architectures from binary, to achieve this add below run script at the end in your build phases.

Note: This is only applicable when using CardinalMobile.framework (universal binary)

Remove Simulator Architectures
FRAMEWORK_NAME="CardinalMobile" 
find "$PROJECT_DIR" -name '*.framework' -type d | while read -r FRAMEWORK
do
    PATH_COUNT=$(echo "$FRAMEWORK/" | grep -o '/' | wc -l)
    FILE_NAME=$(echo $FRAMEWORK | cut -d '/' -f $PATH_COUNT | cut -d '.' -f 1)
    EXECUTE_FILE="$FRAMEWORK/$FILE_NAME"
    
    if [[ "$EXECUTE_FILE" == *"$FRAMEWORK_NAME"* ]]; then
        echo "Executable framework $EXECUTE_FILE"
        if $(lipo "$FRAMEWORK/$FILE_NAME" -verify_arch x86_64); then
            lipo -remove x86_64 $EXECUTE_FILE -o $EXECUTE_FILE
            lipo -info $EXECUTE_FILE
        fi
        
        if $(lipo "$FRAMEWORK/$FILE_NAME" -verify_arch i386); then
            lipo -remove i386 $EXECUTE_FILE -o $EXECUTE_FILE
            lipo -info $EXECUTE_FILE
        fi
    fi
done
 Why am I getting arm64 error with simulator when building the project with CardinalMobileSDK?


Apple removed arm64 support for simulators with Xcode 12, either remove valid architectures column under user settings or add arm64 to the excluded architectures list, for more information refer to https://developer.apple.com/forums/thread/656509

 Why I am getting error: Building for iOS, but the linked and embedded framework 'CardinalMobile.framework' was built for iOS + iOS Simulator. with Xcode 12.3

This error is due to recent changes in Xcode to resolve this follow the steps below: 

Under Build Settings - Navigate to Validate Workspace - Change it to YES (By Default it is NO)

 Why am I getting an error “Command PhaseScriptExecution failed with a nonzero exit code” when building the project with CardinalMobileSDK?


The run script that strips out the unused architecture from the SDK should be at the bottom of all “Build Phases” so that it executes after “Embed Frameworks”.

 Why am I getting an error “Code signing "CardinalMobile.framework" failed” when building the project with fastlane?


This is mostly because of the presence of simulator components in CardinalMobileSDK, to resolve this add the above run script that strips out the unused architecture from the SDK and it should be at the bottom of all “Build Phases” so that it executes after “Embed Frameworks”. Also, make sure that you select Embed&Sign in your general settings (It is under Target->Genral→Frameworks, Libraries, and Embedded Content→CardinalMobile.framework choose Embed&Sign).


Config FAQs

 Can I test staging credentials in the production environment of SDK?

No, if you are using staging credentials make sure SDK config is set to Staging Environment and switch back to Production Environment when moving to production. SDK is configured to the Production Environment by default.

 Can I customize the Challenge Screens?

Yes, you can customize the certain aspect of the Challenge Screen by setting the UICustomization in SDK Config. See iOS UI Customization v2.2.4 for details.

 Can I use my Custom Font for Challenge Screen?

Yes, you can use the custom font file that is registered with the iOS.

 Can I get Setup Completion Handler called unsafe-only after Data Collection is complete?

Yes, you can set enableDFSync to true in SDK Config to get Setup Completion Handler called after Data Collection is complete. enableDFSync is set to false by default.

Setup/Init FAQs

 Why do I get Invalid JWT Error?

JWT might be invalid if the credentials in the JWT like OrgUnitID, APIKey, APIIdentifiers are invalid or the JWT has expired. Also, make sure the credentials in the JWT point to the correct environment that SDK is set to in the config.

 Will I be notified if Device Data Collection fails?

By default, no. If you want Setup to be successful only after Device Data collection is complete, then enable DF Sync in the SDK Config.

 What if the device doesn't have internet access during Setup call?

OnValidated handler of the Setup will be called with the corresponding error message. 

ProcessBin FAQs

 What if ProcessBin unsafe-onComplete Handler doesn't get called?

If you start ProcessBin without successful completion of Setup/Init, then ProcessBin cannot be completed. Please check the console log for error details.

Continue FAQs

 When can continue() throw an error without showing a challenge screen?

If the parameter you passed to the continue, like TransactionId or Payload is invalid then, continue will throw an error.

 Why is my Payload from Lookup response Invalid?

Make sure the ThreeDSVersion of the lookup response matches with what SDK Supports. SDK does not support 1.0 Payload.

 How can I test different UI in Challenge Screen?

After all initial setup, in continue pass a sample payload of various UI Types to test different UI in Challenge Screens. You can get the sample payload for various UI type from your Client Manager or Implementation Manager.

 Does Failure ActionCode mean there was an error?

No. It means the authentication failed based on the data user provided.