Activity Tracking and Live Location Sharing

This open source repo uses HyperTrack for Live Location Sharing and Activity Tracking. Hypertrack Live helps you share your Live Location with friends through your favorite messaging app when on the way to meet up. You can also see your activities organized as chronological cards so that tapping on each card gives you the locations of the activity.

Usecase	Description	Tutorial
Activity Tracking	Track your activities chronologicaly through the day. Description	Build yourself 👩‍💻
Live Location Sharing	Share your Live Location with friends and see theirs. Description	Build yourself 👩‍💻

• Activity Tracking
• Live Location Sharing
• Usage
• Build Activity Tracking in your app
• Build Live Location Sharing in your app
• Documentation
• Contribute
• Support

Activity Tracking

One of the two core features of Hypertrack Live is Placeline. Placeline is useful in tracking your daily activity with near-zero battery impact. We automagically use the combination of device sensors - GPS, WiFi, network, accelerometer, pedometer, gyroscope, compass - to deliver accuracy. Placeline is powered by the HyperTrack SDK which collects location and activity data for your users. It includes segments like stop 🛑, walk 🚶‍♀️,run 🏃‍♀️,drive 🏎️ and cycling 🚴.

Live Location Sharing

The other core feature of Hypertrack Live is Live Location Sharing. Live Location Sharing is useful for consumer apps like messengers and social apps where two or more people want to share their Live Location with each other when on the way to meet up. It is also useful for marketplace aggregators where the transaction starts online 💻📱 but requires people to meet offline for fulfillment. It helps you solve the consumer's anxiety of “where are you⁉️”.

Usage

To use this app

1. Clone this repository

# Clone this repository
$ git clone https://github.com/hypertrack/hypertrack-live-android.git

2. Get your HyperTrack API keys here, and add the publishable key to key.properties file.

HyperTrack.initialize(this.getApplicationContext(), BuildConfig.HYPERTRACK_PK);

3. Get the Google Maps API key and add it to api-keys.xml.

To build Placeline in your app, follow this tutorial.

To build Live Location Sharing in your app, follow this tutorial.

Build Activity Tracking in your app

• Placeline format
• Setup HyperTrack SDK
• Create Hypertrack user
• Start tracking
• Get Placeline in your app

Placeline format

Placeline object contains detailed information about the activity like the start time, end time, location, steps and more. An example JSON representation is given here.

Setup HyperTrack SDK

Set up the HyperTrack SDK by following these instructions.

Create HyperTrack user

The next thing that you need to do is create a HyperTrack User. This would tag the location/activity data to the user and help you get useful filtered data in the form of Placeline. More details about the function here.

UserParams userParams = new UserParams()
                .setName(name)
                .setPhone(phoneNumber)
                .setPhoto(encodedImage)
                .setLookupId(phoneNumber);
                
HyperTrack.getOrCreateUser(userParams, new HyperTrackCallback() {
                @Override
                public void onSuccess(@NonNull SuccessResponse successResponse) {
                    // Handle success on getOrCreate user
                    HyperTrack.startTracking();
                }

                @Override
                public void onError(@NonNull ErrorResponse errorResponse) {
                    // Handle error on getOrCreate user
                    Toast.makeText(this, errorResponse.getErrorMessage(), Toast.LENGTH_SHORT).show();
                }
            });

Start tracking

Start tracking for the created user by calling the following method

HyperTrack.startTracking();

Get Placeline Data in your app

Once tracking has started, implement the following function placelineManager.getPlacelineData() and get PlacelineData. You are all set to use the rich activity data in your app.

