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. In case you are using iOS, refer to our open source iOS repository.
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
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
Usage
To use this app
- Clone this repository
# Clone this repository $ git clone https://github.com/hypertrack/hypertrack-live-android.git
- Get your HyperTrack API keys here, and add the publishable key to key.properties file.
HyperTrack.initialize(this.getApplicationContext(), BuildConfig.HYPERTRACK_PK);
- 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.
Date date = new Date();
HyperTrack.getPlaceline(date, new HyperTrackCallback() {
@Override
public void onSuccess(@NonNull SuccessResponse response) {
// Handle getPlaceline success here
if (response != null) {
PlacelineData = (PlacelineData) response.getResponseObject();
}
}
@Override
public void onError(@NonNull ErrorResponse errorResponse) {
// Handle getPlaceline error here
Log.d("Placeline", "onError: " + errorResponse.getErrorMessage());
}
}
);
Get Placeline View in your Android App
Step 1: Setup Activity
- Firstly, add the following xml snippet in your view layout to enable
PlacelineFragment
.
<fragment
android:id="@+id/placeline_fragment"
android:name="com.hypertrack.lib.internal.consumer.view.Placeline.PlacelineFragment"
android:layout_width="match_parent"
android:layout_height="match_parent"
tools:layout="@layout/placeline_fragment" />
- Secondly, instantiate
PlacelineFragment
in the onCreate method of the activity in which placeline fragment has been included.
PlacelineFragment placelineFragment = (PlacelineFragment) getSupportFragmentManager().findFragmentById(R.id.placeline_fragment);
Once all of the above is done, the code snippet would look like as below.
@Override protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
...
// Initialize Placeline Fragment added in Activity Layout
PlacelineFragment placelineFragment = (PlacelineFragment) getSupportFragmentManager().findFragmentById(R.id.placeline_fragment);
...
}
Step 2: Disable ActionBar
In case your AppTheme adds an ActionBar by default, disable the default Action Bar for the activity containing PlacelineFragment by adding the following under your Activity's theme style-tag in styles.xml file. Refer to Android documentation on Setting up the AppBar.
<!-- Change Placeline activity's theme to remove default ActionBar. --> <style name="PlacelineActivityTheme" parent="Theme.AppCompat.Light.NoActionBar">
...
<!-- We will be using the toolbar so no need to show ActionBar -->
<item name="windowActionBar">false</item>
<item name="windowNoTitle">true</item>
<item name="colorAccent">@color/colorAccent</item>
... </style>
Add the android:theme
attribute to the <activity>
tag in AndroidManifest.xml
file.
<!-- Placeline Activity Tag --> <activity android:name=".PlacelineActivity"
android:theme="@style/PlacelineActivityTheme"/>
Step 3: Start Placeline Activity
Placeline Activity can be the Launcher activity
or it can start from some other activity as normal activity.
Launcher Activity
Add the following xml snippet in your AndroidManifest.xml
file to make PlacelineActivity
as a launcher activity.
<activity
android:name=".PlacelineActivity"
android:theme="@style/PlacelineActivityTheme">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter> </activity>
Normal Activity
Add the following snippet in your activity from which you want to start PlacelineActivity
.
public void startPlaceline(View view) {
startActivity(new Intent(this, PlacelineActivity.class));
}
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
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.
- In the first section, we will do a basic setup of Hypertrack SDK.
- In the second section, we will select a destination and start a Live Location trip to that place.
- In the last section, we will get your friend to join the trip started by you.
Let's get started
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.
- Clone this repository
# Clone this repository $ git clone https://github.com/hypertrack/hypertrack-live-android.git
- Get your HyperTrack API keys here, and add the publishable key to key.properties file.
HyperTrack.initialize(this.getApplicationContext(), BuildConfig.HYPERTRACK_PK);
- 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.
-
Refer to the FCM Integration guide.
-
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.
-
Get your Crashlytics key, see the section Add Your API Key from here and you can copy your API Key.
-
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.
expectedPlace
- This is the destination for the visit. You have it after you select the destination.collectionId
- AcollectionId
is an identifier created by you for the Live Location trip. AcollectionId
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()
.setCollectionId(collectionId != null ? collectionId : 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 collectionId
is an identifier which identifies a Live Location trip. When you want to share your trip, your trip's collectionId
needs to be shared.
You can share your collectionId
to the other person in different ways.
- You can use the Android's ShareCard Intent to share it through messaging apps.
- You can use your backend to send the
collectionId
.
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 collectionId
(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.trackActionByCollectionId(collectionId, new HyperTrackCallback() {
@Override
public void onSuccess(@NonNull SuccessResponse response) {
// Handle trackActionByCollectionId API success here
}
@Override
public void onError(@NonNull ErrorResponse errorResponse) {
// Handle trackActionByCollectionId API error here
}
);
For starter project, you have to enter the collectionId
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()
.setCollectionId(collectionId != null ? collectionId : 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 collectionId
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 collectionId needs to be created. This step is similar to Step 6. But this time it is a collectionId 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()
.setCollectionId(collectionId != null ? collectionId : 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
Releasing to PlayStore
To release the app on the Play Store, you will have to change the app's package name.
-
Change the package name in the AndroidManifest.xml file.
-
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.
-
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>
- Add
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].