Integrate the Ivy Flow into the client side of your iOS app by utilising the Ivy iOS SDK.
Installation
Requirements
- Xcode 14+
- Swift 5.7+
CocoaPods
CocoaPods is a dependency manager for Cocoa projects.
Specify GetivySDK into your project's Podfile
:
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '11.0'
use_frameworks!
pod 'GetivySDK'
Then run the following command:
pod install
Swift Package Manager
Swift Package Manager is a tool for managing the distribution of Swift code.
After you set up your Package.swift
manifest file, you can add GetivySDK as a dependency by adding it to the dependencies value of your Package.swift
.
dependencies: [
.package(url: "https://github.com/getivy/ios-sdk-prod.git", from: "1.0.0")
]
Carthage
Carthage is a simple, decentralized dependency manager for Cocoa.
Specify GetivySDK into your project's Cartfile
:
github "getivy/ios-sdk-prod" ~> 1.0
Manual
- Clone GetivySDK as a git submodule by running the following command from your project root git folder.
git submodule add https://github.com/getivy/ios-sdk-prod.git
- Open the GetivySDK folder created by the previous git submodule command and drag the
GetivySDK.xcodeproj
into the Project Navigator of your application's Xcode project. - Select the
GetivySDK.xcodeproj
in the Project Navigator and verify the deployment target matches with your application deployment target. - Select your project in the Xcode Navigation and then select your application target from the sidebar. Next select the "General" tab and click on the + button under the "Embedded Binaries" section.
- Select
GetivySDK.framework
and you are done!
Payment Integration
Check here for an overview over Payment integrations.
Before starting the flow, you must create a CheckoutSession
with the Ivy API. You will be returned an id
after creating the session. When creating the session, you can specify things like the default market and language to smoothen your customer's journey. Please take a look at the API Reference for more information.
Create a GetivyConfiguration
After receiving the sessionId
, you must create a GetivyConfiguration
to start the flow. You can do so with the constructor GetivyConfiguration()
. It takes the arguments checkoutSessionId
, onSuccess
and onError
. In case of success, onSuccess
will be executed, and vice-versa onError
in case of failure.
// Create an SDK configuration
let config = GetivyConfiguration(
checkoutId: <checkout session id>, // String. The id which is returned after creating a new checkoutSession
environment: "sandbox" | "production", // The environment, the flow should be started in.
onSuccess: { result in
// Retrieve the result data from the Ivy API
},
onError: { error in
// Show error message to user
}
)
Initialize Handler
Use the configuration to initialize a handler. The handler is a UIHandler
which can be opened with the openUI()
and a specified PresentationMethod
.
// initialize Handler
Getivy.shared.initializeHandler(configuration: config, type: .checkout) { handler, error in
handler?.openUI(viewController: self) // Set a view controller for SDK to present its UI and start the flow
}
In case you want to control the UI presentation use a different method when opening UI view a handler
handler?.openUI(presentationCosure: { sdkViewController in
// presentation closure will get called with a reference to the main SDK view controller so the app can control the presentation
}, dismissalClosure: { sdkViewController in
// dismiss callback indicates that SDK should be removed from the app UI in case it finished or there was a non recoverable error
})
Data Integration
Check here for an overview over Data integrations.
Before you can start the flow, you must first create a DataSession
with the Ivy API. You will be returned an id
after creating the session. When creating the session, you can specify things like the default market and language to smoothen your customer's journey. Please take a look at the API Reference for more information.
Create a GetivyConfiguration
After receiving the sessionId
, you must create a GetivyConfiguration
to start the flow. You can do so with the constructor GetivyConfiguration()
. It takes the arguments dataSessionId
, onSuccess
and onError
. In case of success, onSuccess
will be executed, and vice-versa onError
in case of failure.
// Create an SDK configuration
let config = GetivyConfiguration(
dataSessionId: <data session id>, // String. The ID which is returned after creating a new data session
environment: "sandbox" | "production", // The environment, the flow should be started in.
onSuccess: { result in
// Retrieve the result data from the Ivy API
},
onError: { error in
// Show error message to user
}
)
Initialize Handler
You can use the configuration to initialize a handler. The handler is a UIHandler
, which can be opened with the openUI()
and a specified PresentationMethod
.
// initialize Handler
Getivy.shared.initializeHandler(configuration: config) { handler, error in
handler?.openUI(viewController: self) // Set a view controller for SDK to present its UI and start the flow
}
In case you want to control the UI presentation, use a different method when opening UI view a handler
handler?.openUI(presentationCosure: { sdkViewController in
// presentation closure will get called with a reference to the main SDK view controller so the app can control the presentation
}, dismissalClosure: { sdkViewController in
// dismiss callback indicates that SDK should be removed from the app UI in case it finished or there was a non recoverable error
})
Result Handling
OnSuccess
When creating SDK configuration, you can specify the onSuccess
callback. If the user successfully finishes the flow, this closure is called. It returns the result object, which contains the dataSessionId
for Data Integrations or the orderId
for Payment Integrations and the referenceId
of the completed flow.
onSuccess: { result in
// Retrieve the result data from the Ivy API
},
Callback Parameters:
Parameter | Type | Description |
---|---|---|
result.orderId / result.dataSessionId | String | The Ivy ID of the data session |
result.referenceId | String | The referenceId set when creating the data session |
OnError
When creating the SDK configuration, you can specify the onError
callback. If the user successfully does not finish the flow, this closure is being called. It returns the error object, which contains the dataSessionId
for Data Integrations or the orderId
for Payment Integrations and the referenceId
of the failed flow.
onError: { error in
// Let the user try again
},
Callback Parameters:
Parameter | Type | Description |
---|---|---|
error.code | String | This field provides a short string indicating the reported error code. |
error.message | String | A human-readable message that provides additional details about the error. |