Segment

Log in to your Segment workspace at app.segment.com. In the left sidebar, click 'Sources' then 'Add Source'. For a FlutterFlow mobile app, select 'Android' or 'iOS' as your source type — these correspond to the mobile SDK events you'll be sending. If you're building both iOS and Android from FlutterFlow (which you are, since FlutterFlow compiles to both), you can create one source for each platform or use a single source and differentiate by sending a `platform` property with each event. Alternatively, select 'HTTP API' as the source type, which accepts events from the Tracking API directly and works for both the Custom Action SDK path and the web Tracking API fallback. After creating the source, click into it and go to Settings → API Keys. Copy the 'Write Key'. This is the value you'll use in your Custom Action to initialize the Segment SDK. Important distinction: the write key is a source-specific publishable key — it lets code send events to this particular Segment source. It does NOT grant access to your Segment workspace settings, destinations, or other sources. This is why it's safe to use in client code. Keep it separate from the Segment Public API Bearer Token (used for workspace management via the Config API), which is a secret and must never appear in FlutterFlow. For destinations: don't enable them yet — you'll come back to this after verifying events flow correctly in Step 3. Premature destination configuration before the event flow is verified makes debugging harder.

In your FlutterFlow project, go to the left nav and click 'Custom Code' (the code bracket icon). Click '+ Add' and select 'Action'. Name it 'InitializeSegment'. In the Dependencies field, add `analytics_flutter: ^2.0.0` — check pub.dev for the latest stable version of the `analytics_flutter` package before pinning a version. FlutterFlow will add this to your project's pubspec.yaml automatically. Set no return type for the init action (it initializes the SDK globally). Add one argument named 'writeKey' of type String. Paste the initialization Dart code from the code block. This action should be called once at app startup: add it to the On Initialization Action of your initial page or a splash screen. Next, create a second Custom Action named 'SegmentTrack'. Add arguments: `eventName` (String), `properties` (JSON/Map). This action calls `analytics.track(TrackEvent(event: eventName, properties: properties))` using the Analytics singleton. Repeat for 'SegmentIdentify' with arguments `userId` (String) and `traits` (JSON/Map). To use these Custom Actions: in the Action Flow Editor for any widget, click '+ Add Action' → select 'Custom Actions' → select 'SegmentTrack' → fill in the event name (e.g., 'Product Viewed') and the properties JSON object (build it with FlutterFlow's JSON builder from your widget state values). Remember: Custom Actions do not run in FlutterFlow's web Run mode preview. The browser preview doesn't support the compiled Dart environment that the analytics SDK needs. Test exclusively on a real device via Test Mode. To confirm events arrive, open Segment's Debugger tab on your source — events appear in real time as they're sent from your device.

1// FlutterFlow Custom Action: InitializeSegment
2// Dependencies: analytics_flutter: ^2.0.0
3// Arguments: writeKey (String)
4// Return type: void
5import 'package:analytics_flutter/analytics_flutter.dart';
6import 'package:analytics_flutter/state.dart';
7
8Final _analytics = Analytics.with(Configuration(writeKey));
9
10// Note: In production, use a singleton pattern to avoid re-initializing.
11// Store the Analytics instance in a global variable or use the Analytics.with
12// factory which handles this internally.
13
14Future<void> initializeSegment(String writeKey) async {
15  final configuration = Configuration(writeKey)
16    ..trackApplicationLifecycleEvents = true
17    ..debug = false; // Set to true during development
18  
19  await Analytics.setup(configuration);
20}
21
22// =====================================================
23// FlutterFlow Custom Action: SegmentTrack
24// Arguments: eventName (String), properties (dynamic)
25// Return type: void
26import 'package:analytics_flutter/analytics_flutter.dart';
27import 'package:analytics_flutter/event.dart';
28
29Future<void> segmentTrack(
30  String eventName,
31  dynamic properties,
32) async {
33  final analytics = Analytics.shared();
34  if (analytics == null) {
35    debugPrint('Segment not initialized. Call initializeSegment first.');
36    return;
37  }
38
39  final props = properties is Map<String, dynamic>
40      ? properties
41      : <String, dynamic>{};
42
43  await analytics.track(TrackEvent(
44    event: eventName,
45    properties: props,
46  ));
47}
48
49// =====================================================
50// FlutterFlow Custom Action: SegmentIdentify
51// Arguments: userId (String), traits (dynamic)
52// Return type: void
53Future<void> segmentIdentify(
54  String userId,
55  dynamic traits,
56) async {
57  final analytics = Analytics.shared();
58  if (analytics == null) return;
59
60  final traitMap = traits is Map<String, dynamic>
61      ? traits
62      : <String, dynamic>{};
63
64  await analytics.identify(IdentifyEvent(
65    userId: userId,
66    traits: Traits.fromMap(traitMap),
67  ));
68}

