Android SDK

Last updated on May 30, 2023

We have migrated our webhooks infrastructure for better scalability and throughput. As a result, the old Webhook URLs are deprecated and will stop working soon. Please migrate to the new webhook URL (provided in the Set up Webhook section of your Pipeline Overview page) to avoid disruption in your data loading operations.

new webhook notice


1. Add Dependencies to app/build.gradle

"dependencies" {
    ...  
    "implementation" 'com.hevodata:android:1.0.0'  
    ...  
}

2. Add Permissions to app/src/main/AndroidManifest.xml

<uses-permission android:name="android.permission.INTERNET" />

Other optional permissions include:

<!--  
 This permission is recommended, and can be used to decide if data needs to be pushed to Hevo's server.
-->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<!--  
  If enabled, this permission will allow us to include information about bluetooth's state.
-->  
<uses-permission android:name="android.permission.BLUETOOTH" />

3. Add Integration token and Integration Endpoint to _app/src/main/AndroidManifest.xml

<application>  
    <meta-data  
        android:name="com.hevodata.android.IntegrationToken"  
        android:value="my-integration-token"/>  
    <meta-data  
        android:name="com.hevodata.android.IntegrationEndpoint"  
        android:value="https://my-company.hevo.io/"/>  
</application>

Other configuration options are:

com.hevodata.android.EnableDebugLogging  
// A boolean value. If true, emit more detailed log messages. Defaults to false.  

com.hevodata.android.BulkUploadLimit  
// An integer count of messages, the maximum number of messages to queue before an upload   
// attempt. This value should be less than 50 and is defaulted to 50.  

com.hevodata.android.FlushInterval  
// An integer number of milliseconds, the maximum time to wait before an upload if the   
// bulk upload limit isn't reached.  

com.hevodata.android.DataExpiration  
// An integer number of milliseconds, the maximum age of records to send to Hevo.  

com.hevodata.android.MinimumDatabaseLimit  
// An integer number of bytes. Hevo attempts to limit the size of its persistent data
// queue based on the storage capacity of the device, but will always allow queing below   
// this limit. Higher values will take up more storage even when user storage is very full.  

com.hevodata.android.DisableAppOpenEvent  
// A boolean value. If true, do not send an "$app_open" event when the HevoAPI object is   
// created for the first time. Defaults to true - the $app_open event will not be sent by default.  

com.hevodata.android.CaptureAutomaticEvents  
// A boolean value. If not set, automatic events will not be replicated.  

com.hevodata.android.MinimumSessionDuration  
// An integer number. The minimum session duration (ms) that is tracked in automatic   
// events. Defaults to 10000 (10 seconds).  

com.hevodata.android.SessionTimeoutDuration  
// An integer number. The maximum session duration (ms) that is tracked in automatic events.   
// Defaults to Integer.MAX_VALUE (no maximum session duration).  

com.hevodata.android.TestMode  
// A boolean value. If true, in-app notifications won't be marked as seen. Defaults to false.

4. Add Hevo to your main activity MainActivity.java

import com.hevodata.android.hmetrics.HevoAPI;  
public class MainActivity extends AppCompatActivity {  
    @Override  
    protected void onCreate(Bundle savedInstanceState) {  
        super.onCreate(savedInstanceState);  
        HevoAPI hevoAPI = HevoAPI.getInstance(this);  
    }  
}

5. Tracking An Event

try {  
    JSONObject payload = new JSONObject();  

    JSONObject name = new JSONObject();  
    name.put("first_name", "John");  
    name.put("last_name", "doe");  
    payload.put("name", name);  

    JSONArray interests = new JSONArray();  
    interests.put("mountaineering");  
    interests.put("reading");  
    payload.put("interests", interests);  

    payload.put("age", 12);  

    hevoAPI.track("application-user", payload);  
} catch (JSONException e) {  
    e.printStackTrace();  
}

6. Time Tracking
To record the time consumed by a long running function call:

hevoAPI.timeEvent("timed_event");  
longRunningTask.finishCallback(HevoAPI.track("timed_event"))

7. User Identity and Alias
Hevo associates a random distinct_id with each app installation which is later used to track user activity on the app. This distinct_id can be changed into something that is used to identify a user by your application. For e.g. users email_id or even user_id. All the Events that follow after identifying a user will contain the user-id used to identify the user rather than distinct_id.

hevoAPI.identify("user@example.com");

Hevo also allows developers to add aliases for an installation. To add an alias just call:

hevoAPI.alias("123", "John Dao");

8. Super Properties
Hevo Lets developers add properties for an installation this can later be used in your analytics queries.

try {  
    JSONObject superProperties = new JSONObject();  
    superProperties.add("user_billing_plan", "Starter");  
    hevoAPI.registerSuperProperties(superProperties);  
} catch (JSONException e) {  
    e.printStackTrace();  
}

To remove a super properties call:

hevoAPI.unregisterSuperProperty("user_billing_plan");

To clear all super properties call:

hevoAPI.clearSuperProperties();

9. Flush Events
Hevo automatically flushes events to its backend servers. All events are flushed in a batch and at an interval to save battery. But you can flush it on demand calling:

hevoAPI.flush();

10. Opt Out of Tracking
If an app user has preferred to opt out of tracking, you can ask the SDK to not track events for that user by calling:

hevoAPI.optOutTracking();

To opt a user in(user is by default opt-in) call:

hevoAPI.optInTracking();

11. Analysing Events on Hevo’s Dashboard
Hevo sends events tracked by you plus some extra events to the backend servers. The event sent by you will appear in Hevos dashboard as it is. But the events generated by the SDK itself start with a prefix $hae_ and $hre_. Description of events generated by Hevo is as follow.

$hre_installation: This event contains installation details such as device info, app version and other app info and super properties.

$hre_alias: This event contains aliases associated to a user.

$hre_identity_change: The event contains information of a user’s previous identity and new identity.

$hae_first_open: This event contains information regarding when the app was first opened.

$hae_session: This event contains information regarding app session.




See Also

Tell us what went wrong