Bringg

Bringg SDK for Android

The Bringg (SDK) for Android enables you to quickly and easily embed Bringg tracking screen into your own Android native app.

Please refer to our terms of service before downloading Bringg SDK: http://bringg.com/sdk-terms-of-service/

Installation

Android Studio

add the following lines to your build.gradle file:

repositories {
    mavenCentral()
    maven { url 'https://oss.sonatype.org/content/groups/public' }
}

dependencies {
    compile 'com.bringg:ordertrack:1.+'
}

Latest Version is 1.1.11

to specifically use this version you can use compile 'com.bringg:ordertrack:1.1.11' instead

Migration from 1.1.4 to 1.1.11

  • order callbacks now pass order object instead of driver object. you can obtain the driver by using order.getDriver()
  • watchOrder no longer needs to be called from a background thread.
  • rate method no longer needs to be called from a background thread; instead of returning a json with the success/failure result directly it does so via a callback.

Usage

Step 1

implement the RealTimeConnectionCallback interface.

RealTimeConnectionCallback is an interface with the following 4 methods:

public void onConnect();
public void onDisconnect();
public void onError(String message);
public void onAck(String event, boolean success, String error);

each of the above methods will be called on the associated occasion.
it is not mandatory to implement all of the above yet it is highly recommended to at least handle the onConnect() callback (see our example code).

Step 2

create an instance of the BringgClient class.

the class has a single constructor, which receive a callback for handling connection events.
pass along a reference to the interface you implemented in step 1.

public BringgClient(Context context, RealTimeConnectionCallback connectionCallback, String devAccessToken)

Step 3

call the connect() method of the BringgClient instance.

Step 4

call the watchOrder and/or watchDriver and/or rate methods of the BringgClient instance.

Notes

make sure that it is connected, i.e that the onConnected callback was called; otherwise nothing will happen.
you need to obtain the relevant ids to pass to these methods. i.e order_uuid, driver_uuid and shrared_location_uuid (if not signed in).
you need to implement the callbacks for the handling the events you subscribe to.

Step 5

once you finished listening to the events, call the disconnect method.

Bringg Client

Bringg client has the following methods :

2 methods to manage the realtime connection:

/**
* connects the client to bringg real time servers.
* if in the middle of establishing a connection or is already connected - this does nothing.
*/
public void connect()
  
/**
* connects the client to bringg real time servers.
* if in the middle of establishing a connection or is already connected - this does nothing.
* used for signed-in customer usage.
*/
public void connect(String customer_access_token)

/**
* disconnects the client from real-time servers.
*/
public void disconnect()

2 methods for subscribing to events:

/**
* subscribe to events on the order with the provided id.
* @param uuid - the uuid of the order we want to watch.
* @param orderStatusListener - the event handler for order update events.
* @throws RuntimeException if either the uuid is null.
*/
public void watchOrder(String uuid, OrderStatusListener orderStatusListener)

/**
* subscribe to events on the driver with the provided uuid.
* this method is for anonymous usage.
* @param driver_uuid the uuid of the driver we want to watch.
* @param shared_uuid the uuid of the shared location object associated with the order.
* @param driverLocationListener the event handler for driver update events.
*/
public void watchDriver(String driver_uuid, String shared_uuid, DriverLocationListener driverLocationListener)
  
/**
* subscribe to events on the driver with the provided uuid.
* this method is for signed in usage.
* @param driver_uuid the uuid of the driver we want to watch.
* @param driverLocationListener the event handler for driver update events.
*/
public void watchDriver(String driver_uuid, DriverLocationListener driverLocationListener)

/**
* subscribe to events on waypoint, mainly eta changes. 
*/
public void watchWayPoint(String order_uuid, long wayPointId, WayPointStatusListener wayPointStatusListener)   

shared_uuid

shared_uuid can be obtain via multiple ways
1) requesting it via the create order api from your server and passing it to our client.
see http://developers.bringg.com/reference#create_task. 'share_location' param
2) application callback:
see http://developers.bringg.com/v1.0/docs/shared-location-override-application.

