Flutter SDK

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

Installation

flutter pub add onramp_sdk

No native plugins required. The SDK is pure Dart and uses only dart:io and the http package.

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',
    host: 'https://ingest.getonramp.dev',
    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.

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.