Cards SDK for iOS

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

Features

  • Card Management

Requirements

  • iOS 11.0+
  • Xcode 12+
  • Swift 5.3+

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.

image

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.

image

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

image

4. Select the CardsSDK package and click Finish.

image

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.

image

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.

image

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 Management

Adopt the CardDelegate Protocol

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

extension ViewController : CardDelegate

The CardDelegate 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:

  • Issue a Card: didIssueCard(_:)
  • Get Card: didGetCard(_:)
  • Get All Cards: didGetCards(_:)
  • 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.

Issue a Card

To issue a new card, use issueCard where you will need to create a new auth_token, pass the accountUuid and the IssueCardRequest model with the data, and pass the CardDelegate delegate instance.

let model = IssueCardRequest( ... )

AlCards.shared
    .issueCard(token: authToken,
               accountUuid: accountUuid,
               cardData: model,
               delegate: self)

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

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

Get Card(s)

To get all cards or a specific card of a user, use getAllCards and getCard, respectively.

Get All Cards

To get all users’ cards you will need to create a new auth_token, and pass the accountUuid and the CardDelegate delegate instance. Pay attention that on this request the cardImage field has no value.

AlCards.shared
    .getAllCards(token: authToken,
                 accountUuid: accountUuid,
                 delegate: self)

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

func didGetCards(_ 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 accountUuid and the cardId of the card, and the CardDelegate delegate instance.

AlCards.shared
    .getCard(token: authToken,
             accountUuid: accountUuid,
             cardId: cardId,
             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)")
}

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 accountUuid value, the cardId of the card, the UpdateCardRequest model with the upadted authorization rules, and the CardDelegate delegate instance.

let updatedCardData = UpdateCardRequest( ... )

AlCards.shared
    .updateCard(token: authToken,
                accountUuid: accountUuid,
                cardId: cardId,
                cardData: updatedCardData,
                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 accountUuid value, the cardId of the card, the ActivateCardRequest model with the card activation data, and the CardDelegate delegate instance.

let activationData = ActivateCardRequest( ... )

AlCards.shared
    .activateCard(token: authToken,
                  accountUuid: accountUuid,
                  cardId: cardId,
                  cardData: updatedCardData,
                  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 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).")
}

Froze Card

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

AlCards.shared
    .setCardState(token: authToken,
                  accountUuid: accountUuid,
                  cardId: cardId,
                  state: .frozen,
                  delegate: self)

Unfroze Card

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

AlCards.shared
    .setCardState(token: authToken,
                  accountUuid: accountUuid,
                  cardId: cardId,
                  state: .unfrozen,
                  delegate: self)

Cancel Card

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

AlCards.shared
    .cancelCard(token: authToken,
                accountUuid: accountUuid,
                cardId: cardId,
                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!")
}