This section describes the steps to be followed to integrate FirstHive Analytics SDK in your Android application.
Prerequisite
A ‘site ID’ need to be created for your APP in your FirstHive account to map the tracking to your account. Contact your FirstHive rep for the Site ID if not already provided.
Including the Library
Add this to your app module build.gradle file
implementation 'org.matomo.sdk:tracker:4.0.2' implementation 'com.jakewharton.timber:timber:4.7.1' implementation 'com.jakewharton:butterknife:8.8.1' |
Client Configuration
You can also manage the Tracker. To ensure that the metrics are not over-counted, it is highly recommended that the tracker is created and managed in the Application class (i.e. not created twice). The Tracker itself is thread-safe and can be shared throughout your application. It’s not recommended to create multiple Tracker instances for the same target.
Initialize your Tracker either by extending our MatomoApplication class or storing an instance yourself. Get the <Site Id> by login to your FirstHive account and replace <siteid> with your site id integer value.
import org.matomo.sdk.TrackerBuilder; import org.matomo.sdk.extra.DimensionQueue; import org.matomo.sdk.extra.DownloadTracker; import org.matomo.sdk.extra.MatomoApplication; import org.matomo.sdk.extra.TrackHelper; public class YourApplication extends Application { private Tracker tracker; public synchronized Tracker getTracker() { if (tracker == null) tracker = TrackerBuilder.createDefault("https://www.firsthive.com/engage/piwik/piwik.php", <siteid>); return tracker; } } |
————————-OR———————————-
public class DemoApp extends MatomoApplication { private DimensionQueue mDimensionQueue; @Override public TrackerBuilder onCreateTrackerConfig() { return TrackerBuilder.createDefault("https://www.firsthive.com/engage/piwik/piwik.php", <siteid>); } @Override public void onCreate() { super.onCreate(); StrictMode.setVmPolicy(new StrictMode.VmPolicy.Builder() .detectAll() .penaltyLog() .build()); onInitTracker(); } Don't forget to add application name to your AndroidManifest.xml file. <application android:name=".YourApplication"> <!-- activities go here --> </application> |
Using FirstHive App Tracking:
The recommended way to use the library is by using the TrackHelper class. It has methods for all common actions which can be chained in a way that facilities the correct order and use.
Just by using auto-completion on TrackHelper.
// Get the `Tracker` you want to use Tracker tracker = ((MatomoApplication) getApplication()).getTracker(); |
Track screen views
@OnClick(R.id.trackMainScreenViewButton) void onTrackMainScreenClicked(View view) { TrackHelper.track().screen("/").title("Main Screen").with(getTracker()); } |
Track events
To collect data about user’s interaction with interactive components of your app, like button presses .
Refer the miscellaneous section to understand the event Anatomy and list of standard events that you can in corporate
| TrackHelper.track().event(“category”,”Event action”).name(“Event Name”).value(1000f).with(getTracker()); |
Sample implementation:
Example for CategoryViewed event:
TrackHelper.track().event("Viewed","CategoryViewed").name("HighValue_tag").value(0000f).with(getTracker()); mDimensionQueue = new DimensionQueue(getTracker()); mDimensionQueue.add(6, "sku10367"); mDimensionQueue.add(7, "Iphone10"); mDimensionQueue.add(8, "Electronics"); mDimensionQueue.add(9, "75000"); |
|
NOTEReserved Dimension:
mDimensionQueue.add(1, "Email"); mDimensionQueue.add(2, "Mobile No"); mDimensionQueue.add(3, "User Name"); mDimensionQueue.add(4, "PAN"); mDimensionQueue.add(5, "ARN"); |
Track Goal
To track the goal/revenues
@OnClick(R.id.trackGoalButton) void onTrackGoalClicked(View view) { float revenue; try { revenue = Integer.valueOf( ((EditText) findViewById(R.id.goalTextEditView)).getText().toString()); } catch (Exception e) { TrackHelper.track().exception(e).description("wrong revenue").with(getTracker()); revenue = 0; } TrackHelper.track().goal(1).revenue(revenue).with(getTracker()); } |
Track Exceptions
You can also track exceptions using below sample example.
@OnClick(R.id.raiseExceptionButton) void onRaiseExceptionClicked(View view) { TrackHelper.track().exception(new Exception("OnPurposeException")).description("Crash button").fatal(false).with(getTracker()); } |
E-commerce
FirstHive provides e-commerce analytics that let you measure items added to carts, and learn detailed metrics about abandoned carts and purchased orders. You can also track your goal by using below examples.
//Capture Ecommerce items in cart @OnClick(R.id.addEcommerceItemButton) void onAddEcommerceItemClicked(View view) { List<String> skus = Arrays.asList("00001", "00002", "00003", "00004"); List<String> names = Arrays.asList("Silly Putty", "Fishing Rod", "Rubber Boots", "Cool Ranch Doritos"); List<String> categories = Arrays.asList("Toys & Games", "Hunting & Fishing", "Footwear", "Grocery"); List<Integer> prices = Arrays.asList(449, 3495, 2450, 250); int index = cartItems % 4; int quantity = (cartItems / 4) + 1; items.addItem(new EcommerceItems.Item(skus.get(index)) .name(names.get(index)) .category(categories.get(index)) .price(prices.get(index)) .quantity(quantity)); cartItems++; } //Capture Cart update event @OnClick(R.id.trackEcommerceCartUpdateButton) void onTrackEcommerceCartUpdateClicked(View view) { TrackHelper.track().cartUpdate(8600).items(items).with(getTracker()); } //Capture order placed events @OnClick(R.id.completeEcommerceOrderButton) void onCompleteEcommerceOrderClicked(View view) { TrackHelper.track() .order(String.valueOf(10000 * Math.random()), 10000) .subTotal(1000) .tax(2000) .shipping(3000) .discount(500) .items(items) .with(getTracker()); } |
Activate Mobile Push/Notification
Prerequisite: Set up a Firebase Cloud Messaging client app in your Android APP
https://firebase.google.com/docs/cloud-messaging/android/client
How to send app notifications via FirstHive?
To send the notification to your app users, you need to integrate FCM with FirstHive,
- Implement the below API to push the required details, for each user
URL: https://firsthive.com/engage/mobile/doAppUserSubscription
Method: POST
Parameters:
| Param | Data Type | Description | Required |
| projectId | int | <Site ID> Provided by FirstHive | Yes |
| Data | string | Email and/or Mobile number of users for user identification | Yes |
| regId | string | FCM Token | Yes |
| visitId | string | Visitor ID | Yes |
| Browser | string | Browser | Optional |
Example:
"projectId":"85"
"data":{"mobileNo":"1234567890","email":"[email protected]"}
"regId":"c3MyLdaDD7I:APA91bH-TO2aDrg6_-gl-MzEKrMfoAehnCpsnwmxc3TOv4MlUrIKRobRma5rVQvKaf1B3iR3xadzTDPxrO5yjlqsig1GGlzx00TUTnSJCTRfPyZjyWKcEpC1ilAclMccFJZH5oLoZvpg"
"visitId":"dd49680dc9ab2c53"
"browser":"iOShybrid"
|
How to Fetch Visitor Id?
Define below after the firsthive sdk is executed:
var visitor_id;
_paq.push([ function () { visitor_id = this.getVisitorId(); }]);
|
Share the Legacy server key with FirstHive
Follow below steps
https://console.firebase.google.com/project/
Path to key in Firebase >> Project >> Project Settings >> Cloud Messaging >> Legacy server key
Steps to enable tracking of ‘Opens’ for App Push Notifications
When a user tap on the app push notification sent from FirstHive, it will pass a Message ID to the app in the data payload in the following key.
messageId: <Unique value to identify the user and campaign>
Example Below
{
"to" : "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"collapse_key" : "YYYYYYYYYYYYYYYYYYYYYYYYYY",
"notification" : {
"body" : "Test notification content",
"title": "Title of the message",
"image": "<Image URL>"
},
"data" : {
"url":"<URL>",
"customPayload": {
"screen":"HomePage",
"messageId":"123456
}
}
}
|
Whenever the app receives a value in the data payload for the above key, it should trigger following API and pass the tracking ID back to FirstHive URL: https://firsthive.com/engage/mobile/trackNotification
Method: POST
Param:
| Param | Data Type | Description | Required |
| authKey | string | XXXXXXXXXXXXXXXXX (Will be shared separately for the account).
Contact your account representative for authentication key. |
Yes |
| messageId | int | <messageId to identify the user for the campaign, received in the custom payload section mentioned above> | Mandatory |