iOS
This document contains the Programmable Wallets SDK reference for iOS development.
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 |
---|
/// Singletonpublic 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.
Updated 19 days ago