if signing in, this parameter will be no longer needed.

2 methods for determining the state of current subscriptions:

/**
* return true if in the current connection instance the client has asked to watch a driver.
*/
public boolean isWatchingDrivers()

/**
* return true if in the current connection instance the client has asked to watch an order.
*/
public boolean isWatchingOrders()

/**
* return true if client has been asked to watch waypoint
*/
public boolean isWatchingWayPoint()  

Rating

Enables you to add a rate to an order.

Method for rating an order:

/**
* @param rating (1-5)
* @param callback will be called on rating succes or failure.
*/
public void rate(int rating, OrderRateListener callback) throws IOException

Callbacks

RealTimeConnectionCallback - a callback for handling connection status updates.
has the following methods:

public void onConnect();
public void onDisconnect();
public void onError(String message);
public void onAck(String event, boolean success, String error);

OrderStatusListener - a callback for handling order status change events.
has the following methods:

public void onOrderAssigned(Order order);
public void onOrderAccepted(Order order);
public void onOrderStarted(Order order);
public void onOrderArrived(Order order);
public void onOrderDone();
public void onOrderCanceled();

DriverLocationListener - a callback for handling driver location updates.
has the following method:

public void onLocationChanged(double lat, double lng);

Notes

you can use the onOrderAssigned(driver) callback to get the assigned driver_uuid and pass it to the watchDriver() call.
location updates will start arriving only after driver starts the order. you will get notified that it happened by the onOrderStarted() callback.

Sign-in vs. Anonymous usage

signing-in is an optional (yet recommended) action that will let us authenticate the user.

the sdk provides a simple way to use the utility class BringgCustomerManager that includes all the necessary logic to handle the signing-in process for you. all you have to do is provide the required parameters.

Sign-in will work only for registered customers.

Creating a customer

A customer can only be created from your server, using the api call found on the following link
http://developer-api.bringg.com/partner_api/customers

an example of how to use BringgCustomerManager is provided in the example code provided below.

Example

the following is an example of how to use the BringgClient class within an activity.

make sure you add your real parameter values instead of those in the example.

The following example is updated to version 1.1.1

import android.app.Activity;
import android.os.AsyncTask;
import android.os.Bundle;
import android.util.Log;

import com.bringg.ordertrack.callbacks.RealTimeConnectionCallback;
import com.bringg.ordertrack.event_listeners.DriverLocationListener;
import com.bringg.ordertrack.event_listeners.OrderStatusListener;
import com.bringg.ordertrack.http.BringgCustomerManager;

import org.json.JSONObject;

import java.io.IOException;

/**
 * this class shows a basic example of how to use the RealTimeClient class.
 * it implements the RealTimeConnectionCallback interface so we can respond to connection events.
 * it uses two example listeners that log the related events.
 */
public class ExampleBogusActivity extends Activity implements RealTimeConnectionCallback{

    private static final String TAG = "ClientExample";

    private static final String EXAMPLE_DEV_ACCESS_TOKEN = "aaaaa";
    private static final String EXAMPLE_UUID = "asdfg";
    private static final String EXAMPLE_SHARED_UUID = "asdfg";
    private static final String EXAMPLE_MERCHANT_ID = "-1100";


    private BringgClient bringgClient;
    private BringgCustomerManager customerManager;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        // ... the usual ui stuff enters here

        // create an instance of the realTimeClient with our event handlers.
        bringgClient = new BringgClient(this, this, EXAMPLE_DEV_ACCESS_TOKEN);

        // create an instance of the bringg customer manager and provide it with your dev key.
        customerManager = BringgCustomerManager.getInstance(this);
        customerManager.setCredentials(EXAMPLE_DEV_ACCESS_TOKEN, EXAMPLE_MERCHANT_ID);