Before enabling any destinations, confirm that events are flowing correctly from your FlutterFlow app to Segment. Install a Test Mode build on a real device. Open Segment in your browser → your source → 'Debugger' tab. Trigger some actions in your app (tap a button that calls SegmentTrack, or navigate to a screen that calls SegmentTrack on page load). Within a few seconds, you should see the events appear in the Debugger with their event names and properties. In the Debugger, click on an event to inspect its full payload. Verify that: - The event name is correct (exactly matches what you want in your downstream tools) - All properties you passed are present and have the right values - The `context.os.name` and `context.library` fields show the device platform and SDK version Once events are flowing and look correct in the Debugger, go to your source → 'Destinations' → 'Add Destination'. Search for the tools you want to send data to (Google Analytics 4, Mixpanel, Amplitude, etc.). Segment will prompt you for destination-specific configuration — for GA4, this means your Measurement ID; for Mixpanel, your project token. Follow each destination's setup wizard. Critical warning: do NOT also install the GA4 Firebase Analytics toggle (Settings & Integrations → Firebase → Google Analytics) alongside Segment. If both Segment's GA4 destination and FlutterFlow's native Firebase Analytics are active, every event gets counted twice in GA4 — once from Segment's server-side delivery and once from the native SDK on the device. Pick one path. If you want Segment as the source of truth for GA4, disable FlutterFlow's native Firebase Analytics toggle. This double-counting pitfall extends to all destinations: if you use Segment for Mixpanel, remove any direct Mixpanel SDK you might have added. Segment's job is to be the one place you instrument.

The `analytics_flutter` Custom Action is device-only — it uses compiled Dart code that does not run in FlutterFlow's web environment. If your FlutterFlow app is a web build (or you want analytics on both mobile and web), you need the Segment HTTP Tracking API as an alternative or complement. The HTTP Tracking API is a REST endpoint at `https://api.segment.io/v1/track` (and `/v1/identify`, `/v1/page`, `/v1/batch`). It accepts the same event format as the SDK but over plain HTTP. Authentication uses HTTP Basic Auth with your write key as the username and no password. In FlutterFlow, create an API Group named 'SegmentHTTP' with base URL `https://api.segment.io`. For authentication, select 'Basic Auth' → enter your write key as the username and leave the password empty. Add API Calls for 'Track' (POST `/v1/track`), 'Identify' (POST `/v1/identify`), and optionally 'Batch' (POST `/v1/batch`). Each call body takes a JSON object with the required Segment fields. The Track body needs at minimum: `type`, `event`, and `userId` or `anonymousId`. Note on write key in Basic Auth: unlike a secret key, the Segment write key in an API Group header is acceptable (it's the same key used in the mobile SDK). However, if you want to be extra cautious, you can route these calls through a Cloud Function. For the write key — a publishable, send-only key — the direct API Call pattern is widely used and is the approach Segment's own documentation recommends for client-side HTTP tracking. For mobile + web apps: use the Custom Action SDK for native device builds (better performance, offline queuing, automatic context metadata) and the HTTP API Call for web builds. You can detect the platform using a FlutterFlow Conditional Action (Platform == Web → use API Call, otherwise → use Custom Action).

1// Segment HTTP Tracking API — Track event
2// FlutterFlow API Call body (POST /v1/track)
3// Content-Type: application/json
4// Auth: Basic (writeKey as username, password empty)
5{
6  "type": "track",
7  "event": "{{eventName}}",
8  "userId": "{{userId}}",
9  "anonymousId": "{{anonymousId}}",
10  "properties": {
11    "category": "{{category}}",
12    "label": "{{label}}",
13    "value": "{{value}}"
14  },
15  "context": {
16    "library": {
17      "name": "FlutterFlow HTTP",
18      "version": "1.0.0"
19    }
20  },
21  "timestamp": "{{timestamp}}"
22}
23
24// Segment HTTP Tracking API — Identify user
25// FlutterFlow API Call body (POST /v1/identify)
26{
27  "type": "identify",
28  "userId": "{{userId}}",
29  "traits": {
30    "email": "{{email}}",
31    "name": "{{name}}",
32    "plan": "{{plan}}"
33  },
34  "timestamp": "{{timestamp}}"
35}