Track your first user

In this guide, we will setup the HyperTrack SDK in your iOS app and start a Trip. A Trip is a journey that has a location stream, forming a polyline with distance. At the end of the guide, we will visualize the Trip on the dashboard.

If you're on Android, read the Android version of this guide.

Step 1: Install the SDK

To install the SDK, you will need CocoaPods. In your project directory, create a Podfile with the following content. This adds the HTTransmitter pod to your project.

Once the Podfile is configured, install the SDK with the following command.

[warning] Xcode workspace

As with CocoaPods installations, use the .xcworkspace project file to open it in Xcode after the pods have been installed.

use_frameworks!

target 'YourApp' do
   pod 'HTTransmitter'
end
$ pod install

[info] Example app

If you are looking to build an app from scratch, you can use our example iOS app built on the SDK.

Step 2: Configure the SDK

Once the pods have been installed, we can use the SDK methods inside Xcode. The first step is to configure your publishable key in the SDK.

In Objective-C, configure the SDK in application:didFinishLaunchingWithOptions: method of the AppDelegate.

In Swift, configure the SDK in application(_:didFinishLaunchingWithOptions:) method of the AppDelegate.

Configure iOS SDK

@import HyperTrack; //Use #import <HTCommon/HyperTrack.h> if you are not using frameworks

@implementation AppDelegate

- (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary*)launchOptions {

    [HyperTrack setPublishableAPIKey:@"YOUR_PUBLISHABLE_KEY"];
    [HTTransmitterClient initClient];
    return YES;
}

@end
import HTTransmitter

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    //Initialize SDK
    HyperTrack.setPublishableAPIKey("YOUR_API_KEY")
    HTTransmitterClient.initClient()

    // Override point for customization after application launch.
    return true
}

[warning] Required permissions

To use the SDK, the app needs to define capabilities and permissions (screenshot).

  • Capabilities (Background mode): Enable location updates and background fetch
  • Info (Location permission strings): Add strings for location and motion permissions.
Key: Privacy - Location When In Use Usage Description, Value: App needs location permission to track.

Key: Privacy - Motion Usage Description, Value: App needs motion data to improve location accuracy.

[info] Location permissions

The SDK is compatible with Location - When in use or Location - Always permissions. If your app uses the always permission, there is no need to add when-in-use.

Step 3: Start the Trip

Now that the SDK has been initialised, we can start a Trip. The SDK has methods to start a Trip, and these can be hooked to a view or button in your application where tracking should start.

[info] Server-side integration

A Trip is carried out by a Driver. These entities are created on the server-side, to maintain state such as the list of trips for a driver.

It is also possible to start a Trip from a server-side API, and trigger the SDK to send locations. This will prevent the need for user behavior to start tracking, and can be done from the backend. Read more about iOS trips.

// Configure HTTripParams here
HTTripParams* tripParams = [[HTTripParams alloc] init];

// Start trip by passing trip params
[[HTTransmitterClient sharedClient] startTripWithTripParams:tripParams completion:^(HTResponse <HTTrip *> *response, NSError *error) {

  if (error) {
    // Handle error and try again.
  } else {
    NSLog(@"Response trip : %@", response.result);
    NSLog(@"Offline : %@", @(response.offline));
    // If there is no error, use the trip received in the callback in your app.
  }
}];
// Configure HTTripParams here
let tripParams = HTTripParams()

// Start trip by passing trip params
HTTransmitterClient.sharedClient().startTrip(params: tripParams) { (response, error) in
    if let error = error {
        // Handle startTrip error here
        print("Error while startTrip: \(error)")
        return
    }

    // Handle startTrip success here
}

[info] Simulate locations

If you are using the iOS Simulator to test it out, you can mock the locations by setting Freeway Drive in the Debug > Location menu (screenshot). If you are using a Device, the actual location coordinates will be picked up.

Step 4: View dashboard

Once the Trip has been started, you can view it on the dashboard.

Step 5: End the Trip

To end tracking, use the SDK methods to end trips. Hook these methods to a view or button where you want to end tracking.

// End the current trip
[[HTTransmitterClient sharedClient] endAllTripsWithCompletion:^(NSError * _Nullable error) {
    if (error) {
        // Handle error and try again.
    } else {
        // If there is no error, use the trip received in the callback in your app.
    }
}];
// Start trip by passing trip params
HTTransmitterClient.sharedClient().endAllTrips() { (response, error) in
    if let error = error {
        // Handle startTrip error here
        print("Error while startTrip: \(error)")
        return
    }

    // Handle startTrip success here
}

[success] SDK integrated

We just configured the SDK in your app and started tracking the user on the dashboard. This was achieved with the Trip object. A Trip can have 0 or more Tasks, like a pickup, or an appointment. The next guide covers using Tasks in your workflow.

results matching ""

    No results matching ""