PlacelineManager placelineManager = PlacelineManager.getPlacelineManager(this);
placelineManager.getPlacelineData(userID, date, new HyperTrackCallback() {
        @Override
        public void onSuccess(@NonNull SuccessResponse response) {
            if (response != null) {
                    PlacelineData = (PlacelineData) response.getResponseObject();
            }
        }
        @Override
        public void onError(@NonNull ErrorResponse errorResponse) {
            Log.d("Placeline", "onError: " + errorResponse.getErrorMessage());
        }
}

We hope that you got a good taste of Placeline. If you have any problems or suggestions for the tutorial, do not hesitate to buzz 🐝 us here.

Build Live Location Sharing in your app

Use the following tutorial to build Live Location Sharing in your app. This is divided into three section.

1. In the first section, we will do a basic setup of Hypertrack SDK.
2. In the second section, we will select a destination and start a Live Location trip to that place.
3. In the last section, we will get your friend to join the trip started by you.

Let's get started 😊 . Strap yourself in and get ready for an exciting ride 🚀 .

• Basic setup
  • Get API keys
  • Use this project
  • Setup HyperTrack SDK
  • Create HyperTrack user
  • FCM Integration
  • Crashlytics Setup (optional)
• Start a Live Location trip
  • Show Live Location view
  • Create and track action
  • Share your trip
• Track or join an ongoing trip
  • Track ongoing trip
  • Join ongoing trip

Basic Setup

Step 1. Get API keys

Get your HyperTrack API keys here.

Step 2. Use this project

We have created this project so that building Live Location Sharing becomes very easy and quick. It will prevent you from the hassle of creating a new project and the workflow to enable Live Location Sharing. If you want to directly build the flow in your own app or wanted to create a new project, you can ignore this step.

1. Clone this repository

# Clone this repository
$ git clone https://github.com/hypertrack/hypertrack-live-android.git

2. Get your HyperTrack API keys here, and add the publishable key to key.properties file.

HyperTrack.initialize(this.getApplicationContext(), BuildConfig.HYPERTRACK_PK);

3. Get the Google Maps API key and add it to api-keys.xml.

Step 3. Setup HyperTrack SDK

If you are NOT using the starter project, set up the HyperTrack SDK by following these instructions. Else, initialize the SDK by putting the following code in MyApplication.java file.

public class MyApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        
        ...
        
        // Initialize HyperTrack SDK
        HyperTrack.initialize(this.getApplicationContext(), BuildConfig.HYPERTRACK_PK);
    }

Step 4. Create HyperTrack user

The next thing that you need to do is to create a HyperTrack user. It helps us tag the location/activity data with the user and share their Live Location status with friends. More details about the function here.

When the user is created, we need to start tracking his location and activity. Call the following method to do so HyperTrack.startTracking()

For starter project, go to ProfilePresenter.java. When the user taps login, get the name of the user and use the following function to create a user.

UserParams userParams = new UserParams()
                .setName(name)
                .setPhone(phoneNumber)
                .setPhoto(encodedImage)
                .setLookupId(phoneNumber);
                
HyperTrack.getOrCreateUser(userParams, new HyperTrackCallback() {
                @Override
                public void onSuccess(@NonNull SuccessResponse successResponse) {
                    // Handle success on getOrCreate user
                    HyperTrack.startTracking();
                    Toast.makeText(this, "Yay Hypertrack User is created successfully.", Toast.LENGTH_SHORT).show();
                }

                @Override
                public void onError(@NonNull ErrorResponse errorResponse) {
                    // Handle error on getOrCreate user
                    Toast.makeText(this, errorResponse.getErrorMessage(), Toast.LENGTH_SHORT).show();
                }
            });

Step 5. FCM Integration

The HyperTrack SDK requires FCM for a battery efficient real-time tracking experience.

1. Refer to the FCM Integration guide.

2. After setting up your account on the Firebase console, you will need to add the google-services.json file to your app folder.

Step 6. Crashlytics Setup (Optional)

You can also enable the crashlytics crash reporting tool. This is optional and if you choose to skip this won't affect your integration.

1. Get your Crashlytics key, see the section Add Your API Key from here and you can copy your API Key.

2. Paste the key to fabric.properties. Create a new fabric.properties file, if it doesn't exist already.

Start a Live Location trip

Are you ready to rock and roll?

Step 1. Show Live Location view

Now to start a Live Location trip, the first thing that you need to do is to add a destination. For this, we will need a location picker. The good news is that HyperTrack Location View has a location picker within it. Once the user selects a location with the help of our inbuilt location picker, than the sdk gives a callback to the app with the selected location so that the app can start a trip.

For starter project, Check Home.java embedding the HyperTrackMapFragment view in content_home.xml view. Initialize the HyperTrackMapFragment inside oncreate method of Home activity and set your implementation of HyperTrackMapAdapter, MapFragmentCallback for HyperTrackMapFragment.

