Installing the Freshpaint Android SDK

To install the Freshpaint Android SDK, add the following dependency to your gradle file:

implementation 'io.freshpaint.android:freshpaint:2.1.0'

To import the SDK, use:

import io.freshpaint.android.Freshpaint;
import io.freshpaint.android.Properties;

Then to initialize the SDK, you should run:

Freshpaint freshpaint = new Freshpaint.Builder(getApplicationContext(), "<your environment id>")
    .trackApplicationLifecycleEvents()
    .trackDeepLinks()
    .recordScreenViews()
    .build();

Freshpaint.setSingletonInstance(freshpaint);

You can get your environment id from the Freshpaint sources page.

You should run the initialization code in either the onCreate method of your class that extends Application, or in the onCreate method of your main activity class.

Application Lifecycle Events

The Freshpaint Android SDK does not support general autotrack/autocapture of user interactions, such as utton clicks, form submissions, or arbitrary screen interactions. You’ll need to instrument those events with precision tracking. The SDK can optionally track app lifecycle events automatically when you enable trackApplicationLifecycleEvents(), including Application Installed, Application Opened, Application Backgrounded, and Application Updated.

Deep Link Tracking

When trackDeepLinks() is enabled, the SDK reads the Intent URI from an Activity when it is created and sends a Deep Link Opened event. The full deep link URL is included in event context as url.

The SDK also captures attribution query parameters from the deep link, including UTM parameters and common ad click IDs such as gclid, gbraid, wbraid, fbclid, ttclid, and others. These values are added to event context, not event properties. UTM values expire after 24 hours; click IDs are retained for attribution.

You must define your own Android deep link or App Link intent-filter; the SDK does not add schemes, hosts, paths, or domain verification.

If lifecycle tracking is also enabled, captured deep-link attribution can enrich the first-open Application Installed event context.

User Consent and Ad Tracking

The Freshpaint Android SDK respects the device-level “Limit Ad Tracking” setting. When ad tracking is limited, the SDK does not collect or send the Google Advertising ID (GAID) and sets limit_ad_tracking to true in the device context.

When ad tracking is allowed and Google Play Services returns an advertising ID, the SDK may include advertisingId in event context. The SDK also declares the Android 13+ com.google.android.gms.permission.AD_ID permission through its manifest.

Freshpaint does not manage user consent for your app. If your app needs consent before collecting analytics or advertising identifiers, collect that consent before initializing or using the SDK. You can also opt a device out of event collection:

Freshpaint.with(getApplicationContext()).optOut(true);

Verifying Your Instrumentation

To verify your Freshpaint installation, navigate to the Freshpaint Live View. After opening your app, you should see an Application Opened event show up in Live View:

Note, the Freshpaint SDK batches events, so it can take a minute for the event to show up.