Android SDK 3.0

What changes when you move the Grovs Android SDK from 1.x to 3.0

3.0.0 is a major release. Every public method and property from 1.1.1 is still present. Kotlin code using named arguments compiles unchanged; the one signature change is that both generateLink overloads gained copyToClipboardIos and copyToClipboardAndroid before tracking, which breaks positional Kotlin calls and Java calls that passed tracking. What changes is behavior: automatic screen tracking is on by default, setSDK(false) now stops all collection, and clipboard-assisted deferred deep linking runs on the first launch. Most apps upgrade by bumping the version, deciding on screen tracking, and checking how they gate on consent.

Requirements are unchanged: Android 5.0 (API 21), Kotlin 1.8 or later.

There is no 2.x. The Android SDK goes from 1.1.1 straight to 3.0.0 so that all Grovs native SDKs share one major version with the same feature set.

Checklist

Bump the dependency to 3.0.0.
Decide on automatic screen tracking — it is on by default.
Review your consent gating — setSDK(false) now stops everything, and configure has an enabled parameter.
Fix PaymentEventType names if you followed older docs.
Check the other behavior changes — the clipboard toast, event batching, link lookup retries, and your Data safety form.

1. Bump the version

In your app-level build.gradle:

Groovy

dependencies {
    implementation("io.grovs:Grovs:3.0.0")
}

Then sync Gradle. The SDK adds androidx.fragment:fragment-ktx, which was already reachable transitively, and still declares only the INTERNET and ACCESS_NETWORK_STATE permissions.

2. Decide on automatic screen tracking

This changes behavior without any code edit on your side.

autoTrackScreenViews defaults to true. An app that only bumps the version starts reporting a screen_view event for every Activity and Fragment that resumes.

Keep it if you want screen analytics — see Events & Screen Tracking for what is and is not tracked (Fragments over their host Activity, no modals, no Compose) and how to name screens.

To opt out, use the overload that takes autoTrackScreenViews:

Kotlin

Grovs.configure(this, "your-api-key", useTestEnvironment = false, baseURL = null, autoTrackScreenViews = false)

The 1.1.1 configure(application, apiKey, useTestEnvironment, baseURL) overload still exists and compiles unchanged; it now means autoTrackScreenViews = true.

setSDK(false) now stops everything. In 1.1.1 it blocked link generation, link details, and deep link resolution but left lifecycle event collection running. In 3.0, while disabled, the SDK does not authenticate, resolve the device, read the clipboard, or send lifecycle events, custom events, screen views, or purchases. Outstanding requests and their retries are cancelled. Changes to identifier, attributes, pushToken, and screen aliases are held and synced when you enable it again. Events already queued stay on the device.

Start disabled with enabled. Calling setSDK(false) right after configure is too late — configuring starts the first round of collection. If you gate on consent, pass it to configure:

Kotlin

// 1.x — collection has already started when setSDK runs
Grovs.configure(this, "your-api-key", useTestEnvironment = false)
if (!hasConsent) {
    Grovs.setSDK(false)
}
 
// 3.0
Grovs.configure(
    this, "your-api-key", useTestEnvironment = false, baseURL = null,
    autoTrackScreenViews = true, clipboardDomains = null,
    enabled = hasConsent
)

The value is not persisted, so pass your stored consent on every launch. The shorter configure overloads reset it to true. See Privacy & Consent.

Enabling does not replay a launch link. If the app was opened from a link while disabled, forward onStart or onNewIntent again after enabling to resolve it.

4. Check `PaymentEventType` names

The enum has always been BUY, CANCEL, and REFUND. Earlier versions of these docs listed CANCELLATION, which never existed — if you copied that name your code did not compile, so there is nothing to change in a working app. Use PaymentEventType.CANCEL for cancellations.

5. Check the other behavior changes

Clipboard-assisted deferred deep linking is on. On the first launch after install, when fingerprint matching found nothing and the backend reports recent clicks on copy-to-clipboard links for your project (currently a 48-hour window), the SDK reads the clipboard to attribute the install. On Android 12 and later the system shows its "pasted from your clipboard" toast once. If you never enable copy-to-clipboard for your project or its links, the clipboard is never read. See Clipboard-assisted deferred deep linking.

Events are batched. Lifecycle events and custom events are sent through a batch endpoint, with custom events flushed every 30 seconds. Up to 1,000 events are kept for seven days.

Install attribution has a 25-second budget. Events queued during a fresh install are held until the install-referrer lookup, fingerprint match, and clipboard fallback resolve, or the budget runs out, so they are credited to the right link.

Link lookups recover from outages differently. In 1.1.1 a failed lookup was retried inside the call indefinitely, every 5 then 10 seconds. In 3.0 the in-call retries are bounded, and a tapped link whose lookup still failed is retried at the session level — after a widening wait, on foreground, and when the network returns — with the listener firing once it succeeds.

Purchases carry a session. Purchase events now include the analytics session they were logged in.

Update your Data safety form. Screen views and custom events are new categories of collection. Check your Google Play Console declarations against what the SDK collects.

What's new in 3.0

Nothing here is required:

Custom events and screen tracking — track, trackScreenView, trackNavigation for Jetpack Navigation, global tags, and screen aliases.
Consent gating — the enabled parameter on configure, and a setSDK that stops all collection.
Clipboard-assisted deferred deep linking — deterministic install attribution on first launch, with clipboardDomains for custom link domains.
copyToClipboardIos / copyToClipboardAndroid — per-link override of the project's copy-to-clipboard setting.

Verifying the upgrade

Turn on info logging before configure and filter Logcat by the message text GROVS (the tag is Logger):

Kotlin

Grovs.setDebug(LogLevel.INFO)
Grovs.configure(this, "your-api-key", useTestEnvironment = true)

Then check that deep links still reach your GrovsDeeplinkListener, and — if you kept automatic screen tracking — that screen views appear in the dashboard under names you recognize. Use setScreenAliases to rename any that read like class names.