Cards SDK for iOS

The Cards SDK is a solution to ease the integration with the Alviere services.

Features
Requirements
Installation
- SPM
- CocoaPods
- Carthage
- Manual
Usage
Alternative Usage
Text and Localization

Features

Card Issuance

Requirements

iOS 13.0+
Xcode 15+
Swift 5.5+

Installation

Swift Package Manager

1. Add the dependency to your project. Open your project and navigate to your project’s settings. Select the tab named Swift Packages and click on the add button + at the bottom left.

2. Enter the url of Cards SDK for the iOS repository (https://github.com/Alviere/alviere-cards-ios) in the text field and click Next.

3. On the next screen, select the SDK version and click Next.

4. Select the CardsSDK package and click Finish.

5. Repeat the same process for AlCore SDK (https://github.com/Alviere/alviere-core-ios). The current version is compatible with AlCore SDK version 0.9.0 and up.

CocoaPods

1. Get the latest version of CocoaPods, if you haven’t already.

2. Create the Podfile by running the following command, if you don’t have one already.

pod init

3. Add this line to your Podfile.

pod 'CardsSDK'

4. Run the following command to install the library. Also, run this to update to newer releases in the future.

pod install

Carthage

1. Get the latest version of Carthage, if you haven’t already.

2. Add the following entries in your Cartfile:

binary https://raw.githubusercontent.com/Alviere/alviere-core-ios/master/AlCore.json
binary https://raw.githubusercontent.com/Alviere/alviere-cards-ios/master/CardsSDK.json

3. Run the following command to download the latest version of the SDK.

carthage update --use-xcframeworks

4. Follow the Manual instructions below to embed the SDK into your project.

Manual

1. Get the latest versions of CardsSDK.xcframework and AlCore.xcframework and embed them into your application by dragging and dropping the files onto the Frameworks, Libraries and Embedded Content project section, as shown below.

2. Depending on the location of CardsSDK.xcframework and AlCore.xcframework on the filesystem you may need to change the Framework Search Paths build setting to avoid the error: fatal error: ‘CardsSDK/CardsSDK.h’ file not found. For example, the Xcode project below have it set to FRAMEWORK_SEARCH_PATHS = $(PROJECT_DIR)/../ since the xcframeworks files are shared between them and are kept in the directory that also contains the project directories.

Usage

To initialize the Cards SDK for iOS, you need to set the Environment at the entry point of your application. For example, you can do this on your AppDelegate file on the application(_:,didFinishLaunchingWithOptions:) method, as shown below.

import AlCore

...

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Setup Alviere SDK.
    if !AlCoreSDK.shared.setEnvironment(.sandbox) {
        print("Error initializing SDK.")
    }
    return true
}

After this setup, you just need to import the Cards SDK for iOS on the files where you want to use the features.

import CardsSDK

Card Issuance

Adopt the CardIssuanceDelegate Protocol

This can be handled, for instance, by the view controller object that will call the card actions.

extension ViewController : CardIssuanceDelegate

The CardIssuanceDelegate methods are the main communication backchannel to your application for the card management on Cards SDK for iOS. For each action there is one method associated as follows:

Create Card: didCreateCard(_:)
List Cards: didListCards(_:)
Get Card: didGetCard(_:)
Get Card Image: didGetCardImage(_:)
Get Card Sensitive Data: didGetCardSensitiveData(_:)
Update a Card: didUpdateCard(_:)
Activate Card: didActivateCard()
Set Card State: didSetCardState(_:)
Cancel Card: didCancelCard()

There is also a global method didHandleEvent(_,metadata:) to receive events, like errors for instance. This enables your application to gain further insight into what is going on as the user goes through the Cards SDK flow. In case of an error, you may want to display error-related information to the user and have them try doing the action again.

func didHandleEvent(_ event: String, metadata: [String : String]?) {
    print("Received event: \(event)\nmetadata: \(metadata ?? [:])")
}

The event keys are defined on the Event enum and the metadata keys on Metadata enum.

Create Card

To issue a new card, use createCard where you will need to create a new auth_token, pass the walletUuid and the CardRequest model with the data, and pass the CardIssuanceDelegate delegate instance.

let model = CardRequest( ... )

AlCards.shared
    .createCard(token: authToken,
                walletUuid: walletUuid,
                data: model,
                delegate: self)

The result of this action will return the newly issued Card model on the didCreateCard(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didCreateCard(_ card: Card) {
    print("New card issued is:\n\(card)")
}

Create Non Reloadable Prepaid Card

To issue a new card, use createNonReloadablePrepaidCard where you will need to create a new auth_token, pass the cardholder accountUuid and the NonReloadablePrepaidCardRequest model with the data, and pass the CardIssuanceDelegate delegate instance.

let model = NonReloadablePrepaidCardRequest( ... )

AlCards.shared
    .createNonReloadablePrepaidCard(token: authToken,
                                    accountUuid: accountUuid,
                                    data: model,
                                    delegate: self)

The result of this action will return the newly issued Card model on the didCreateCard(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didCreateCard(_ card: Card) {
    print("New card issued is:\n\(card)")
}

List Cards

To get all users’ cards you will need to create a new auth_token, and pass the walletUuid and the CardIsuanceDelegate delegate instance.

AlCards.shared
    .listCards(token: authToken,
               walletUuid: walletUuid,
               delegate: self)

The result of this action will return all user-issued Card list on the didListCards(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didListCards(_ cards: [Card]) {
    print("User cards are:\n\(cards)")
}

Get Card

To get a single user card you will need to create a new auth_token, pass the walletUuid and the cardUuid of the card, and the CardIsuanceDelegate delegate instance.

AlCards.shared
    .getCard(token: authToken,
             walletUuid: walletUuid,
             cardUuid: cardUuid,
             delegate: self)

The result of this action will return the user-issued Card on the didGetCard(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didGetCard(_ card: Card) {
    print("User card is:\n\(card)")
}

Get Card Image

To get a card image you will need to create a new auth_token, pass the walletUuid and the cardUuid of the card, and the CardIsuanceDelegate delegate instance.

AlCards.shared
    .getCardImage(token: authToken,
                  walletUuid: walletUuid,
                  cardUuid: cardUuid,
                  delegate: self)

The result of this action will return the card image UIImage on the didGetCardImage(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didGetCardImage(_ image: UIImage) {
    print("User card image is:\n\(image)")
}

Get Card Sensitive Data

To get a card sensible details you will need to create a new auth_token, pass the walletUuid and the cardUuid of the card, and the CardIsuanceDelegate delegate instance.

AlCards.shared
    .getCardSensitiveData(token: authToken,
                          walletUuid: walletUuid,
                          cardUuid: cardUuid,
                          delegate: self)

The result of this action will return the card sensitive data CardSensitiveData on the didGetCardSensitiveData(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didGetCardSensitiveData(_ cardSensitiveData: CardSensitiveData) {
    print("User card is:\n\(cardSensitiveData)")
}

Update a Card

There is the possibility to update a card authorization rules. To do that you will need to create a new auth_token, pass the walletUuid value, the cardUuid of the card, the UpdateCardRequest model with the updated authorization rules, and the CardDelegate delegate instance.

let model = UpdateCardRequest( ... )

AlCards.shared
    .updateCard(token: authToken,
                walletUuid: walletUuid,
                cardUuid: cardUuid,
                data: model,
                delegate: self)

The result of this action will return the updated Card model on the didUpdateCard(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didUpdateCard(_ card: Card) {
    print("User card updated:\n\(card)")
}

Activate Card

To activate a card you will need to create a new auth_token, pass the walletUuid value, the cardUuid of the card, the ActivateCardRequest model with the card activation data, and the CardDelegate delegate instance.

let model = ActivateCardRequest( ... )

AlCards.shared
    .activateCard(token: authToken,
                  walletUuid: walletUuid,
                  cardUuid: cardUuid,
                  data: model,
                  delegate: self)

The result of activating a card will return a confirmation on the didActivateCard() delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didActivateCard() {
    print("Did activate a card.")
}

Set Card Pin

To set a card’s pin you will need to create a new auth_token, pass the walletUuid value, the cardUuid of the card, the SetCardPinRequest model, and the CardDelegate delegate instance.

let model = SetCardPinRequest( ... )

AlCards.shared
    .setCardPin(token: authToken,
                walletUuid: walletUuid,
                cardUuid: cardUuid,
                data: model,
                delegate: self)

The result of setting a card’s pin will return a confirmation on the didSetCardPin() delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didSetCardPin() {
    print("Did set a card's pin.")
}

Set Card State

To set the card state, use setCardState. Currently, you can change the card state to:

Frozen
Unfrozen

The result of changing the card state will return the new state on the didSetCardState(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didSetCardState(_ state: CardState) {
    print("Did set card state to \(state).")
}

Freeze Card

To set a card on the frozen state you will need to create a new auth_token, pass the walletUuid and the cardUuid of the card, and the CardDelegate delegate instance.

AlCards.shared
    .setCardState(token: authToken,
                  walletUuid: walletUuid,
                  cardUuid: cardUuid,
                  state: .frozen,
                  delegate: self)

Unfreeze Card

To set a card on the unfrozen state you will need to create a new auth_token, pass the walletUuid and the cardUuid of the card, and the CardDelegate delegate instance.

AlCards.shared
    .setCardState(token: authToken,
                  walletUuid: walletUuid,
                  cardUuid: cardUuid,
                  state: .unfrozen,
                  delegate: self)

Cancel Card

To cancel a user card you will need to create a new auth_token, pass the walletUuid and the cardUuid of the card, and the CardDelegate delegate instance.

AlCards.shared
    .cancelCard(token: authToken,
                walletUuid: walletUuid,
                cardUuid: cardUuid,
                delegate: self)

The result of this action will return a confirmation on the didCancelCard() delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didCancelCard() {
    print("User card is cancelled!")
}

Reissue or Replace Card

To reissue or replace a user card you will need to create a new auth_token, pass the cardUuid of the card, the ReissueReplaceCardRequest model with the request data, and the CardDelegate delegate instance.

let model = ReissueReplaceCardRequest( ... )

AlCards.shared
    .reissueOrReplaceCard(token: authToken,
                          cardUuid: cardUuid,
                          data: model,
                          delegate: self)

The result of this action will return the new reissued/replaced Card model on the didReissueOrReplaceCard(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didReissueOrReplaceCard(_ card: Card) {
    print("User card reissed or replaced:\n\(card)")
}

Digital Wallet

⚠️

Adding payment passes requires a special entitlement issued by Apple. Your app must include this entitlement before this class can be instantiated. For more information on requesting this entitlement, see the Card Issuers section at developer.apple.com/apple-pay.

Adopt the DigitalWalletDelegate protocol

This can be handled, for instance, by the view controller object that will present the UI.

extension ViewController : DigitalWalletDelegate

The DigitalWalletDelegate methods are the main communication backchannel to your application for the tokenized card management on Payments SDK for iOS. For each action there is one method associated as follows:

Add a Card: didAddCard()

func didHandleEvent(_ event: String, metadata: [String : String]?) {
    print("Received event: \(event)\nmetadata: \(metadata ?? [:])")
}

The event keys are defined on the Event enum and the metadata keys on Metadata enum.

Add Card

To add a card you need to present the included UI objects. The result of tokenizing a card will return the card on the didAddCard() delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didAddCard() {
    print("Card was added to Digital Wallet with success")
}

Add Card UI Presentation

Presenting the Add Card is as simple as creating a new auth_token, using it to initialize AlCards, and get/register the DigitalWalletAddCardViewController instances.

Presenting Add Card View Controller

⚠️

Be aware that you should present the DigitalWalletAddCardViewController from a PKAddPassButton (as shown below), for more info refer to PKAddPassButton’s documentation.

Creating the `PKAddPassButton`

A PKAddPassButton is instantiated in the same way as a regular UIButton. After instantiating a PKAddPassButton you can change its appearance by assigning a value to the addPassButtonStyle property.

let button: PKAddPassButton = PKAddPassButton()
button.addPassButtonStyle = .blackOutline
button.addTarget(self, action: #selector(action), for: .touchUpInside)

@objc func action() {
    // TODO: Present `DigitalWalletAddCardViewController`.
}

From code

To instantiate DigitalWalletAddCardViewController from code, use createAddCardToWalletViewController where you will need to create a new auth_token, pass the DigitalWalletDelegate delegate instance, pass a account_uuid, pass a card_uuid, pass the cardholder_name and pass the last_four_digits of the card. You can either present the newly created view controller by with present.

⚠️

Be aware that instantiating the DigitalWalletAddCardViewController might fail and in that case it will return nil.

let viewController = AlCards.shared
    .createAddCardToWalletViewController(token: authToken,
                                         delegate: self,
                                         accountUuid: accountUuid,
                                         cardUuid: cardUuid,
                                         cardholderName: cardholderName,
                                         lastFourDigits: lastFourDigits)

self.present(viewController, animated: true)

Incentives

Adopt the IncentivesDelegate Protocol

This can be handled, for instance, by the view controller object that will call the incentives actions.

extension ViewController : IncentivesDelegate

The IncentivesDelegate methods are the main communication backchannel to your application for the incentive management on Cards SDK for iOS. For each action there is one method associated as follows:

List Incentives: didListIncentives(_:)
Get Incentive: didGetIncentive(_:)

func didHandleEvent(_ event: String, metadata: [String : String]?) {
    print("Received event: \(event)\nmetadata: \(metadata ?? [:])")
}

The event keys are defined on the Event enum and the metadata keys on Metadata enum.

List Incentives

To get all incentives you will need to create a new auth_token, and pass the IncentivesDelegate delegate instance.

AlCards.shared.listIncentives(
    token: authToken,
    query: query,
    delegate: self)

The result of this action will return all IncentiveRule list on the didListIncentives(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didListIncentives(_ incentives: [IncentiveRule]) {
    print("Incentives are:\n\(incentives)")
}

Get Incentive

To get a single incentive you will need to create a new auth_token, pass the ruleUuid of the incentive, and the IncentivesDelegate delegate instance.

AlCards.shared.getIncentive(
    token: authToken,
    ruleUuid: ruleUuid,
    delegate: self)

The result of this action will return the IncentiveRule on the didGetIncentive(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didGetIncentive(_ incentive: IncentiveRule) {
    print("Incentice is:\n\(incentive)")
}

Alternative Usage

The SDK can also be integrated using Closures, Combine or Async/Await methods. They can be accessed respectively by:

Closures - A closure can be passed instead of the delegate.
Combine - AlCards.shared.combine can be used to access methods that return Combine Future objects.
Async/Await - AlCards.shared.async can be used to access async methods.

Text and Localization

The Cards SDK for iOS allows you to customize the UI text. To do so, you will need to redefine the localization key that you want to change on your Localizable.strings file. The next section details a list of the current localization keys. Currently, the SDK only provides english localization.

Localization Keys

Key	English Value
alviere_sdk_cards_digital_wallet_card_description	(If not overridden this key will provide the default system value)

Cards SDK for iOS

Features

Requirements

Installation

Swift Package Manager

CocoaPods

Carthage

Manual

Usage

Card Issuance

Adopt the CardIssuanceDelegate Protocol

Create Card

Create Non Reloadable Prepaid Card

List Cards

Get Card

Get Card Image

Get Card Sensitive Data

Update a Card

Activate Card

Set Card Pin

Set Card State

Freeze Card

Unfreeze Card

Cancel Card

Reissue or Replace Card

Digital Wallet

Adopt the DigitalWalletDelegate protocol

Add Card

Add Card UI Presentation

Presenting Add Card View Controller

Creating the PKAddPassButton

From code

Incentives

Adopt the IncentivesDelegate Protocol

List Incentives

Get Incentive

Alternative Usage

Text and Localization

Localization Keys

Creating the `PKAddPassButton`