Get started with the UI SDK

📘
Please visit the new version of our documentation here.

The Karhoo Mobile UI SDK offers an end-to-end cab booking experience, from quoting to driver tracking. It enables our partners to add Karhoo Mobility Exchange functionality into their own apps - without any additional maintenance or redesign.

With the Karhoo Mobile UI SDK, you can:

Quickly build white-labeled apps
View/Update your card details
Retrieve quotes
Book a trip (ASAP/Prebook)
Receive trip updates
Track driver
See current and past bookings
Rating your trip

Add the UISDK to your project

We run our SDK's under a BSD 2-Clause License . By downloading and using the Karhoo SDK's you are acknowledging that you will adhere to this license agreement.

iOS

The Karhoo iOS UISDK is compatible with iOS 11 and above.

Add the following to your podfile:

source 'https://github.com/CocoaPods/Specs.git'

pod 'KarhooSDK'
pod 'KarhooUISDK'

Android

The Karhoo Android SDK is compatible with Android 5.0 Lollipop and above.

Ensure that you have added your Google Maps API key to your app level manifest file within your application tag.

In the root level build.gradle file, in all projects, add the cardinalcommerce Maven repo.

Add the following to your Gradle build file

// Add your google maps key to your Manifest xml
<meta-data
    android:name="com.google.android.maps.v2.API_KEY"
    android:value="${google_maps_api_key}" />

// Add the following into your Root level build.gradle
allprojects {
    repositories {
        ... // Other maven repos for your project
        maven { url 'https://jitpack.io' }
        maven {
            url "https://cardinalcommerce.bintray.com/android"
            credentials {
                username 'braintree-team-sdk@cardinalcommerce'
                password '220cc9476025679c4e5c843666c27d97cfb0f951'
            }
        }
    }
}

//In your app dependancies add the latest UISDK verison
implementation 'com.github.karhoo:karhoo-android-ui-sdk:1.3.1'

Getting Started

iOS

To configure the SDK you will need to provide an implementation of our KarhooUISDKConfiguration interface. This lets our SDK grab certain dependencies and configuration settings.

struct KarhooUIConfig: KarhooUISDKConfiguration {
  
    // logo used on side menu and trip completion pop up
    func logo() -> UIImage {
        return UIImage("")!
    }

    func environment() -> KarhooEnvironment {
        return .sandbox
    }
  
    func authenticationMethod() -> AuthenticationMethod {
    	return .karhooUser
    }
}

// register configuration (AppDelegate) before any usage of the SDK
KarhooUI.set(configuration: KarhooUIConfig())

Android

KarhooUISDKConfiguration interface also needs an implementation within your project.

class KarhooUIConfig(val context: Context): KarhooUISDKConfiguration {

    override fun logo(): Drawable? {
        return context.getDrawable(R.drawable.your-logo)
    }

    override fun environment(): KarhooEnvironment {
        return KarhooEnvironment.Sandbox()
    }

    override fun context(): Context {
        return context
    }
  
    override fun authenticationMethod(): AuthenticationMethod {
    	return AuthenticationMethod.KarhooUser()
    }
}

// register configuration in your Application file
KarhooUISDK.setConfiguration(KarhooConfig(applicationContext))

Authentication

In addition, there are 3 different authentication methods that can be used:

Username/password
Token authentication
Guest authentication

The AuthenticationMethod is set as part of the configuration. The sample code above is the config for username/password.

Token authentication

You will first need to integrate your external authentication system with the Karhoo platform before initialising the SDK with your client id.

iOS

// set up KarhooSDKConfiguration implementation
struct KarhooSDKConfig: KarhooSDKConfigurationProvider {

  func environment() -> KarhooSDKConfiguration {
       return .sandbox
   }
 
  func authenticationMethod() -> AuthenticationMethod {
    	return .tokenExchange(clientId: "your-app-id", scope: "openid profile email phone https://karhoo.com/traveller")
   }
}

//App Delegate
Karhoo.set(configuration: KarhooSDKConfig())

Android

// set up KarhooSDKConfiguration
import com.karhoo.sdk.api.KarhooEnvironment
import com.karhoo.sdk.api.KarhooSDKConfiguration

class KarhooSDKConfig : KarhooSDKConfiguration {

    override fun environment(): KarhooEnvironment {
        return KarhooEnvironment.Sandbox()
    }

    override fun context(): Context {
        return context
    }
  
    override fun authenticationMethod(): AuthenticationMethod {
    	return AuthenticationMethod.TokenExhange(clientId = "your-app-id", scope = "openid profile email phone https://karhoo.com/traveller"
    }
}

//Application file
KarhooApi.setConfiguration(configuration = KarhooSDKConfig(context = this.applicationContext))
})

Guest users

iOS

// set up KarhooSDKConfiguration implenmentation
struct KarhooSDKConfig: KarhooSDKConfigurationProvider {

  func environment() -> KarhooSDKConfiguration {
       return .sandbox
   }
 
  func authenticationMethod() -> AuthenticationMethod {
    	return .guestSettings(identifier: "client_identifier", referer: "referer", organisationId: "organisation_id")
   }
}

//App Delegate
Karhoo.set(configuration: KarhooSDKConfig())

Android

// set up KarhooSDKConfiguration
import com.karhoo.sdk.api.KarhooEnvironment
import com.karhoo.sdk.api.KarhooSDKConfiguration

class KarhooSDKConfig : KarhooSDKConfiguration {

    override fun environment(): KarhooEnvironment {
        return KarhooEnvironment.Sandbox()
    }

    override fun context(): Context {
        return context
    }
  
    override fun authenticationMethod(): AuthenticationMethod {
    	return AuthenticationMethod.Guest(identifier = "client_identifier", referer = "referer", organisationId = "organisation_id")
    }
}

//Application file
KarhooApi.setConfiguration(configuration = KarhooSDKConfig(context = this.applicationContext))
})

Payment Method Setup

There are two possible payment options for the trips booked through the SDKs. An invoicing flow where Karhoo will invoice your organisation at the end of the month, or Karhoo acting as the merchant of record.

Invoicing Model

Invoicing is the fastest approach to test the SDKs as no payment set up is required. This method also works well for B2B/corporate travel use cases. On both Android and iOS, invoicing flows can be used by not adding a ‘nonce’ to your booking request payload when using the trip service.

Karhoo as the merchant of record

The KarhooUISDK makes use of the Braintree payment drop in. Braintree have a selection of Sandbox credit cards for testing purposes that can be used to make bookings.

Specifically, the KarhooUISDK uses Braintree to make 3DSecure payments. Work is required within your project to enable the 3DSecure flow to execute correctly. These can be found in the integration guidelines on the Braintree documentation site. For iOS, you will need to register a URL type and for Android a URL scheme for browser switching

Authentication Setup

Using the KarhooSDKs (either Network or UI) requires authenticating the Network SDK.

Karhoo User

Users are managed and secured within our platform. These users are created under organisations and are utilised in B2B scenarios, platform testing and proof of concept development.

To authenticate with basic auth you will need to use the user service. The login endpoint can be found here: https://developer.karhoo.com/reference#user-service-login A username and password will be issued to you when you're ready to start testing and making bookings.

Book with your users (3rd Party Auth)

The token exchange method exchanges your users access token for a Karhoo users access token. This involves a backend Curity integration between your authentication system and Karhoo’s authentication system to map and manage user permissions. This functionality can be accessed through the AuthService in the KarhooSDK. https://developer.karhoo.com/reference#login-token

Guest user

Using a client key and referer identifier issued by Karhoo, you can allow anyone to book a taxi on the marketplace.