Using Shifts

A Shift represents a period where the current location of the Driver is available for queries. Shifts are typically used to make assignment decisions.

The Android SDK provides the current location of the Driver when a Shift is active. In this guide, we will cover how to start and stop shifts on the SDK. There are two ways to start a Shift: using the REST APIs on the server-side, and using the Android SDK APIs on the client-side.

Server-side

It is possible to start a shift 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 Shift 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 shift APIs

Create a Shift object with the driver id to start. You can refer to the Shift 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 shift 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/shifts/

To stop the service and the collection of location data, just end the Shift. This can be done using the given REST API. The Shift 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/shifts/YOUR_SHIFT_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 Shift must be live.

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 Shifts. Use these methods if your use-case requires location tracking to depend on buttons or other user actions in the app, like a login flow.

Start shift

To start a Shift, we need to create a HTShiftParams object with the following parameters.

Parameters Description
driverID required The id of the driver on the shift

Once you have created the shift params, you'll need to call the startShift method of HTTransmitterService and pass the shift params to it, along with a HTShiftStatusCallback callback handler.

The HTShiftStatusCallback returns a HTShift object inside onSuccess method of callback, if the shift was successfully started. If it fails, it gives an Exception object inside onError method of the callback.

HTShiftParamsBuilder htShiftParamsBuilder = new HTShiftParamsBuilder();
HTShiftParams htShiftParams = htShiftParamsBuilder.setDriverID(driverID)
                        .createHTShiftParams();
HTTransmitterService transmitterService = HTTransmitterService.getInstance(getApplicationContext());
transmitterService.startShift(htShiftParams, new HTShiftStatusCallback() {
  @Override
  public void onError(Exception error) {
    // Handle startShift API error here
  }

  @Override
  public void onSuccess(HTShift shift) {
    // Handle startShift API success to server here
  }

  @Override
  public void onOfflineSuccess() {
    // Shifts are not supported offline currently
    // So, this callback will not be called for Shift APIs
  }
});

End shift

After you've started a shift, you'll need to call endShift of HTTransmitterService to end the current shift.

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

  @Override
  public void onSuccess(HTShift shift) {
    // Handle endShift API success to server here
  }

  @Override
  public void onOfflineSuccess() {
    // Shifts are not supported offline currently
    // So, this callback will not be called for Shift APIs
  }
});

results matching ""

    No results matching ""