Using the iOS SDK {#concept_blv_1bc_fqb} ======================================== A mobile SDK is available for integrating payer authentication services into mobile applications running on the iOS platform. Downloading and Importing the SDK {#reference_h5r_rr2_xpb} ========================================================== Download the *CardinalMobile.framework* file using the cURL program in this example. Download CardinalMobile.framework ``` curl -L -u <USER_NAME> :<API_KEY> https://cardinalcommerceprod.jfrog.io/artifactory/ios/<VERSION>-<BUILD_NUMBER>/cardinalmobilesdk.zip -o <LOCAL_FILE_NAME.EXT> #Example: curl -L -u UserName:ApiKey "https://cardinalcommerceprod.jfrog.io/artifactory/ios/2.2.5-1/cardinalmobilesdk.zip" -o cardinalmobile2.2.5-1.zip ``` Download the *CardinalMobile.xcframework* file using the cURL in this example. Download CardinalMobile.xcframework ``` curl -L -u <USER_NAME> :<API_KEY> https://cardinalcommerceprod.jfrog.io/artifactory/ios/<VERSION>-<BUILD_NUMBER>/CardinalMobileiOSXC.zip -o <LOCAL_FILE_NAME.EXT> #Example: curl -L -u UserName:ApiKey "https://cardinalcommerceprod.jfrog.io/artifactory/ios/2.2.5-1/CardinalMobileiOSXC.zip" -o cardinalmobile2.2.5-1.zip ``` In your XCode project, drag the *CardinalMobile.framework* file into the Frameworks group in your Xcode Project. (Create the group if it does not already exist.) In the import dialog box, check the box to Copy items into the destinations group folder (or Destination: Copy items if needed). The iOS SDK files are now available for linking in your project. Configuring Your Build Environment {#task_bbs_hr2_xpb} ====================================================== Follow these to configure your build environment: 1. Open Xcode, and in the source list to the left of the main editor area, choose your project. 2. Under the Targets section, select your application and open the **General** tab. 3. Expand the Embedded Binaries section and click the small plus (**+**) at the bottom of the list. 4. From the list, add the **CardinalMobile.framework** file. Configuring the iOS SDK {#reference_sr5_1c2_xpb} ================================================ Use **CardinalSession new** to create a new instance of the cardinal object. Use the default configuration options. Study these examples to complete the iOS SDK configuration. For more details on configuration options, refer to the table after the examples. CardinalSession new (iOS SDK - Objective-C) ``` #import <CardinalMobile/CardinalMobile.h> CardinalSession *session; //Setup can be called in viewDidLoad - (void)setupCardinalSession { session = [CardinalSession new]; CardinalSessionConfiguration *config = [CardinalSessionConfiguration new]; config.deploymentEnvironment = CardinalSessionEnvironmentProduction; config.timeout = CardinalSessionTimeoutStandard; config.uiType = CardinalSessionUITypeBoth; UiCustomization *yourCustomUi = [[UiCustomization alloc] init]; //Set various customizations here. See "iOS UI Customization" documentation for detail. config.uiCustomization = yourCustomUi; CardinalSessionRenderTypeArray *renderType = [[CardinalSessionRenderTypeArray alloc] initWithObjects: CardinalSessionRenderTypeOTP, CardinalSessionRenderTypeHTML, nil]; config.renderType = renderType; config.enableQuickAuth = false; [session configure:config]; } ``` CardinalSession new (iOS SDK - Swift) ``` import CardinalMobile var session : CardinalSession! //Setup can be called in viewDidLoad func setupCardinalSession{ session = CardinalSession() var config = CardinalSessionConfiguration() config.deploymentEnvironment = .production config.timeout = 8000 config.uiType = .both let yourCustomUi = UiCustomization() //Set various customizations here. See "iOS UI Customization" documentation for detail. config.uiCustomization = yourCustomUi config.renderType = [CardinalSessionRenderTypeOTP, CardinalSessionRenderTypeHTML] config.enableQuickAuth = true session.configure(config) } ``` | Method | Description | Default Values | Possible Values | |:-----------------------|:------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | deploymentEnviron ment | The environment to which the SDK connects. | CardinalSessionEnviron mentProduction | CardinalSession Environment Staging CardinalSessionEnvi ronment Production | | timeoutInMilli seconds | Maximum amount of time (in milliseconds) for all exchanges. | 8000 | | | uiType | Interface types that the device supports for displaying specific challenge user interfaces within the SDK. | CardinalSessionUIType Both | CardinalSessionUIT ypeBoth CardinalSessionUIT ypeNative CardinalSessionUIT ypeHTML | | renderType | List of all the render types that the device supports for displaying specific challenge user interfaces within the SDK. | \[CardinalSessionRend erTypeOTP, CardinalSessionRend erTypeHTML, CardinalSessionRend erTypeOOB, CardinalSessionRend erTypeSingleSelect, CardinalSessionRend erTypeMultiSelect\] | CardinalSessionRen derType OTP CardinalSessionRen derType HTML CardinalSessionRen derType OOB CardinalSessionRen derType SingleSelect CardinalSessionRen derType MultiSelect | | proxyServerURL | Proxy server through which the Cardinal SDK Session operates. | nil | | | enableQuickAuth | Enable Quick Authentication | false | | | uiCustomization | Set Custom UICustomization for SDK-Controlled Challenge UI. | nil | | | enableDFSync | Enable DF Sync to get onSetupCompleted called after collected device data is sent to the server. | false | | [iOS Configuration Options] Setting Up the Initial Request {#reference_ezk_h1f_xpb} ======================================================= Requesting the *cardinal session setup* process begins the communication process, authenticates your credentials (server JWT), and completes the data collection process. By the time the customer is ready to check out, all necessary preprocessing is complete. Each time a user begins a mobile transaction, a unique value is assigned to the consumerSessionId API field to identify the session. This value ensures that the correct device data collection results are matched to each user request. `Cybersource` uses its payerAuthEnrollService_referenceID field to contain Cardinal's consumerSessionId value. You must assign the value of the consumerSessionId field to the payerAuthEnrollService_referenceID field so that `Cybersource` can also track the requests for each user session. Study these code examples to understand how to complete setting up the cardinal session process. The function request must be placed in your Checkout ViewController. Cardinal session setup (iOS SDK - Objective-C) ``` NSString *accountNumberString = @"1234567890123456"; NSString *jwtString = @"INSERT_YOUR_JWT_HERE"; [session setupWithJWT:jwtString didComplete:^(NSString * _Nonnull consumerSessionId){ // // You may have your Submit button disabled on page load. Once you are // setup for CCA, you may then enable it. This will prevent users // from submitting their order before CCA is ready. // } didValidate:^(CardinalResponse * _Nonnull validateResponse) { // Handle failed setup // If there was an error with setup, cardinal will call this // function with validate response and empty serverJWT }]; ``` Cardinal session setup (iOS SDK - Swift) ``` let accountNumberString = "1234567890123456" let jwtString = "INSERT_YOUR_JWT_HERE" session.setup(jwtString: jwtString, completed: { (consumerSessionId: String) in // // You may have your Submit button disabled on page load. Once you // are setup for CCA, you may then enable it. This will prevent // users from submitting their order before CCA is ready. // }) { (validateResponse: CardinalResponse) in // Handle failed setup // If there was an error with setup, cardinal will call this // function with validate response and empty serverJWT } ```