Localytics Flutter Sample

A runnable sample app demonstrating the localytics_flutter_sdk plugin end-to-end on iOS and Android.

It replicates the public Dart API surface (events, profile attributes, in-app appearance, location, inbox, lifecycle) through a tap-driven UI, allowing you to verify dashboard integration in minutes without writing any code.

The home screen surfaces a Diagnostics card at the top (native SDK version, resolved app key, install ID) aand organizes demo buttons into labeled sections: Privacy, Customer, Events, Profile, Appearance, Location, Inbox, Lifecycle — with the result of your last call always visible at the bottom.

---

What this sample covers

Section	Plugin calls exercised
Privacy	setLoggingEnabled, setOptedOut
Customer	setCustomerId, setCustomerEmail, setCustomerFullName
Events	tagEvent, tagScreen, tagPurchased
Profile	setProfileAttribute, incrementProfileAttribute (ProfileScope.organization)
Appearance	enableDarkMode
Location	setLocationMonitoringEnabled, persistLocationMonitoring
Inbox	refreshInboxCampaigns (rendered as a list of InboxCampaigns)
Lifecycle	upload
Diagnostics	getLibraryVersion, getAppKey, getInstallId (rendered in a card at the top)

The bottom of the home screen always shows the result of your last call (e.g. tagEvent OK, tagPurchased FAILED: <error>).

---

Requirements

Tool	Minimum
Flutter	3.22 (with Swift Package Manager on)
Dart	3.5
Xcode	15 (for iOS builds)
Android	minSdk 24 (matches Flutter stable's enforced runtime floor and localytics_flutter_sdk)
Plugin	localytics_flutter_sdk: ^1.0.3 (pinned in pubspec.yaml)

Enable Swift Package Manager once per machine — the iOS plugin ships SPM-only:

flutter config --enable-swift-package-manager

---

Setup

1. Add your Localytics app keys

App keys are loaded from a local, gitignored .env file at the project root. Copy the template:

cp .env.example .env

Open .env and replace the placeholders with your real keys (find them at Localytics dashboard → Settings → Apps):

LOCALYTICS_IOS_APP_KEY=your-ios-app-key-here
LOCALYTICS_ANDROID_APP_KEY=your-android-app-key-here

iOS and Android typically have different keys — set each to the value for that platform.

2. Sync the iOS xcconfig

Android picks up .env automatically every time Gradle configures the build. iOS needs one extra step to inject the key into Info.plist via Xcode:

dart run tool/sync_env.dart

That writes ios/Flutter/LocalyticsEnv.xcconfig (gitignored), which feeds $(LOCALYTICS_APP_KEY) into Info.plist's LocalyticsAppKey entry. The iOS AppDelegate then reads that key at launch.

Re-run the script whenever you change LOCALYTICS_IOS_APP_KEY in .env.

3. Install Flutter dependencies

flutter pub get

4. Run

# iOS simulator
flutter run -d "iPhone 15"

# Android emulator / device
flutter run -d <device-id>

# List available devices
flutter devices

---

Verifying your setup

Open the app. The Diagnostics card near the top shows:

• Native SDK — e.g. 7.1.1 (iOS) or 7.1.0 (Android)
• App key — should match what you set in .env
• Install ID — a UUID assigned by the native SDK on first launch

If the App key field shows YOUR_IOS_APP_KEY / YOUR_ANDROID_APP_KEY (or is empty), a red banner appears at the top of the screen — the sample is running with placeholder values and events won't reach the dashboard. Re-check your .env, re-run dart run tool/sync_env.dart if you changed the iOS key, then rebuild.

Tap Events → tagEvent('Sample Event'). The "Last call" line should read tagEvent OK. After a few minutes the event will appear in your Localytics dashboard.

---

File layout

.
├── .env.example                          # template — copy to .env
├── .env                                  # gitignored — your real keys
├── lib/
│   └── main.dart                         # sample UI
├── tool/
│   └── sync_env.dart                     # .env → ios xcconfig
├── ios/
│   ├── Flutter/
│   │   ├── LocalyticsEnv.xcconfig.example
│   │   └── LocalyticsEnv.xcconfig        # gitignored — generated
│   └── Runner/
│       ├── Info.plist                    # LocalyticsAppKey = $(LOCALYTICS_APP_KEY)
│       └── AppDelegate.swift             # reads LocalyticsAppKey, autoIntegrates
├── android/
│   └── app/
│       ├── build.gradle.kts              # reads .env → resValue("ll_app_key")
│       └── src/main/
│           ├── AndroidManifest.xml
│           ├── kotlin/.../MainApplication.kt   # autoIntegrates
│           ├── kotlin/.../MainActivity.kt      # FlutterFragmentActivity
│           └── res/values/localytics.xml       # platform-side SDK config
└── README.md

---

How the app keys reach the native SDKs

Variable	Platform	Path
LOCALYTICS_IOS_APP_KEY	iOS	.env → tool/sync_env.dart → ios/Flutter/LocalyticsEnv.xcconfig → Info.plist → AppDelegate.swift
LOCALYTICS_ANDROID_APP_KEY	Android	.env → android/app/build.gradle.kts (resValue("string", "ll_app_key", …)) → consumed by the SDK from R.string.ll_app_key

This pattern keeps real keys out of source control entirely. The Android side also reads it at every Gradle configure, so changing .env only requires a rebuild — no script step.

---

Troubleshooting

"Localytics app key is not configured" banner shows on launch. The native SDK reported the placeholder key. Check that:

1. .env exists at the project root and has the correct variable names (LOCALYTICS_IOS_APP_KEY, LOCALYTICS_ANDROID_APP_KEY).
2. For iOS, you ran dart run tool/sync_env.dart after editing .env.
3. You rebuilt (flutter clean && flutter run) — the iOS key is injected at build time via xcconfig.

iOS build fails with Module 'localytics_flutter_sdk' not found. Swift Package Manager isn't enabled. Run flutter config --enable-swift-package-manager and retry. The plugin ships iOS support via SPM only.

Android build fails resolving com.localytics.androidx:library:7.1.0. The Localytics Maven repository isn't declared. android/build.gradle.kts includes maven { url = uri("https://maven.localytics.com/public") } — verify yours has the same.

Android crashes on launch with In-app messages can only appear in Activities subclassing FragmentActivity. MainActivity must extend FlutterFragmentActivity (not FlutterActivity). This sample already does that — see android/app/src/main/kotlin/.../MainActivity.kt.

iOS app launches but Dart calls throw MissingPluginException. Your AppDelegate.swift likely doesn't register plugins against the implicit Flutter engine spun up by the scene-based scaffold. Make sure it adopts FlutterImplicitEngineDelegate and calls GeneratedPluginRegistrant.register(with: engineBridge.pluginRegistry) from didInitializeImplicitFlutterEngine. This sample already does that — see ios/Runner/AppDelegate.swift.

---

Going further

• Plugin on pub.dev
• Plugin source on GitHub
• Localytics iOS integration guide
• Localytics Android integration guide

License

Licensed under the Apache License, Version 2.0 — same license as the underlying localytics_flutter_sdk plugin. Use of the Localytics platform and native SDKs is also subject to your Localytics customer agreement.