Metrickle

Android SDK

Last updated

Use the Kotlin SDK to add Metrickle to an Android app built with Views or Jetpack Compose. It follows the same rules as the other SDKs, so a funnel, task or survey means the same thing on Android as on the web. For what each event means and how to name your own, see Events, people and properties.

Native Android SDK for Metrickle: accessibility-first UX research and conversion analytics. It follows the same event model as the other Metrickle SDKs, so a funnel, task or survey means the same thing on Android, iOS, Flutter and the web.

  • metrickle: the core SDK. It covers events, sessions, automatic screens, rage taps, form errors, accessibility context, the survey engine (headless) and feedback. It needs Kotlin coroutines, kotlinx.serialization and androidx.lifecycle:lifecycle-process. It has no HTTP library (it uses HttpURLConnection).
  • metrickle-compose adds Jetpack Compose helpers: TrackScreen, Modifier.metrickleTag and MetrickleSurveyHost, a built-in survey sheet designed to meet WCAG 2.2 AA.

minSdk 23, compileSdk 36.

Install

// build.gradle.kts
dependencies {
    implementation("com.metrickle:metrickle:0.2.0")
    implementation("com.metrickle:metrickle-compose:0.2.0") // optional, Compose apps
}

The library declares INTERNET. Its consumer ProGuard/R8 rules keep the serializable wire models.

Quick start

Views

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        Metrickle.init(this, "mk_pub_YOUR_WRITE_KEY", MetrickleOptions(debug = BuildConfig.DEBUG))
    }
}

// Anywhere, from any thread:
Metrickle.track("checkout_started", mapOf("plan" to "pro"))
Metrickle.identify("user_123", mapOf("plan" to "pro"))
Metrickle.formError(form = "signup", field = "email", reason = "invalid") // never the field's contents
Metrickle.reset() // on logout

Each Activity is tracked as a screen when it resumes. The screen name is the class name without Activity, so CheckoutActivity becomes Checkout. Class names stay the same in every locale. To choose a name or skip an Activity, implement MetrickleScreen:

class CheckoutActivity : AppCompatActivity(), MetrickleScreen {
    override val metrickleScreenName: String? = "Checkout" // null skips this Activity
}

Rage taps (3 taps within 1s inside 30dp) report the tapped view’s id resource name as selector, and its content description as text (at most 80 characters). The SDK never reads text field contents. The SDK only observes the Activity window. Dialogs and popups have their own windows, so taps in them aren’t observed.

Java:

Metrickle.init(this, "mk_pub_YOUR_WRITE_KEY");
Metrickle.track("checkout_started");

Compose

Single-Activity Compose apps should turn off Activity screens and name each destination:

Metrickle.init(this, "mk_pub_YOUR_WRITE_KEY", MetrickleOptions(automaticScreenTracking = false))

@Composable
fun CheckoutScreen() {
    TrackScreen("Checkout")
    Button(onClick = pay, modifier = Modifier.metrickleTag("pay_button")) { Text("Pay") }
}

Modifier.metrickleTag(id) sets testTag and gives rage, dead and slow taps a selector. Compose has no view ids.

Revenue from Stripe or RevenueCat

Connect your RevenueCat project (or Stripe account) in the Metrickle dashboard under Integrations → Revenue. Purchases, renewals, refunds and cancels then arrive server-side on the person you identified, so a refund takes back the task they completed. Log in to RevenueCat with the same id:

Metrickle.identify(user.id)
Purchases.sharedInstance.logInWith(user.id)
// Or keep RevenueCat's id and name the Metrickle user:
// Purchases.sharedInstance.setAttributes(mapOf("metrickle_user_id" to user.id))

Options

OptionDefault
hosthttps://in.metrickle.comIngest origin
cookielessfalseNothing is persisted: no anonymous or session id (the server derives a daily-rotating hash), no offline queue and no surveys
flushIntervalMs5000The SDK also flushes at 20 queued events and when the app goes to the background
sessionTimeoutMs30 minInactivity before a new session starts
automaticScreenTrackingtrue$screen on Activity resume
rageTapstrue$rage_click detection
deadTapstrue$dead_click and $slow_click detection (see Dead and slow taps)
debugfalseLogs every queued event and send result (Logcat tag Metrickle)
beforeSendnullBeforeSend { event -> event or null } to edit or drop an event before it’s queued
appVersion / appBuildfrom the packageOverride versionName / versionCode

Other API: register(props) (super properties), optOut() / optIn(), consent(replay = true), flush(), refreshConfig(), and Metrickle.client for the MetrickleClient (identity(), getContext(), a11yFlags, config, suspend flushNow()).

Automatic events: $app_open on launch and each return to the foreground, $app_background and then a flush, $screen, $u_turn (A → B → A within 7s), $rage_click, $dead_click, $slow_click and $form_error. The accessibility context is sent with each batch: screen_reader (TalkBack), keyboard (a hardware keyboard or Switch Access), reduced_motion, high_contrast, inverted_colors, bold_text and large_text.

Dead and slow taps

A tap on a control that nothing answers within 4 seconds sends $dead_click; one answered after 1 to 4 seconds sends $slow_click with ms, how long it took. They carry the same properties as the web SDK’s dead clicks (selector, text, input: "touch", affordance: "control") and the screen the tap happened on, so friction reports and cases treat them alike. Turn it off with MetrickleOptions(deadTaps = false); rage taps are separate.

  • Which taps. A touch that goes down and up within the touch slop, on the nearest enabled view that is clickable or long-clickable. Text fields (EditText), sliders (AbsSeekBar) and disabled views aren’t judged. In Compose, it’s the innermost semantics node under the finger with an enabled click action (text fields aren’t judged); Modifier.metrickleTag("id") names it, otherwise its role. Compose taps are judged automatically when metrickle-compose is on the classpath; there’s nothing to call.
  • What counts as an answer. Any event after the tap other than friction signals ($rage_click, $form_error and the like): a new screen, your own track(), the app going to the background. Or a change on screen: when the finger goes down the SDK takes a cheap fingerprint of the window (each view’s bounds, visibility, scroll, enabled, selected, activated and checked state, a hash of TextView text, window focus, and under Compose the semantics tree), and compares it 1 second later, then every 250ms until 4 seconds. Pressed and ripple states are left out. Text is only hashed on the device, never sent.
  • Something that animates by itself (a looping progress indicator, say) counts as a change, so it can hide a dead tap. Nothing makes a working tap look dead.

The SDK persists events in SharedPreferences("metrickle"): up to 1000, for 7 days. Events queued before the app is killed are sent on the next launch. Failed sends retry with backoff (1s doubling to 60s).

Surveys

Surveys are authored in the dashboard. The SDK decides when to show them: trigger, targeting, sampling, frequency caps and a 24h global cooldown. There are two ways to render them. Without either, surveys never show.

Built-in sheet (Compose): place the host once at your root, inside your MaterialTheme:

setContent {
    AppTheme {
        Box { AppNavHost(); MetrickleSurveyHost() }
    }
}

The sheet is a Material 3 ModalBottomSheet:

  • It is announced once as “Survey”, and TalkBack and keyboard focus move to the question heading when it opens and on each new question.
  • Scale questions are radio groups of targets at least 48dp. Each option’s label includes the end labels (“0, Not at all likely”).
  • Choice questions use native radio buttons or checkboxes. Text questions use a labelled multiline field.
  • It follows font scale (it scrolls instead of truncating), your theme’s dark mode, and high contrast (high-contrast text or, on Android 14 and later, the contrast setting): borders and secondary text use the full text colour, and Close, Skip and No thanks are outlined.
  • It does not animate when animations are removed.
  • It has a visible Close button, and back or Escape dismisses it. A thank-you message ends the survey.
  • If the campaign has a follow-up and the answers qualify, the Submit button says “One moment…” (focus stays on it) while the sheet asks for the person’s study link, for up to 5 seconds. With a link, it shows the invite: focus moves to its heading, and TalkBack reads it. “Choose a time” (a video call) or “Take part” (a self-guided test) opens the link in the browser. “No thanks” goes to the thank-you. Without a link, it shows the thank-you.
  • It uses the brand accent only when the accent reaches 4.5:1 against the sheet. Otherwise it uses your theme’s primary.

Headless: render with your own UI. A custom renderer takes precedence over the host.

val sub = Metrickle.surveys.onShow { survey ->   // main thread
    showMySurveyUi(survey.campaign,
        onShown = { survey.shown() },
        onAnswer = { q, a -> survey.answer(q, a) }, // SurveyAnswer(score =, values =, text =)
        onDone = { survey.complete() },
        onClose = { index -> survey.dismiss(index) })
}
Metrickle.surveys.show("cmp_123") // QA: show now, ignoring targeting

Follow-ups (study invites)

A campaign can invite people who answered into a study: a booked video call (moderated) or a self-guided test on the web (unmoderated). survey.followUp is set only while the study is recruiting. when (the condition property) limits the invite to some answers, for example NPS 0–6. The built-in sheet handles all of this. With your own UI, after the last answer:

survey.complete()
val fu = survey.followUp
if (fu != null && survey.qualifies()) {
    lifecycleScope.launch {
        // The personal link, asked once per response. Null when the study is full or the request failed.
        val url = withTimeoutOrNull(5_000) { survey.invite() }
        if (url == null) return@launch showThankYou()
        showInvite(fu.prompt, fu.kind, fu.durationMin, fu.incentive) // then call survey.followUpOffered()
        // When they accept: survey.followUpAccepted(), then open url in the browser (Intent.ACTION_VIEW).
    }
}

invite() only returns https links (or http when your host is http). followUpOffered() and followUpAccepted() each record $survey_follow_up once per response.

Feedback

lifecycleScope.launch {
    // Only after the user chose to attach a screenshot: it may contain personal data.
    val shot = Metrickle.feedback.captureScreenshot(activity) // JPEG 70, ≤ 1280px, data URL; null for FLAG_SECURE windows
    val result = Metrickle.feedback.submit(FeedbackCategory.BUG, "The pay button did nothing", rating = 2, screenshot = shot)
}

Feedback can be switched off per platform under Settings → Research in the dashboard. While it’s off, Metrickle.feedback.isEnabled is false and submit sends nothing, so use it to hide your feedback button.

Session, screen, device, app version, locale and accessibility flags are attached automatically. Java callers can use submitAsync(...) and captureScreenshotAsync(activity, callback).

Built-in feedback sheet

metrickle-compose has a “Report a problem” sheet that meets WCAG 2.2 AA, with the same copy as the web dialog. Open it from your own button or menu item; it never opens by itself:

@Composable
fun HelpMenu() {
    var reporting by rememberSaveable { mutableStateOf(false) }
    // Hide your button while feedback is switched off for Android in the dashboard.
    if (Metrickle.client?.feedback?.isEnabled == true) {
        TextButton(onClick = { reporting = true }) { Text("Report a problem") }
    }
    if (reporting) MetrickleFeedbackSheet(onDismiss = { reporting = false })
}
  • The person chooses what it’s about (Something’s broken, Something’s confusing, An idea or request, An accessibility barrier, Something else) and describes what happened (up to 4000 characters). Preselect a category with MetrickleFeedbackSheet(onDismiss, category = FeedbackCategory.ACCESSIBILITY).
  • It sends through feedback.submit, so the screen, device, app version, locale and accessibility settings are attached. It never attaches a screenshot; to send one, build your own form with captureScreenshot and submit.
  • After sending it says “Thank you! Your feedback was sent.” and waits for Done. If sending fails it says so and keeps what was typed.
  • It follows your MaterialTheme (dark theme included), uses the dashboard’s brand accent only when it has 4.5:1 contrast, strengthens borders with high contrast, scrolls at large font sizes, opens without sliding when animations are removed, and moves TalkBack focus to its heading when it opens. Close, Cancel and back dismiss it. “Powered by Metrickle” is hidden when branding is turned off in the dashboard.
  • Before Metrickle.init, or while feedback is switched off, it shows nothing and calls onDismiss at once.

A Views app can host it in a ComposeView:

binding.reportProblem.setOnClickListener {
    val host = ComposeView(this)
    (window.decorView as ViewGroup).addView(host)
    host.setContent {
        MaterialTheme { MetrickleFeedbackSheet(onDismiss = { (host.parent as? ViewGroup)?.removeView(host) }) }
    }
}

Privacy

  • No Android Advertising ID, device serials or other hardware identifiers. anonymousId is a random UUID in app storage, removed when the app is uninstalled.
  • The SDK never captures text field contents, only identifiers you pass (formError) and content descriptions.
  • After optOut() the SDK makes no network calls at all. It clears the queue and removes the anonymous id and session id from the device. It keeps your own user id (from identify) and the consent choice. isOptedOut changes as soon as optOut() or optIn() returns.
  • An opted-out device gets no anonymous id, also on later launches and after reset(). optIn() creates a new one and fetches the config again.
  • cookieless = true persists nothing.

Google Play Data safety (summary)

This depends on your configuration and on what you pass in track, identify and feedback. With the defaults:

Data typeCollectedSharedPurpose
App interactions (screens, taps, events)YesNoAnalytics
Device or other IDs (random app-scoped anonymousId, not a device ID)YesNoAnalytics
Diagnostics (OS version, device model, accessibility settings)YesNoAnalytics
User IDs (only if you call identify)OptionalNoAnalytics
Other user-generated content (survey answers, feedback text)OptionalNoAnalytics, app functionality
Photos or screenshots (only if you attach captureScreenshot)OptionalNoApp functionality

Data is encrypted in transit (HTTPS). Users can opt out, and you can offer deletion through your Metrickle workspace.