Swiftpack.co - Package - karhoo/karhoo-ios-sdk

Karhoo iOS Network SDK

KarhooSDK is a framework for integrating with the KarhooAPI: https://developer.karhoo.com

Read The Docs

Installation

CocoaPods

You can use CocoaPods to install KarhooSDK by adding it to your Podfile:


use_frameworks!
pod 'KarhooSDK', '~> 1.2.2'

then import KarhooSDK wherever you want to access Karhoo services

import KarhooSDK

Carthage

Create a Cartfile that lists the framework and run carthage update. Follow the instructions to add $(SRCROOT)/Carthage/Build/iOS/YourLibrary.framework to an iOS project.

github "Karhoo/Karhoo-ios-sdk"

Swift Package Manager

The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the swift compiler and Xcode 11+

Once you have your Swift package set up, adding Karhoo as a dependency is as easy as adding it to the dependencies value of your Package.swift.

dependencies: [
.package(url: "https://github.com/Karhoo/karhoo-ios-sdk.git", .upToNextMajor(from: "1.2.2"))
]

Usage

Initialisation

There are a few things the SDK needs to know before you can get started. Such as what environment to connect to, or what kind of authentication method to use. These dependencies can be set up in an implementation of the KarhooSDKConfiguration protocol.

import KarhooSDK

struct YourCompanyKarhooConfiguration: KarhooSDKConfiguration {
    
    func environment() -> KarhooEnvironment {
        return .sandbox
    }

    func authenticationMethod() -> AuthenticationMethod {
    // for other authentication methods such as guest or token exchange bookings please see: https://developer.karhoo.com/docs/using-the-network-sdk#authentication
        return .karhooUser
    }
}

With this configuration the SDK can be initialised in your App/SceneDelegate

import KarhooSDK

class AppDelegate: UIResponder, UIApplicationDelegate {

    var window: UIWindow?

    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        Karhoo.set(configuration: YourCompanyKarhooConfiguration())
       ..
        return true
    }
}

For full documentation of SDK services please visit our Developer Portal: https://developer.karhoo.com/reference#user-service

Making Requests

The SDK uses two generic types. Call and PollCall. These are network requests that are going to either make one request or observe the end point over a given interval.

Example Call

let tripService = Karhoo.getTripService()
let tripCancellation = TripCancellation(tripId: "123", cancelReason: .notNeededAnymore)

tripService.cancel(tripCancellation: tripCancellation).execute { result in
    switch result {
    case .success:
        print("Trip cancelled")
    case .failure(let error):
        print("error: \(error.code) \(error.message)")
    }
}

Example PollCall

Perhaps you want to monitor a trip and update your UI accordingly. We've made an Observable type that can subscribe / unsubscribe a subject to a publisher.

//ensure your reference for the Observer (Subject) AND the Observable (Publisher) are not confined to the scope of a function otherwise they go out of memory at runtime and your UI won't update.
private var tripTrackingObservable: Observable<TripInfo>?
private var tripTrackingObserver: Observer<TripInfo>?


tripTrackingObserver = Observer<TripInfo>.value { [weak self] tripInfo in
           			print("new trip update! ", tripInfo)
        		}
        
tripTrackingObservable = tripService.trackTrip(identifier: "some-trip-id").observable(pollTime: 5) // where 5 = 5 seconds

tripTrackingObservable?.subscribe(observer: tripTrackingObserver)

// deallocation
tripTrackingObservable?.unsubscribe(observer: tripTrackingObserver)

SDK Architecture overview:

The SDK is split into Services. Services such as Trip, DriverTracking, Availability, User, Payments etc. These services in turn depend on Interactors, these Interactors depend on a request. Simply calling a function in a service will trigger the interactor to call the request. The request uses our HttpClient to make the network call.

Models are encoded/decoded using Decodable structs. These are located in Api/DataObjects/Request /Response groups.

There is a unit test target that tests individual classes work as expected, and there is an integration test target that uses OHHTPStubs to test the sdk works as expected end to end. (from the network layer to a service)

Setup For Development

We use Swift Package Manager to handle the SDK internal dependencies and development. On Xcode 11+, once you've checked out the project you can go to Xcode -> File -> Swift Packages -> Update to Latest Package Versions

Running Tests

There is an Xcode scheme for unit tests and integration tests. Unit tests test the functionality of individual classes using mocked dependencies. The integration tests mock backend responses with JSON contrtacts and ensure the SDK works from input to output.

Client example

There is an example project inside the Client directory of this repository. This is meant to be a fast way to test SDK changes and development steps. You will need to add access Keys to the client module as these are ignored due to this being an open source repository.

struct Keys {
  static let identifier = ""
  ...
}

Issues

Looking to contribute?

🐛 Bugs

Please file an issue for bugs, missing documentation, or unexpected behavior.

💡 Feature Requests

Please file an issue to suggest new features. Vote on feature requests by adding a 👍. This helps maintainers prioritize what to work on.

❓ Questions

For questions related to using the library, please re-visit a documentation first. If there are no answer, please create an issue with a label help needed.

Useful Links

Karhoo Developer Site

The iOS UI SDK

License

BSD-2-Clause

Github

link
Stars: 6

Dependencies

Used By

Total: 0

Releases

1.2.2 - 2020-09-21 17:19:22

1.2.0 - 2020-08-19 12:26:59

Quotes V2: https://developer.karhoo.com/reference#post_

1.1.3 - 2020-07-02 09:57:33

Guest mode specified in analytics event

1.1.2 - 2020-06-30 08:39:24

  • Use carthage to build project
  • Guest vs authenticated user analytics flag

1.1.1 - 2020-05-19 10:36:40

1.1.0 - 2020-05-19 09:25:23