Using Trips

A Trip represents a journey taken by the Driver. The iOS SDK collects location data when a Trip is active. In this guide, we will cover how to start and stop trips on the SDK.

There are two ways to start a Trip: using the REST APIs on the server-side, and using the iOS SDK APIs on the client-side.

[info] Trips can have Tasks

While on a Trip, a Driver can perform zero or more Tasks. To learn about how to assign and perform Tasks, read the API guide.

Server-side

It is possible to start a trip on the server, and trigger the SDK to send locations. With this implementation, location tracking is independent of the actions on the app, or user behavior. To be able to trigger the SDK, the SDK needs to be online and connected with a driver id.

[warning] Platform restrictions

When using the REST APIs to start the Trip from the server, the iOS SDK responds only if the app is in the foreground.

Connect SDK

Initialise the SDK connection to the server by passing the driver id to the connectDriverWithDriverID method. This should be done in the applicationDidBecomeActive method of your AppDelegate.m.

Once the SDK is connected, the device responds to the server-side APIs.

[info] Driver required

To connect the SDK, a driver id is required. To create a Driver, read about the Driver APIs.

[[HTTransmitterClient sharedClient] connectDriverWithDriverID:@"YOUR_DRIVER_ID" completion:^(NSError * _Nullable error) {
        NSLog(@"Error : %@", error);
    }];
HTTransmitterClient.sharedClient().connect(driverID: "driver_id") { (error) in
    print("did fail to connect \(error)")
}

Start and end trip APIs

Create a Trip object with the driver id to start. You can refer to the Trip model for more options. Remember to use the same driver id you used to connect the SDK.

If the SDK is connected, it will trigger location collection once a trip is created.

curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     -d "{\"driver_id\": \"YOUR_DRIVER_ID\"}" \
     https://app.hypertrack.io/api/v1/trips/

To stop the service and the collection of location data, just end the Trip. This can be done using the given REST API. The Trip entity page covers these server-side APIs in more detail.

curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     https://app.hypertrack.io/api/v1/trips/YOUR_TRIP_ID/end/

[info] Fallback for offline

As this requires the phone to be online, it is recommended to add a fallback to start collecting location data for offline scenarios. The startServiceForDriverID method can be used as shown.

This can be used at a point when you are certain that a Trip must be live. For example, in a food delivery app, it is when you receive details of pending orders.

[[HTTransmitterClient sharedClient] startServiceForDriverID:@"YOUR_DRIVER_ID" completion:^(NSError * _Nullable error) {
    if (error) {
        NSLog(@"Error : %@", error);
    }
}];
HTTransmitterClient.sharedClient().start(driverID: "driver_id") { (error) in
    print("did fail to start \(error)")
}

Client-side

The iOS SDK also provides methods to start and end Trips. Use these methods if your use-case requires location tracking to depend on buttons or other user actions in the app.

[info] Singleton instance

For calling the methods in HTTransmitter library, please use singleton [HTTransmitterClient sharedClient].

Start trip

To start a Trip, we need to create a HTTripParams object. This object does not have any mandatory parameters, but you can specify the following.

Parameters Description
driverID The id of the driver on the trip. If not specified, creates a dummy driver for this trip
vehicleType The vehicle type for the trip, defined by the HTTripVehicleType enum. If not specified, defaults to the vehicle type of the driver

After you create a trip param, you'll need to call the startTripWithTripParams:completion: method of HTTransmitterClient and pass the trip params to it.

The method also needs a HTTripCompletionBlock completion handler. The HTTripCompletionBlock returns a trip, if the trip was successfully started or gives an NSError object otherwise.

[info] Offline trips

It is possible to also start a trip when the device is offline. Read more about offline support.

// Configure HTTripParams here
HTTripParams* tripParams = [[HTTripParams alloc] init];
tripParams.driverID = @"YOUR_DRIVER_ID";
// 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()
tripParams.driverID = "YOUR_DRIVER_ID"
// 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
}

End trip

To end the current trip call endTrip method of HTTransmitterService. The API will end the current trip and stop collecting locations for the Driver.

// End the current trip
[[HTTransmitterClient sharedClient] endTripWithTripID:@"YOUR_TRIP_ID" completion:^(HTResponse <HTTrip *> * _Nullable response, 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.
  }
}];
HTTransmitterClient.sharedClient().endTrip(tripID: "YOUR_TRIP_ID") { response, error in
    if let error = error {
        // Handle endTrip error here
        print("Error while endTrip: \(error)")
        return
    }

    // Handle endTrip success here
}

results matching ""

    No results matching ""