Integration Docs

Integrate the Ivy Flow into the client side of your Android app by utilising the Ivy Android SDK.

Installation

To integrate the Ivy flow into your Android app, you can install the GetivySDK with GitHub and maven.

Generate Personal Access Token

Register on Github and create a personal access token with read:packages permission. Add your Github username and token as an environmental variables.
Add the following to the Android project build.gradle project:

allprojects {
        repositories {
            maven {
                name = "GitHub"
                url = uri("https://maven.pkg.github.com/getivy/android-sdk-public")
                credentials {
                    username = System.getenv("GITHUB_USER")
                    password = System.getenv("GITHUB_TOKEN")
                }
            }
        }
    }

Replace username and password with:

  • username = GitHub user you used to create the PAT
  • password = GitHub token, i.e. your generated PAT

🚧

Keep these secrets safe at all times!

Add Ivy's dependency

Add the Ivy dependency in your app's app/build.gradle.

dependencies {
    …
    implementation 'io.getivy:sdk:2.+'
    …
}

Start Flow

Before starting the flow, you must create a DataSession or CheckoutSession with the Ivy API, see the API Reference for more information.

You will be returned an id after creating either session. When creating the session, you can specify the default market and language to smoothen your customer's journey. Please take a look at the API Reference for more information.

Data Integration

Check here for an overview over Data Integrations.

After creating the Data Session, use the returned sessionId to create a handler with the createHandler method. By default, a handler is created for data session flow.

GetivySDK.createHandler(
    context = MainActivity.this,
    sessionId = dataSessionIdString,
    type = SDKFlowType.DATA,
    environment = "production")
{ handler ->
    // Retain the handler
    this.handler = handler
}

Payment Integration

Check here for an overview over Payment Integrations.

After creating the Checkout Session, use the returned sessionId to generate a handler with the createHandler method by specifying an extra type parameter.

GetivySDK.createHandler(
    context = MainActivity.this,
    sessionId = checkoutSessionIdString,
    type = SDKFlowType.CHECKOUT,
    environment = "production")
{ handler ->
    // Retain the handler
    this.handler = handler
}

Open handler

Start the Data or Checkout flow by opening the returned handler by calling handler.open. Now, the Client Side Checkout or Data flow is being started.

handler.open { result ->
    when (result) {
      is Handler.Result.Error -> …
      is Handler.Result.Success -> …
    }
}

Handling Result

OnSuccess

When creating the handler, 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 dataId and the referenceId of the completed flow.

is Handler.Result.Success -> { result ->
  /* handle onSuccess */
}

Callback Parameters:

ParameterTypeDescription
result.dataId/ result.orderIdStringThe Ivy Id of the Data session or resulting Order
result.referenceIdStringThe referenceId set when creating the Data or Checkout Session

OnError

When creating 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 result object, which contains the dataId and the referenceId of the completed flow.

is Handler.Result.Error -> { result ->
  /* handle onError */
}

Callback Parameters:

ParameterTypeDescription
result.codeStringThis field provides a short string indicating the reported error code.
result.messageStringA human-readable message that provides additional details about the error.