MapFragmentCallback callback = new MapFragmentCallback(){
    @Override
    public void onMapReadyCallback(HyperTrackMapFragment hyperTrackMapFragment, GoogleMap map) {
        // Handle onMapReadyCallback API here
    }

    @Override
    public void onExpectedPlaceSelected(Place expectedPlace) {
        // Check if expected place was selected
        if (expectedPlace != null) {
            // Handle selected expectedPlace here
        }
    }
    ...
};

htMapFragment = (HyperTrackMapFragment) getSupportFragmentManager()
        .findFragmentById(R.id.htMapfragment);
HomeMapAdapter adapter = new HomeMapAdapter(this);
htMapFragment.setHTMapAdapter(adapter);
htMapFragment.setMapFragmentCallback(callback);

Implement this method in the MapFragmentCallback as specified above. You will get a callback when a user selects an expected place using SDK's Place Selector View.

@Override
public void onExpectedPlaceSelected(Place expectedPlace) {
    // Check if expected place was selected
    if (expectedPlace != null) {
        // Handle selected expectedPlace here
    }
}

Step 2. Create and track action

When the user selects a location, you will get a callback in the onExpectedPlaceSelected function of your MapFragmentCallback instance. This is the right time to start a trip. For starting a trip, you need to create a session. This can be achieved by creating a 'visit' action.
You will need two things to create an action.

1. expectedPlace - This is the destination for the visit. You have it after you select the destination.
2. lookupId - A lookpupId is an identifier created by you for the Live Location trip. A lookupId is what needs to be shared with the friend, so they can join your trip and share their location. We chose it to be the UUID. You can use your own internal identifiers.

For starter project, go to Home.java and add the following code when you get a callback of place selection onExpectedPlaceSelected.

ActionParams actionParams = new ActionParamsBuilder()
                .setLookupId(lookupID != null ? lookupID : UUID.randomUUID().toString())
                .setType(Action.ACTION_TYPE_VISIT)
                .setExpectedPlace(expectedPlace)
                .build();

// Call assignAction to start the tracking action
HyperTrack.createAndAssignAction(actionParams, new HyperTrackCallback() {
    @Override
    public void onSuccess(@NonNull SuccessResponse response) {
        if (response.getResponseObject() != null) {
            Action action = (Action) response.getResponseObject();
            
            // Handle createAndAssign Action API success here
            Toast.makeText(this, "Live Location successful shared back", Toast.LENGTH_SHORT).show();
        }
    }

    @Override
    public void onError(@NonNull ErrorResponse errorResponse) {
        // Handle createAndAssign Action API error here
        Toast.makeText(this, "Live Location successful shared back", Toast.LENGTH_SHORT).show();
    }
});

Also, allow user to stop sharing his location by handling stopSharing method in HomePresenter.java file so the action gets completed when the user taps stop sharing.

HyperTrack.completeAction(actionID);

Step 3. Share your trip

As described earlier, a lookpupId is an identifier which identifies a Live Location trip. When you want to share your trip, your trip's lookupId needs to be shared.

You can share your lookupId to the other person in different ways.

1. You can use the Android's ShareCard Intent to share it through messaging apps.
2. You can use your backend to send the lookupId.

For starter project, let us keep it simple and use Android's ShareCard to do the job for us.

Intent sharingIntent = new Intent(android.content.Intent.ACTION_SEND);
sharingIntent.setType("text/plain");
sharingIntent.putExtra(android.content.Intent.EXTRA_TEXT, shareMessage);
startActivityForResult(Intent.createChooser(sharingIntent, "Share via"),
        Constants.SHARE_REQUEST_CODE);

Track or join an ongoing trip

If you have completed the steps in above section, you have a user who has started a Live Location session. Once their friend receives a lookupId (either through your own backend or through a messaging app), she can use it to track the user and optionally join the trip if you add a few lines of code as described in the following steps.

Step 1. Track ongoing trip

To track the user, use the following function. Although the tracking has started in the SDK, visualizing it requires you to embed HyperTrack's map fragment in your activity containing hypertrack map view.

