Flutter SDK

Full reference for onramp_sdk. Works with Flutter on iOS and Android.

Installation

flutter pub add onramp_sdk

Milestone tracking and sessions are pure Dart (dart:io and http). Deep-link attribution (see Attribution below) pulls in the app_links plugin - no manual native setup beyond the standard platform Universal Link/App Link configuration your app already needs for deep links to work at all.

Setup

Call OnRamp.initialize() once when your app starts, before any OnRamp.step() calls. A good place is main() or your root widget's initState.

import 'package:flutter/material.dart';
import 'package:onramp_sdk/onramp_sdk.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await OnRamp.initialize(
    apiKey: 'onr_YOUR_API_KEY',
    appVersion: '1.0.0', // optional - surfaces a version breakdown in your dashboard
  );
  runApp(const MyApp());
}

Your API key is on the Settings page of each app in the dashboard.

OnRamp.initialize() options

Tracking steps

OnRamp.step(name, {properties?})

Records a funnel milestone. Safe to call from any widget or service - the SDK fires and forgets over HTTP.

import 'package:onramp_sdk/onramp_sdk.dart';

// Basic
OnRamp.step('account_created');

// With custom properties
OnRamp.step('subscription_started', properties: {
  'plan': 'pro',
  'billing_period': 'annual',
  'price_usd': 79.99,
});

Options

Identifying users

OnRamp.identify(traits)

Associates the current anonymous user with known identity traits. Call once after sign-in so integrations (Stripe, RevenueCat) can match the user to external records.

// After the user signs in
OnRamp.identify({
  'email': user.email,
  'userId': user.id,
});

identify() is entirely optional. All funnel and retention features work without it. Only call it if you have an integration connected and want to correlate OnRamp sessions with external revenue data.

Attribution

The SDK can capture which channel or campaign drove an install, so you aren't blind to what's working the way you would be with milestone data alone. This is off by default - set captureInstallReferrer: true to turn it on:

await OnRamp.initialize(apiKey: 'onr_YOUR_API_KEY', captureInstallReferrer: true);

It defaults to false rather than true because turning it on starts collecting a new category of data (campaign/referrer info) that you should consciously opt into rather than get for free on an SDK upgrade. OnRamp.setAttribution() (below) works regardless of this flag, so it's always safe to call if you get attribution data from elsewhere.

Deep links

On app launch, the SDK reads utm_source/utm_medium/utm_campaign/utm_term/utm_content from the Universal Link/App Link that opened the app (falling back to known ad click IDs - gclid, fbclid, etc). This is attached once, to the very first tracked event for the install, and never re-attached on later app opens.

myapp://open?utm_source=newsletter&utm_medium=email&utm_campaign=spring_launch

Configuring the Universal Link (iOS associatedDomains) or App Link (Android intentFilters) itself is a separate, still-required app configuration step - the SDK only reads the URL once your app is already set up to receive it.

OnRamp.setAttribution()

If you already use an MMP (Adjust, AppsFlyer, Branch, etc.) for install attribution, leave captureInstallReferrer at its default false and call this from your MMP's attribution-resolved callback instead:

await OnRamp.initialize(apiKey: 'onr_YOUR_API_KEY'); // captureInstallReferrer left at its default (false)

// Inside your MMP's attribution callback:
OnRamp.setAttribution(source: 'facebook', medium: 'paid_social', campaign: 'summer_promo');

This works independently of captureInstallReferrer - it's always safe to call, whether or not you've turned on OnRamp's own capture. No-ops if attribution has already been attached to this install's first tracked event.

Session management

OnRamp.newSession()

Force-starts a new session. Call after sign-out so the next user starts fresh.

Future<void> handleLogout() async {
  await signOut();
  OnRamp.newSession();
}

OnRamp.flush()

Waits for all in-flight events to finish sending. Useful before the app is suspended or when running integration tests.

@override
void dispose() {
  OnRamp.flush();
  super.dispose();
}

Server-side correlation

OnRamp.getIds()

Returns the current anonymous and session IDs so your backend can associate server-side events (purchases, trial starts) with this session.

final ids = OnRamp.getIds();
await myApi.post('/checkout', {
  'onramp_anonymous_id': ids.anonymousId,
  'onramp_session_id': ids.sessionId,
});

Platform support

The SDK reports platform automatically based on dart:io:

Offline support

Events are sent immediately over HTTP. If the network is unavailable, the call fails silently. For guaranteed delivery in poor network conditions, call OnRamp.flush() at lifecycle boundaries (e.g. AppLifecycleState.paused) to ensure in-flight events complete before the OS suspends the app.