Using Trips

A Trip represents a journey taken by the Driver. The Android 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 Android 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 SDK responds only if the app is in the memory of the device and the device is online. This means,

  • The app must be opened around the time the trip should start, for the connection to be established.
  • Force killing the app will break the connection.

Connect SDK

Initialise the SDK connection to the server by passing the driver id to the connectDriver method. This should be done in the onResume method of your app's Launcher or Main activities.

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.

@Override
protected void onResume() {
  super.onResume();
  // Initiate DriverSDK connection
  HTTransmitterService.connectDriver(getApplicationContext(), driverID,
    new TransmitterErrorCallback() {
      @Override
      public void onError(final int errorCode, final String errorMessage) {
        // Handle connectDriver Error here
        // Refer to TransmitterError.java file for Error codes & messages
        // Note: This callback might be called on a worker thread, so handle
        // the errors accordingly. To run commands on MainThread refer to
        // runOnUiThread API in Android documentation
      }
  });
}

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. To verify, check that the service notification is visible on the lock screen.

Service notification

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 startLocationService 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.

transmitterService =  HTTransmitterService.getInstance(this);
transmitterService.startLocationService(driverID, new HTStartDriverStatusCallback() {
  @Override
  public void onError(Exception error) {
    // Log error.getMessage() here or do something
  }

  @Override
  public void onSuccess() {
    // Add code for successful startLocationService here
  }
});

Client-side

The Android 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.

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

Once you have created the trip params, you'll need to call the startTrip method of HTTransmitterService and pass the trip params to it, along with a HTTripStatusCallback callback handler. This API will create and start a Trip for you in a single call.

The HTTripStatusCallback returns a HTTrip object inside onSuccess method of callback, if the trip was successfully started. If it fails, it gives an Exception object inside onError method of the callback.

[info] Offline trips

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

HTTripParamsBuilder htTripParamsBuilder = new HTTripParamsBuilder();
HTTripParams htTripParams = htTripParamsBuilder.setDriverID(driverID)
    .setTaskIDs(taskIDs)
    .setOrderedTasks(false)
    .setIsAutoEnded(false)
    .createHTTripParams();

HTTransmitterService transmitterService = HTTransmitterService.getInstance(getApplicationContext());
transmitterService.startTrip(htTripParams, new HTTripStatusCallback() {
  @Override
  public void onError(Exception error) {
    // Handle startTrip API error here
  }

  @Override
  public void onSuccess(HTTrip trip) {
    // Handle startTrip API success to server here
  }

  @Override
  public void onOfflineSuccess() {
    // Handle offline startTrip API success here (startTrip request has been
    // cached, starting the DriverSDK and it will be synced with server once
    // the device comes online)
  }
});

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.

HTTransmitterService transmitterService = HTTransmitterService.getInstance(getApplicationContext());
transmitterService.endTrip(new HTTripStatusCallback() {
  @Override
  public void onError(Exception error) {
    // Handle endTrip API error here
  }

  @Override
  public void onSuccess(HTTrip trip) {
    // Handle endTrip API success to server here
  }

  @Override
  public void onOfflineSuccess() {
    // Handle offline endTrip API success here (endTrip request has been
    // cached and it will be synced with server once the device comes online)
  }
});

Was this helpful? Yes, thanks! Not really

results matching ""

    No results matching ""