iOS

The User wallet provides APP SDK in iOS and Android for the customer to integrate. The APP SDK secures the process when users input their secret data, whether as PIN or security answer, and the SDK app encrypts the request body by the secret key.

Due to the security requirement for Circle to control the end-to-end process, the SDK also exposes functionality for the customer to customize the description and layout:

Customize predefined error messages.
Customize the title and subtitle of the UI.
Customize the PIN code input layout.
Set the question list in the UI.
Initialize the SDK to set the endpoint server.
Accept the challengeID and retrieve any operations.

💡
Tip:
To use the SDK in the most flexible way, combine this SDK reference with the iOS SDK UI Customization API article.

SDK Installation

Requirements

The iOS SDK supports:

iOS 13.0+
macOS 12.5+
Xcode 14.1+

*Earlier versions are not supported.

CocoaPods (suggested)

CocoaPods is a dependency manager for Cocoa projects. You can install it with the following command:

$ brew install cocoapods

How to install Homebrew in MacOS: Link

To integrate into your Xcode project using CocoaPods, specify it in your Podfile:

source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/circlefin/w3s-ios-sdk-podspecs.git'

target '<Your Target Name>' do  
  pod 'CircleProgrammableWalletSDK'
end

Then, run the following command:

$ pod install

Manually

Download the iOS SDK here.

iOS SDK

WalletSdk

Public Methods
/// Singleton `public static let shared = WalletSdk()`
/// Set SDK configuration /// - Parameter configuration: Configure the Circle endpoint for SDK to connect /// - Throws: An error is thrown while the configuration is invalid. `public func setConfiguration(_ configuration: Configuration)`
/// Execute the operations by challengeId and call the completion after sending the request to the Circle endpoint. `public func execute(userToken: String, secretKey: String, challengeIds: [String], completion: ExecuteCompletion? = nil)`
/// Set SDK LayoutProvider /// - Parameter provider: WalletSdkLayoutProvider `public func setLayoutProvider(_ provider: WalletSdkLayoutProvider)`
/// Set messenger for custom error messages /// - Parameter messenger: ErrorMessager `public func setErrorMessenger(_ messenger: ErrorMessenger)`
/// Set SDK delegate /// - Parameter delegate: WalletSdkDelegate `public func setDelegate(_ delegate: WalletSdkDelegate)`

WalletSdk.Configuration

public struct Configuration

Fields
String	`endPoint` Init with Circle endpoint. SDK will connect to this endpoint.
String	`appId` AppID from Circle Web3 Services Console

ExecuteCompletion

public typealias ExecuteCompletion = ((ExecuteCompletionStruct) -> Void)

public struct ExecuteCompletionStruct {
  public let challenges: [String]
  public let result: Result<ExecuteResult, ApiError>
  public let onErrorController: UINavigationController?
}

ExecuteCompletionStruct

public struct ExecuteCompletionStruct {
  public let challenges: [String]
  public let result: Result<ExecuteResult, ApiError>
  public let onErrorController: UINavigationController?
}

ExecuteResult

public struct ExecuteResult {
  /// The type of the operation that the challenge represents.
  public let resultType: ChallengeType
  /// The execute result
  public let status: ChallengeStatus
}

ChallengeType

public enum ChallengeType: String, Decodable {
  case SET_PIN
  case CHANGE_PIN
  case RESTORE_PIN
  case SET_SECURITY_QUESTIONS
  case CREATE_WALLET
  case CREATE_TRANSACTION
  case ACCELERATE_TRANSACTION
  case CANCEL_TRANSACTION
  case UNKNOWN
}

ChallengeStatus

public enum ChallengeStatus: String, Decodable {
  case PENDING
  case IN_PROGRESS
  case COMPLETE
  case FAILED
  case EXPIRED
}

ApiError

public struct ApiError

Fields
ApiError.ErrorCode	`errorCode`
String	`errorString` /// Error string from the SDK
String	`displayString` /// Error string for UI display

ApiError.ErrorCode

public enum

case unknown = -1  
case success = 0  
case apiParameterMissing = 1  
case apiParameterInvalid = 2  
case forbidden = 3  
case unauthorized = 4  
case retry = 9  
  
case walletIdNotFound = 156001  
case tokenIdNotFound = 156002  
case transactionIdNotFound = 156003  
case walletSetIdNotFound = 156004  
  
case notEnoughFounds = 155201  
case notEnoughBalance = 155202  
case exceedWithdrawLimit = 155203  
case minimumFundsRequired = 155204  
case invalidTransactionFee = 155205  
case rejectedOnAmlScreening = 155206  
case tagRequired = 155207  
...

WalletSdkLayoutProvider

> Set WalletSdkLayoutProvider for layout customization.

public protocol WalletSdkLayoutProvider: AnyObject {
  /// Set security question list
  ///
  /// - Returns: [SecurityQuestion]
  func securityQuestions() -> [SecurityQuestion]

  /// Set security question required count (default is 2), used in SecurityQuestionsViewController
  ///
  /// - Returns: Int
  func securityQuestionsRequiredCount() -> Int

  /// Set security confirm item list
  ///
  /// - Returns: [SecurityConfirmItem]
  func securityConfirmItems() -> [SecurityConfirmItem]

  /// Set local and remote images
  ///
  /// - Returns: ImageStore
  func imageStore() -> ImageStore

  /// Set theme font programmatically
  ///
  /// - Returns: ThemeFont
  func themeFont() -> ThemeConfig.ThemeFont?

  /// Set the date format for display date strings. (Default is "yyyy-MM-dd")
  /// Reference: https://stackoverflow.com/a/52297497
  ///
  /// - Returns: Date format string
  func displayDateFormat() -> String
}

SecurityQuestion

public struct SecurityQuestion

Fields
String	title The question string
SecurityQuestion.InputType	inputType The input type of the question.

SecurityQuestion.InputType
public enum InputType

text  
datePicker
...

SecurityConfirmItem
public struct SecurityConfirmItem

Fields
UIImage?	Image The drawable resource ID for the introduction item.
URL?	url The remote image url
String	Text The Text for the introduction item.

ImageStore
public struct ImageStore

Fields
[Img: UIImage]	local The images from local
[Img: URL]	remote The images from remote

ImageStore.Img
public enum Img

naviClose  
naviBack  
  
securityIntroMain  
selectCheckMark  
dropdownArrow  
errorInfo  
securityConfirmMain  
...

WalletSdkDelegate

> Methods for managing CircleProgrammableWalletSDK process and customizing controllers.

public protocol WalletSdkDelegate: AnyObject {
  /// Tells the delegate that the SDK is about to be present the controller.
  /// You can customize the layout as you wish dynamically.
  ///
  /// - Parameter controller: The UIViewController to be presented
  func walletSdk(willPresentController controller: UIViewController)

  /// Tells the delegate that the forget PIN button was selected in the controller
  ///
  /// - Parameter controller: Current controller
  /// - Parameter onSelect: Void
  func walletSdk(controller: UIViewController, onForgetPINButtonSelected onSelect: Void)
}

ErrorMessenger

> Define the customized error description. All error codes are listed in ApiError.ErrorCode.

public protocol ErrorMessenger {
  func getErrorString(_ code: ApiError.ErrorCode) -> String?
}

Sample Code

See our sample app guides here.