Setup guide

From nothing to your first events in about ten minutes.

1. Create your app

Sign in, then open Settings → Apps → Add an app (or follow the setup that appears on your first visit). Give it a name, the platform and its time zone. MetricNudge shows you two values, once:

• App id, a short name such as myapp.
• Ingest key, starting tl_pk_. It can only send events, never read anything, so it is safe to put in the app itself. Treat the dashboard password and API keys differently: those never go in an app.

Add one MetricNudge app per store app. An Android build of the same product is its own app, with its own key.

2. Add the SDK

iOS (Swift)

Download MetricNudge.swift into your project. It is a single file with no dependencies beyond the system frameworks. At launch, after RevenueCat if you use it:

MetricNudge.configure(
    app: "myapp",
    key: "tl_pk_…",
    userId: Purchases.shared.appUserID   // the RevenueCat id; joins purchases to people
)

Flutter (iOS and Android)

Download metric_nudge.dart into lib/ and add device_info_plus, package_info_plus, path_provider and shared_preferences to pubspec.yaml. Release builds need the internet permission in AndroidManifest.xml.

await MetricNudge.configure(
  app: 'myapp',
  key: 'tl_pk_…',
  endpoint: Uri.parse('https://metricnudge.com/api/ingest'),
  userId: appUserId,
);

What you get without writing more code

• first_open once per install, and app_open each session (more than 30 minutes in the background starts a new one).
• Device, OS, app version, language and country, and your Apple Search Ads attribution on iOS.
• Debug builds are tagged debug, TestFlight builds testflight, and sideloaded or emulator builds test. The dashboard shows production by default, so your own testing never pollutes the numbers.

3. Track what matters

MetricNudge.track("recipe_saved", ["source": "share_sheet"])
MetricNudge.onboardingStep(2, id: "pick_goal", answer: "weight_loss")
MetricNudge.onboardingCompleted()
MetricNudge.paywallShown("onboarding")
MetricNudge.paywallPlanSelected("yearly", placement: "onboarding")
MetricNudge.paywallDismissed(placement: "onboarding")

The Flutter calls have the same names. Event names may use letters, digits and _ . : - $ and a space, up to 80 characters. Properties are small key and value pairs: keep them short and never put names, emails or other personal data in them.

Pick one event that means a new user "got it" (for example first_recipe_saved) and set it as the activation event in Settings → Apps. MetricNudge then shows how many installs reach it.

4. Connect purchases (RevenueCat)

In Settings → Apps open your app: it shows a webhook URL. Choose a secret and save it in the same place ("RevenueCat webhook secret"). In RevenueCat go to Project settings → Integrations → Webhooks, paste the URL, put the same secret in the authorization header, and send a test event. Purchases, trials, renewals, refunds and cancellations then appear in Revenue, Trials and the alerts you choose. Sandbox purchases are kept apart from real ones.

5. Check it works

Run the app on a device (a release or TestFlight build, or switch the environment filter to All envs to see debug traffic) and open the dashboard's Events page. first_open and app_open should appear within seconds. If nothing arrives: check the app id and key, that the device is online, and, for Android, the internet permission.

Any other platform: the HTTP API

Android (Kotlin or Java), web, games, a backend: send events yourself. One request carries up to 200 events.

POST https://metricnudge.com/api/ingest
x-app-key: tl_pk_…
content-type: application/json

{
  "app": "myapp",
  "sent_at": "2026-11-02T10:00:03Z",
  "events": [
    { "event_id": "uuid-1", "name": "first_open", "ts": "2026-11-02T10:00:00Z",
      "device_id": "stable-random-id", "session_id": "uuid-of-session",
      "user_id": "revenuecat-app-user-id", "env": "release",
      "platform": "android", "app_version": "1.0.0",
      "props": { "source": "share_sheet" } }
  ]
}

The answer is 200 {"ok":true} only when the batch is stored; retry anything else with a short backoff. A 401 means the app id or key is wrong.

Ask your data from Claude

On paid plans you can create a read-only API key (Settings → API keys) and connect Claude Code or any MCP client to your numbers and your keyword rankings. A key can look but never change anything, and never sees secrets.

Privacy

MetricNudge stores a random device id, the events you send and the country the request came from. It does not need names, emails or advertising ids. You can export or delete everything from Settings. See the privacy policy. Remember to mention an analytics provider in your own privacy policy and, where the law requires it, in your App Store privacy answers.

Stuck? The contact address is at the foot of the privacy policy.