        // sign in the customer to bringg if not signed in already
        signCustomerToBringgOnce();

        // connect with credentials
        if (customerManager.isSignedIn()) {
            // connect the client to the real time endpoint.
            // this call is asynchronous so we use the onConnect callback which this class implements
            // to act after connection is established.
            bringgClient.connect(customerManager.getCredentials());
        }

        // note that if we did not sing in the customer we use the connect() method again after
        // successful sign in. see the signCustomerToBringgOnce() method.
    }

    @Override
    protected void onDestroy() {
        // it is very important to disconnect the client when we are done with it
        // so it will stop using battery and network.
        bringgClient.disconnect();

        super.onDestroy();
    }

    // =============================================
    // =============================================

    private static final String EXAMPLE_CONFIRMATION_CODE = "aaa";
    private static final String EXAMPLE_CUSTOMER_PHONE = "111";

    /**
     * sign in the customer to bringg and retrieve his access token to be used later.
     */
    private void signCustomerToBringgOnce(){
        if (!customerManager.isSignedIn())
            new AsyncTask<Void, Void, JSONObject>() {
                @Override
                protected JSONObject doInBackground(Void... voids) {
                    try {
                        // sign in using the customer's phone.
                        // we could use the customer's name instead or both.
                        return customerManager.signIn(
                                EXAMPLE_CUSTOMER_PHONE, null, EXAMPLE_CONFIRMATION_CODE, String.valueOf(EXAMPLE_MERCHANT_ID));
                    } catch (IOException e){
                        e.printStackTrace();
                        // do something with exception here
                        return null;
                    }
                }

                @Override
                protected void onPostExecute(JSONObject result) {
                    if (result != null){
                        if (result.has("error")) {
                            Log.e(TAG, result.optString("error"));
                        } else if (result.has("access_token")){
                            Log.i(TAG, "sign in succeeded");
                            // connect with the access token if not already connected
                            if (!bringgClient.isConnected())
                                bringgClient.connect(result.optString("access_token"));
                        }
                    }
                }
            }.execute();
    }

    // ============================================================================
    // ============= optional callbacks for handling connection events ============


    @Override
    public void onConnect() {
        Log.i(TAG, "connected");

        // tell the client to start listening for events related to the order with the given uuid.
        // any event will be handled by the orderStatusChangedListener.
        bringgClient.watchOrder(EXAMPLE_UUID, orderListener);
    }

    @Override
    public void onDisconnect() {
        Log.i(TAG, "disconnected");
    }

    @Override
    public void onError(String message) {
        Log.e(TAG, message);
    }

    @Override
    public void onAck(String event, boolean success, String error) {
        // can check here if broadcast for the event succeeded if we received an ack.
    }


    // ==========================================================================
    // ========================== event listeners ===============================

    private DriverLocationListener driverListener = new DriverLocationListener() {
        @Override
        public void onLocationChanged(double lat, double lng) {
            Log.i(TAG, "driver location: " + lat + ", " + lng);
        }
    };

    private OrderStatusListener orderListener = new OrderStatusListener() {
        @Override
        public void onOrderAssigned(Driver driver) {
            Log.i(TAG, "order assigned");
        }

        @Override
        public void onOrderAccepted(Driver driver) {
            Log.i(TAG, "order accepted");
        }

        @Override
        public void onOrderStarted(Driver driver) {
            Log.i(TAG, "order started");

            if (driver.uuid != null){
                // tell the client to start listening for events on the driver with the given id.
                // any event will be handled by the driverLocationListener.
                bringgClient.watchDriver(driver.uuid, EXAMPLE_SHARED_UUID, driverListener);
            }
        }

        @Override
        public void onOrderArrived() {
            Log.i(TAG, "order arrived");
        }

        @Override
        public void onOrderDone() {
            Log.i(TAG, "order done");
        }

        @Override
        public void onOrderCanceled() {
            Log.i(TAG, "order canceled");
        }
    };
}

Bringg SDK for Android