iOS

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:

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: