Mobile analytics event naming guide

AppMetricsKit uses Namespace.action event names so mobile teams can send consistent analytics from iOS, Android, and server-side revenue providers. Unknown well-formed names are accepted, but the built-in names below power dashboards for onboarding funnels, paywall conversion, purchase success, subscription revenue, retention readiness, and app health.

Recommended first-party events

Start with a small taxonomy and add custom events only when a dashboard question requires them. These names map directly to product pages inside AppMetricsKit, so a clean SDK integration produces useful charts without custom SQL or dashboard setup.

App.launch

Start a session and populate live activity, DAU, and platform breakdowns.

Onboarding.started

Mark the first onboarding entry point.

Onboarding.stepViewed

Track step-level drop-off with a step name or index.

Onboarding.completed

Close the onboarding funnel and measure completion.

Paywall.viewed

Count paywall impressions by plan, screen, source, or experiment variant.

Paywall.ctaTapped

Measure intent before purchase flow handoff.

Purchase.started

Capture purchase attempts before StoreKit or Play Billing completes.

Purchase.completed

Record successful purchases and revenue values.

Purchase.failed

Measure failed payments, cancellations, or billing errors.

Subscription.trialStarted

Track trial starts by plan and acquisition source.

Subscription.trialConverted

Measure trial-to-paid conversion.

Subscription.renewed

Record renewal revenue from provider or app events.

Subscription.cancelled

Track voluntary or provider-reported subscription cancellation.

Subscription.refunded

Record refunds as negative revenue values.

Subscription.billingRetry

Identify billing recovery and dunning flow volume.

Subscription.gracePeriod

Track grace-period state during billing issues.

Feature.used

Measure adoption of a named feature without collecting personal data.

Error.occurred

Track app-health events by safe error category.

What should an event payload contain?

Payloads should describe product context, not the person. Good keys are stable, low-cardinality, and safe to group in dashboards: plan, source, variant, screen, step, appVersion, and errorCode. Avoid raw names, emails, phone numbers, advertising IDs, precise location, and large text fields.

Code

AppMetricsKit.track(  "Paywall.viewed",  payload: [    "plan": "pro_monthly",    "source": "onboarding",    "variant": "hero_video"  ])
AppMetricsKit.track(  "Purchase.completed",  payload: ["plan": "pro_monthly"],  floatValue: 29.99)

Dashboard mapping

App.launch appears in Live Events, overview activity, platform breakdown, and retention readiness.
Onboarding.* events feed the default onboarding funnel and reveal step-level drop-off.
Paywall.* and Purchase.* events drive paywall conversion and revenue panels.
Subscription.* events reconcile provider webhook data with client-side purchase events.
Error.occurred gives product teams a lightweight health signal without sending crash logs or user text.

Naming rules for custom events

Custom events should use the same namespace pattern, for example Search.performed or Reminder.scheduled. Keep event names stable across app releases, and move changing labels into payload keys. If an event needs a person-specific value to be useful, hash or remove that value before sending it.

Privacy rules Test-mode validation