UI SDK for iOS

CocoaPods

Welcome to the Apto iOS UI SDK. This SDK provides access to Apto's mobile platform, and provides a pre-built / standard UI/UX flow to onboard cardholders and enable users to manage their cards.

Note: If you want to control the UI/UX, use the Mobile SDK.

You can quickly set up a UI/UX cardholder experience by dropping the SDK into your existing application or distributing it as a standalone mobile application. Some UI/UX elements may be configured to match your organization's branding look and feel, such as fonts, themes and enabled features.

Note: Branding features such as the card background image and colors of various UI elements (i.e. Buttons) require configuration changes on Apto Payment's backend. Please contact us for more information.

This document provides an overview of how to:

Note: The UI SDK automatically imports the PCI SDK. Therefore, the main screen will display a view provided by the PCI SDK.

You can access the iOS UI SDK on GitHub.

To contribute to the SDK development, see Contributions & Development

Requirements#

  • iOS 12.0 (minimum version)
  • Xcode 12 (minimum version)
  • Swift 5 (minimum version)
  • CocoaPods. No minimum version is required, but version 1.8.3 or higher is recommended.

Get the Mobile API key#

A Mobile API Key is required to run the SDK. To retrieve your Mobile API Key see Get the Mobile API Key for the SDKs.

Install the SDK#

We suggest using CocoaPods to install the SDK.

Note: Ensure you have a Podfile created in your app's root project directory using pod init while Xcode is closed.

  1. In your project's Podfile:

    • At the top of the file, ensure the platform specified is set to iOS 12 and frameworks are enabled:
    platform :ios, '12.0'
    ...
    • Add the Apto and AptoPCI iOS SDK pod dependencies to your app's target and save the file:
    platform :ios, '12.0'
    target '<YourApp>' do
    use_frameworks!
    pod 'AptoUISDK'
    ...
    end
  2. Open your Terminal app, and navigate to your project's directory containing the Podfile using cd and install the SDK by running the following pod install command:

    cd <PATH_TO_YOUR_PROJECT_FOLDER>
    pod install

Initialize the SDK#

Follow the steps below to initialize the SDK:

  1. Open the workspace (.xcworkspace) for your app with Xcode.

  2. Open the UIViewController subclass for a view in your app.

  3. Initialize the Apto UI SDK by invoking initializeWithApiKey() and replacing <MOBILE_API_KEY> in the following example with your API key from the Apto Developer Portal. This fully initializes the SDK for your application:

class ViewController: UIViewController {
override func viewDidLoad() {
super.viewDidLoad()
AptoPlatform.defaultManager().initializeWithApiKey("<MOBILE_API_KEY>")
}
}

The default environment selected is the production environment (.production). If you would like to use the sandbox environment, you must set the optional environment parameter to .sandbox:

AptoPlatform.defaultManager().initializeWithApiKey("<MOBILE_API_KEY>", environment: .sandbox)

Start the Cardholder Onboarding Flow#

Once the SDK is initialized, you can implement our pre-built cardholder onboarding flow. The onboarding flow enables users to verify their credentials, log in, and manage their cardholder information. For an example of the cardholder onboarding UI/UX screens, view the Apto Developer Guides.

To start the cardholder onboarding flow, initiate the card UI flow process by invoking startCardFlow() and passing in your UIViewController subclass and ShiftCardModuleMode values:

AptoPlatform.defaultManager().startCardFlow(from: self, mode: .standalone) { [weak self] result in
switch result {
case .failure(let error):
// handle error
case .success(let module):
// SDK successfully initialized
}
}

The callback closure has a single Result<UIModule, NSError> parameter. Use the result object for error handling, or to add additional features once the SDK is successfully initialized.

Note: When testing in the sandbox environment, you must use 000000 as the OTP code when prompted by the UI. For more information, see the Getting Started guides

The startCardFlow method has two required parameters and two optional parameters:

ParameterRequired?Description
fromYesThe UIViewController subclass where the SDK is initialized. This is used to present the SDK to the user.
modeYesA ShiftCardModuleMode value defining how the SDK is opened and closed. The available modes are:
  • embedded: This mode displays a close option on the manage card screen, enabling the user to close the card UI and return to the main application view. We recommend using this mode when starting the Apto UI SDK from an existing app.
  • standalone: This mode enables the SDK to only be closed via the logout process. We recommend using this mode if your application is only using the Apto UI SDK and no has other features.
optionsNoThe UI SDK has multiple features that can be enabled / disabled. This parameter is used to enable / disable card-management features and can be used to define the card theme and fonts. See CardOptions Parameters for more information.
initialUserDataNoThe initialization data that will be stored on the Apto servers.
initializationData can contain the following values values:
  • userMetadata - A string attached to the user data after sign up.
  • cardMetadata - A string attached to the card after issuance.
  • custodianUid - A string attached to the user after sign up. The value refers to the user ID in your platform.
  • design See Issue Card Design Parameters for more information.

Note: The first three values may be a string up to 256 characters.

Issue Card Design Parameters (Enterprise Only)#

ParameterRequired?TypeDescription
designKeyNoString up to 30 charactersThe identifier for the design which will be applied to the card.
qrCodeNoString up to 256 charactersThe URL for the QR code image which will be printed on the card.
extraEmbossingLineNoString up to 25 charactersText for the embossed line that will be applied to the card. (This is located under the cardholder name.)
imageUrlNoString up to 256 charactersThe image that will be printed on the card.
additionalImageUrlNoString up to 256 charactersThe secondary image that will be added to the card.