HyperTrack.trackActionByLookupId(lookupId, new HyperTrackCallback() {
    @Override
    public void onSuccess(@NonNull SuccessResponse response) {
        // Handle trackActionByLookupId API success here
    }
 
    @Override
    public void onError(@NonNull ErrorResponse errorResponse) {
        // Handle trackActionByLookupId API error here
    });

For starter project, you have to enter the lookupId in the text field that you have received from the user who has started the session. Add the following code in the click of track button onTrackSharedLinkButtonClick().

ActionParams actionParams = new ActionParamsBuilder()
                .setLookupId(lookupID != null ? lookupID : UUID.randomUUID().toString())
                .setType(Action.ACTION_TYPE_VISIT)
                .setExpectedPlace(expectedPlace)
                .build();

// Call assignAction to start the tracking action
HyperTrack.createAndAssignAction(actionParams, new HyperTrackCallback() {
    @Override
    public void onSuccess(@NonNull SuccessResponse response) {
        if (response.getResponseObject() != null) {
            Action action = (Action) response.getResponseObject();
            
            // Handle createAndAssign Action API success here
            Toast.makeText(this, "Live Location successful shared back", Toast.LENGTH_SHORT).show();
        }
    }

    @Override
    public void onError(@NonNull ErrorResponse errorResponse) {
        // Handle createAndAssign Action API error here
        Toast.makeText(this, "Live Location successful shared back", Toast.LENGTH_SHORT).show();
    }
});

Now to see the result, go to the other device and set up the user. After that click on 'Track a Live Location trip' and paste/enter the lookupId which you received from the user.

Step 2. Join ongoing trip

In this step, we will see how the friend can share her Live Location and join the trip. To join the trip, an action with the same lookupId needs to be created. This step is similar to Step 6. But this time it is a lookupId of an existing trip and NOT a new one in Step 6.

For starter project, add this code to onShareLiveLocationBack() when the user taps the 'Share Live Location' button. It creates and assign action for your friends Live Location session.

ActionParams actionParams = new ActionParamsBuilder()
                .setLookupId(lookupID != null ? lookupID : UUID.randomUUID().toString())
                .setType(Action.ACTION_TYPE_VISIT)
                .setExpectedPlace(expectedPlace)
                .build();

// Call assignAction to start the tracking action
HyperTrack.createAndAssignAction(actionParams, new HyperTrackCallback() {
    @Override
    public void onSuccess(@NonNull SuccessResponse response) {
        if (response.getResponseObject() != null) {
            Action action = (Action) response.getResponseObject();
            
            // Handle createandAssign Action API success here
            Toast.makeText(this, "Live Location successful shared back", Toast.LENGTH_SHORT).show();
        }
    }

    @Override
    public void onError(@NonNull ErrorResponse errorResponse) {
        // Handle createandAssign Action API error here
        Toast.makeText(this, "Live Location successful shared back", Toast.LENGTH_SHORT).show();
    }
});

We hope you’ve enjoyed yourself on your epic quest to build a Live Location feature. If you have any problems or suggestions for the tutorial, please do not hestitate to buzz 🐝 us here.

Releasing to PlayStore

To release the app on the Play Store, you will have to change the app's package name.

1. Change the package name in the AndroidManifest.xml file.

2. Refactor the name of your package with right click → Refactor → Rename in the tree view, then Android Studio will display a window, select "Rename package" option.

3. Change the application id in the build.gradle file. Once done, clean and rebuild the project.

   • Add release key store file in app level folder.
   • Create a keystore.properties file in root or project level folder with key-values pair.

       storeFile=<File path of keystore file>
       storePassword=<Key Store Password>
       keyAlias=<Key Alias>
       keyPassword=<Key Password>

Usage

To build live location sharing within your own app

Follow this step-by-step tutorial that will walk you through how you can embed this code in your app.

Documentation

For detailed documentation of the APIs, customizations and what all you can build using HyperTrack, please visit the official docs.

Contribute

Feel free to clone, use, and contribute back via pull requests. We'd love to see your pull requests - send them in! Please use the issues tracker to raise bug reports and feature requests.

We are excited to see what live location feature you build in your app using this project. Do ping us at [email protected] once you build one, and we would love to feature your app on our blog!

Support

Join our Slack community for instant responses, or interact with our growing community. You can also email us at [email protected].

Dependencies

• Google v7 appcompat library
• Google Design Support Library
• Google libphonenumber library
• Square Retrofit
• Square Picasso
• tajchert WaitingDots
• Compact Calendar View
• Android Ripple Background
• Scrolling Image View
• RecylcerView Snap
• Leak Canary
• Branch
• Crashlytics