CardOptions Parameters#

The UI SDK retrieves all card design configurations from our servers and applies the configurations to the included PCI SDK. This ensures the correct card styles and design are shown to the user, including:

  • Card Background
  • Card Text Colors

Use the CardOptions object to customize the card management features and card themes and fonts.

Some of the features that can be customized are:

  • Enable / Disable management of:

    • Account Settings
    • Stats
    • Funding Source
    • Notification Preferences
    • Detailed Card Transaction Activity
    • Monthly Statements
  • Authentication Settings

  • Card Theme

  • UI opening display mode

  • Font Options

  • Card logo and design

    Note: If you need to customize the logo and/or card design, it will need to be configured on our servers. You will need to send us a 969px × 612px png file of the entire card, including the background, company logo, and network logo (i.e., Visa, Mastercard, etc.). Once your PNG file is set up, the UI SDK will communicate with our servers to retrieve the PNG file and display it to the user. Please contact us for more information.

The CardOptions object can accept multiple unordered parameters. No parameters are required to create a CardOptions object.

let options = CardOptions(features:fontCustomizationOptions:)

The available parameters are:

The CardOptions object has two parameters:

ParameterDescription
featuresThis parameter accepts a dictionary of FeatureKey-Bool key-value pairs. Each key-value pair represents a feature.

See FeatureKey Options for more information.
fontCustomizationOptions (optional)This is a ThemeFontDescriptors object used to specify a custom font for the card UI. If no font customization options are specified, the SDK will use the system font.

See The fontCustomizationOptions Parameter for more information.

FeatureKey Options#

The available FeatureKey options are:

ParameterDefault ValueDescription
supportDarkModefalseControls if the UI's dark theme is enabled.
showStatsButtonfalseControls if the Stats button is displayed. This enables the user to see their monthly consumption statistics.

Stats button
showAccountSettingsButtontrueControls if the Account Settings button is displayed. This enables the user to see the account settings screen.

Account Settings button
showActivateCardButtontrueControls if the SDK displays the Enable your physical card button. This button enables the user to activate a physical card.
showNotificationPreferencesfalseControls if the user can customize their notification preferences.
showDetailedCardActivityOptionfalseControls if the user can view detailed transaction activity (i.e., declined transactions).
showMonthlyStatementsOptiontrueControls if the user can view their monthly statements.
authenticateOnStartupfalseControls if the user must authenticate their account (using a passcode or biometrics), when the app starts or after returning from background mode. Enabling this option will require the user to create a passcode when signing up.
authenticateWithPINOnPCIfalseControls if the user must authenticate using their passcode instead of the SMS/email code, prior to viewing their full card data. The available options for this CardOptions.PCIAuthType setting are:
  • PIN_OR_BIOMETRICS
  • BIOMETRICS
  • NONE


Note: If biometric authentication is enabled, it will appear first. The user may choose to cancel biometric authentication and use their passcode instead.

The fontCustomizationOptions Parameter#

The fontCustomizationOptions parameter specifies custom fonts for the UI. The parameter may be one of the following object types:

ThemeFontDescriptors Object#

The fontCustomizationOptions parameter specifies custom fonts for the UI. A ThemeFontDescriptors object can have up to four typeface parameters:

  • regular
  • medium
  • semibold
  • bold

Note: Although no parameters are required to create a ThemeFontDescriptors object, we recommend you use one of the following options:

  • Set no typefaces, and use the default phone fonts for the UI.
  • Set all four typefaces to provide consistent fonts throughout the UI.

To create a ThemeFontDescriptors object, pass in a UIFontDescriptor object for each font type:

let descriptors = ThemeFontDescriptors(regular: UIFontDescriptor(name:"XYZ-Regular", size: 10),
medium: UIFontDescriptor(name:"XYZ-Medium", size: 10),
semibold: UIFontDescriptor(name:"XYZ-Semibold", size: 10),
bold: UIFontDescriptor(name:"XYZ-Bold", size: 10))

Use the resulting ThemeFontDescriptors object as the fontCustomizationOptions parameter for the CardOptions object:

let options = CardOptions(features: [:], fontCustomizationOptions: .fontDescriptors(descriptors))

Custom Font using UIFontProviderProtocol#

To use a custom font, create a custom class that implements UIFontProviderProtocol. This protocol enables you to have complete control over the fonts types and sizes shown in the card UI.

Note: You will need to modify the protocol within one of your classes to implement the different styles, but handle with care, as it may break the look and feel of the card UI.

To specify the fontCustomizationOptions parameter with a custom class implementing the UIFontProviderProtocol, wrap the provider in the .fontProvider() method:

let provider = MyCustomFontProvider()
let options = CardOptions(features: [:], fontCustomizationOptions: .fontProvider(provider))

Google Maps API Key parameter#

The Google Maps API key is an optional parameter (googleMapsApiKey) in the startCardFlow method. The parameter's default value is nil and enables you to specify a Google Maps API Key to be used by the SDK.

Note: This parameter is required if you are using our UI to collect an address from your user, otherwise you can disregard it.

Contributions & Development#

We look forward to receiving your feedback, including new feature requests, bug fixes, and documentation improvements.

If you would like to help:

  1. Refer to the issues section of the repository first, to ensure your feature or bug doesn't already exist (the request may be ongoing, or a newly-finished task).
  2. If your request is not in the issues section, please feel free to create one. We'll get back to you as soon as possible.

If you want to help improve the SDK by adding a new feature or bug fix, we'd be happy to receive pull requests!