avafli_sdk 3.3.3
avafli_sdk: ^3.3.3 copied to clipboard
Avafli Engagement SDK for Flutter — add daily-streak sweepstakes and prize experiences to your app with a few lines of code.
Avafli SDK for Flutter #
Drop-in daily-streak sweepstakes for your Flutter app. One configure() call and one navigator key; the SDK presents its own bottom drawer, captures the email, grants the day's entries, and runs the winner's prize claim. Branding, prize, ladder and copy are managed from your Avafli dashboard — no app release needed to change them.
- Requirements
- Install
- Configure
- What the user sees
- Controlling presentation
- Push reminders
- Testing checklist
- API reference
Requirements #
| Minimum | |
|---|---|
| Flutter / Dart | Flutter 3.24, Dart 3.5 |
| iOS | 13.0 (floor of the bundled webview_flutter, image_picker and url_launcher plugins) |
| Android | minSdk 24 (floor of the bundled flutter_secure_storage, webview_flutter and shared_preferences plugins) |
| App shell | A MaterialApp (or GetMaterialApp / MaterialApp.router) whose root navigator key the SDK can use — see Configure |
| API key | From your Avafli dashboard: avafli_live_… for release builds, avafli_test_… for everything else. No account yet? Start at sdk.avafli.com/pricing. |
Platform setup in your host app (both are already in example/):
- iOS
Info.plist— the prize-claim photo step usesimage_picker, so addNSCameraUsageDescriptionandNSPhotoLibraryUsageDescription(iOS requires them for any binary that links the picker). - Android
AndroidManifest.xml—<uses-permission android:name="android.permission.INTERNET"/>in your main manifest (Flutter's template only grants it in the debug/profile manifests).
The SDK ships its own fonts, icons and images; nothing else to add to pubspec.yaml.
Install #
dependencies:
avafli_sdk: ^3.3.3
flutter pub get
import 'package:avafli_sdk/avafli_sdk.dart';
A git dependency on AVAFLI/avafli_flutter_sdk also works if you need an unreleased revision.
Configure #
This is the whole integration. Copy it as-is: main(), Avafli.configure(...), and a MaterialApp that carries Avafli.navigatorKey.
import 'package:avafli_sdk/avafli_sdk.dart';
import 'package:flutter/foundation.dart' show kReleaseMode;
import 'package:flutter/material.dart';
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
// Mount the app FIRST so the navigator below exists by the time the SDK
// wants to open — then configure. (Configuring from your root widget's
// initState works just as well.)
runApp(const MyApp());
await Avafli.configure(AvafliConfiguration(
// Release builds hit your real giveaway; every other build hits your
// isolated sandbox — same backend, same behaviour, never your real draw.
apiKey: kReleaseMode
? 'avafli_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
: 'avafli_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
bundleId: 'com.example.myapp', // exactly as registered in your dashboard
user: AvafliUser(id: 'user_123'), // your stable user id — or AvafliUser.guest
options: AvafliOptions(
logging: kReleaseMode ? LoggingLevel.error : LoggingLevel.debug,
),
));
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
return MaterialApp(
// REQUIRED. The drawer is pushed through this navigator. Without it the
// SDK logs "Avafli.navigatorKey not attached" and never appears.
navigatorKey: Avafli.navigatorKey,
home: const HomeScreen(),
);
}
}
class HomeScreen extends StatelessWidget {
const HomeScreen({super.key});
@override
Widget build(BuildContext context) {
return const Scaffold(body: Center(child: Text('Your app')));
}
}
From here the SDK registers the device (every launch, every mode — this is the DAU/MAU heartbeat) and opens the drawer at most once per calendar day on the first app-open of the day. configure() resolves true on success and false (after logging) if initialisation threw; it never throws.
Pass the identity you have #
Only id is required. The SDK captures the email on its own screen and the name at prize-claim time.
// Signed-in user, no email on file (the common case — the SDK captures one):
user: AvafliUser(id: 'user_123', firstName: 'Jane', lastName: 'Doe')
// Signed-in user with an email: the capture field is pre-filled and LOCKED
// (consent is still an explicit tick inside the flow):
user: AvafliUser(id: 'user_123', email: 'jane@example.com')
// Nobody signed in: the SDK mints a stable per-install guest id
// (`avafli_guest_…`). Call configure() again with the real user after sign-in
// and attribution upgrades in place; the streak is device-anchored and stays.
user: AvafliUser.guest
firstName / lastName must match ^[a-zA-Z '-]{1,50}$ and phone must normalise to a 10-digit US number — anything else is dropped silently (they are optional).
Your app already has a navigator key #
Avafli.navigatorKey is an assignable static. Hand it your existing root key before configure() instead of changing your MaterialApp:
final rootNavigatorKey = GlobalKey<NavigatorState>();
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
Avafli.navigatorKey = rootNavigatorKey; // before configure()
runApp(MaterialApp(navigatorKey: rootNavigatorKey, home: const HomeScreen()));
await Avafli.configure(/* ... */);
}
The SDK pushes with rootNavigator: true, so the key must be the root navigator's — a nested navigator (a tab shell, a ShellRoute) will not do.
GetX, GoRouter, auto_route and splash screens #
Give the router the SDK's key as its root navigator key (or assign your own root key to Avafli.navigatorKey as above):
// GetX
GetMaterialApp(navigatorKey: Avafli.navigatorKey, home: const SplashScreen());
// GoRouter — the key goes on the router, not on MaterialApp.router
final router = GoRouter(navigatorKey: Avafli.navigatorKey, routes: [/* ... */]);
MaterialApp.router(routerConfig: router);
// auto_route — construct your generated router with the SDK's key
final appRouter = AppRouter(navigatorKey: Avafli.navigatorKey);
MaterialApp.router(routerConfig: appRouter.config());
If your boot flow clears the navigation stack (Get.offAll, context.go from a splash, Navigator.pushAndRemoveUntil, an auth gate), that navigation can destroy the drawer the instant it auto-opens. The SDK detects a drawer removed within 5 seconds without a user tap, refunds the day and retries twice — but the right fix is to tell it to wait:
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
Avafli.holdAutoOpen(); // BEFORE configure: nothing is burned while held
runApp(const MyApp());
await Avafli.configure(/* ... */);
}
// In the screen your boot flow lands on (after Get.offAll / go('/home')):
class HomeScreen extends StatefulWidget { /* ... */ }
class _HomeScreenState extends State<HomeScreen> {
@override
void initState() {
super.initState();
// Releases the hold and opens right away if today's drawer is due.
WidgetsBinding.instance.addPostFrameCallback((_) => Avafli.releaseAutoOpen());
}
// ...
}
releaseAutoOpen() is safe to call repeatedly and before configure(). Avafli.present() ignores the hold.
Sandbox key vs live key #
Your dashboard shows two keys. Both hit the same production backend with identical behaviour — registration, streaks, entries, the full drawer — but avafli_test_… lands every device and entry in a separate sandbox tenant with its own always-active test giveaway:
- Developers, testers and CI can never enter (or win) your real giveaway.
- Sandbox usage never counts toward your MAU or your bill.
- Your registered bundle IDs work with both keys.
Swap the key per build configuration (the kReleaseMode ternary above) and nothing else changes. Keys minted before the Avafli rename carry an older prefix and remain valid.
What the user sees #
Everything below is built into the drawer. There is no host-app code for any of it.
Day 1 — email capture. The drawer opens on "VISIT. EARN. WIN." with the prize, an email field, an age-gate tick (the publisher's configured minimum age, default 18; the tick gates the button) and a marketing-consent checkbox that is unchecked by default and never gates entry. Official Rules and the Privacy Policy are tappable in the fine print and open in an in-app webview. Submitting claims Day 1 and lands on the dashboard celebrating — the day tile checks off with confetti, the total counts up, the bar reads "YOU'RE IN!", the pill reads GOT IT. Nothing to tap to collect entries.
- If the typed email already belongs to an existing Avafli account (another device or app), the SDK asks for a 6-digit code emailed to that address before linking the streak to this device.
- A never-before-seen email gets a dismissible "Verify your email" chip on the dashboard. It never blocks play or the draw; confirming early means no code step if they win.
- Until an email is on file, the auto-open shows at most 3 times (server-configurable
unregisteredImpressionCap), then stays quiet until the person registers or you callpresent().
Day 2 onward — auto-claim. The drawer opens once per day, claims that day's entries silently and celebrates ("YOU'RE ON A ROLL!"). Entries follow the giveaway's ladder from your dashboard; the built-in default is 10 → 30 → 60 → 130 → 240 → 300 → 500 for days 1–7, plus any milestone accelerators ("+25 EVERY DAY!" tiles). A missed day resets a daily streak to Day 1; a giveaway in visit mode counts visits and never resets. A claim that already happened on another device shows a short notice instead of a second grant. A claim that fails on the network is queued and retried the same day on resume / next launch (capped backoff, at most 5 attempts per session); the server dedups, so a retry can never double-grant.
Winner. When the person is drawn, the drawer opens on "WE HAVE A WINNER!" instead of the dashboard. CONTINUE goes to a 6-digit email-ownership code when the backend asks for one (people whose inbox is already proven skip it), then a 3-step claim form — about you, US shipping address (50 states + DC, with address autocomplete when the platform ships a Places key in sdkConfig), optional photo — a review screen with an optional likeness-consent tick, and a confirmation with their claim number and a share step. The claim is open for the giveaway's claim window: 3 days (72 hours) from the winner notification by default, configurable per giveaway from 1 to 60 days by Avafli; once it has passed the backend refuses the claim and the drawer simply closes. While a claim is pending the drawer re-opens on every cold start and at most every 30 minutes on foreground, regardless of the once-a-day rule — see Controlling presentation.
Shared giveaway. If you opt your app into the shared giveaway (one prize pool across many Avafli apps, Avafli LLC as Sponsor of Record), the served Giveaway carries scope: "network" and a sponsorDisclosure ("Sponsored by Avafli LLC") that renders, small and muted, under the prize on the capture strip, the prize card and the winner splash. It is a legal disclosure and cannot be hidden. Exclusive giveaways show nothing extra.
Branding. The drawer design is fixed. From the dashboard you set the logo, the prize image and the primary colour (CTAs, tiles, highlights); the age-gate sentence and marketing-consent line are also server copy. Changes apply on the next open without an app update.
Delete my data. Users delete their Avafli data themselves from the Privacy Policy screen inside the experience ("Delete my data & stop participating"): the erasure is identity-wide, the drawer stays silent on that device for 24 hours, and after that they may join again as a brand-new participant. There is nothing for the host app to do, and no host-app call for it — only the person can erase their own data.
Busy backend. An HTTP 429/5xx that is the platform refusing the request (no structured error — instances warming up) is retried automatically four times on a jittered backoff (≈15 s worst case, Retry-After honoured up to 10 s) before AvafliError.serverError surfaces. Real backend answers (rate limit, cooldown, geo, consent, already claimed) are never retried.
Controlling presentation #
Registration always runs on configure(); the modes below only change when the drawer opens.
AvafliConfiguration.autoOpen |
Behaviour |
|---|---|
AvafliAutoOpen.always (default) |
Opens once per calendar day on the first app-open of the day, and again on a foreground that crosses midnight. |
AvafliAutoOpen.returningUsersOnly |
Skips the auto-open in the one session where the device registered for the first time (so it never pops over first-run onboarding). Every later launch auto-opens. |
AvafliAutoOpen.never |
Never auto-opens. You call Avafli.present(). |
Your dashboard can set a server-side mode too (experience.autoOpenMode); the more restrictive of the two applies, and the server kill switch (experience.autoOpenEnabled: false) always wins.
await Avafli.configure(AvafliConfiguration(
apiKey: 'avafli_test_…',
bundleId: 'com.example.myapp',
user: AvafliUser(id: 'user_123'),
autoOpen: AvafliAutoOpen.never, // we choose the moment
));
// Later — after onboarding, or from a "Daily prize" button:
final shown = await Avafli.present(); // true once the drawer was shown and closed
Avafli.present() waits for an in-flight registration, then opens the drawer if the SDK is configured, the person is not opted out, the publisher is not suspended, a giveaway is live (or a prize claim is pending) and the drawer is not already up — each failing guard resolves false with an info log, never a throw. It ignores the once-a-day mark, the impression cap and holdAutoOpen(), counts no impression, and on close writes the once-a-day mark so an auto-open later that day does not double-pop.
Avafli.holdAutoOpen() / Avafli.releaseAutoOpen() pause and resume the auto-open around a boot flow — see GetX, GoRouter, auto_route and splash screens.
Pending prize claim. A winner must always be able to get back to an unfinished claim, so while one is pending the auto-open bypasses the once-a-day mark, the impression cap and returningUsersOnly: it opens on every cold start and on foreground at most every 30 minutes. The hold, the opt-out, a suspended publisher, the kill switch and mode never still apply — on never, present() opens straight onto the winner splash, and resolves true for a winner even when no giveaway is active (the usual case, since the giveaway has ended by the time its winner is drawn).
Avafli.isAvailable is false until configure() ran, or when the backend reported the publisher suspended / the key revoked (billing lapse) — the drawer stays silent and present() resolves false in that state.
Push reminders #
Streak reminders are sent through your Firebase project. The SDK never links Firebase itself; you forward the FCM token.
-
Set up Firebase Cloud Messaging for Flutter in your app.
-
Forward every token to Avafli:
import 'package:firebase_messaging/firebase_messaging.dart'; final token = await FirebaseMessaging.instance.getToken(); if (token != null) await Avafli.registerPushToken(token); FirebaseMessaging.instance.onTokenRefresh.listen(Avafli.registerPushToken);Avafli.registerPushTokenis a no-op untilconfigure()has run. If your token can arrive earlier, useAvafliPushNotificationManager.instance.didReceiveRegistrationToken(token)instead — it queues the token and sends it once the SDK is configured, and skips the network when the token is unchanged. -
Upload your FCM service-account key in the Avafli dashboard and set the reminder schedule there.
AvafliOptions.enablePushReminders defaults to true; set it to false to keep the SDK from registering tokens at all. Avafli.registerForPushNotifications() exists for source compatibility only — it writes a debug log and does nothing else; you do not need to call it.
Testing checklist #
Run every item with your avafli_test_… key and logging: LoggingLevel.debug.
- First launch — the drawer opens on email capture within a few seconds of
configure(). If the log saysAuto-present skipped: Avafli.navigatorKey not attached to a MaterialApp, the key is missing or on a nested navigator. - Submit an email — the dashboard celebrates "YOU'RE IN!" and the log shows
avafli_daily_entry_claimedwithday: 1. - Relaunch the same day — no second auto-open (
present()still opens it). To see the auto-open again today, delete the app's data or use the example app's reset button. - Next day (or the device clock moved forward a day, then a cold start) — the drawer auto-opens and claims Day 2.
- Splash / boot navigation — if you use
holdAutoOpen(), confirm the log readsAuto-present deferred: host is holding auto-openduring boot and the drawer appears over your home screen afterreleaseAutoOpen(). A log lineAuto-presented experience was removed by host navigation — retryingmeans the hold is missing or released too early. autoOpen: AvafliAutoOpen.never— nothing opens on its own;await Avafli.present()resolvestrue.- Delete my data — Privacy Policy → Delete my data: the drawer dismisses and stays silent; after 24 hours a relaunch shows email capture again.
- Push — after forwarding a token there is no
registerPushToken failed:line in the log (through the manager you also getPush token registered with backend). - Platform setup — iOS
Info.plisthas both usage strings; Android main manifest hasINTERNET; a release build uses theavafli_live_…key.
The example app (example/, flutter run) wires all of this up with a demo key and a "Reset demo state" button.
API reference #
Everything below is exported by package:avafli_sdk/avafli_sdk.dart. Members documented @internal in the source (markOptedOut, syncClaimedToday, recoverExpiredSession, …) are used by the drawer and are not for host apps.
Avafli #
| Member | Type | Description |
|---|---|---|
Avafli.configure(config) |
Future<bool> |
Initialise the SDK, register the device, then attempt the once-a-day auto-open. false (logged) if initialisation threw. |
Avafli.navigatorKey |
GlobalKey<NavigatorState> (assignable) |
The root navigator the drawer is pushed through. Attach to MaterialApp, or assign your own root key before configure(). |
Avafli.present() |
Future<bool> |
Open the drawer on demand. true once it was shown and closed; false for any failing guard (never throws). |
Avafli.holdAutoOpen() |
void |
Pause the auto-open during a boot flow. Nothing is burned while held. |
Avafli.releaseAutoOpen() |
Future<void> |
Release the hold and open at once if today's drawer is due. Safe before configure() and repeatedly. |
Avafli.isAvailable |
bool |
false before configure() or while the publisher is suspended / key revoked. |
Avafli.registerPushToken(token) |
Future<void> |
Forward an FCM token. No-op before configure() or for an empty token; failures are logged. |
Avafli.registerForPushNotifications() |
Future<void> |
Source-compatibility shim: logs at debug level, nothing else. Throws AvafliError.notConfigured before configure(). |
Avafli.sdkVersion |
String |
'3.3.3' — sent to the backend and in the User-Agent. |
Avafli.platformOS |
String |
'iOS', 'Android' or 'Web' at runtime. |
AvafliConfiguration #
| Parameter | Type | Default | Description |
|---|---|---|---|
apiKey |
String |
required | avafli_live_… or avafli_test_… from your dashboard |
bundleId |
String |
required | Must match a bundle ID registered in your dashboard |
user |
AvafliUser |
required | Your user, or AvafliUser.guest |
options |
AvafliOptions |
AvafliOptions() |
Logging, analytics, push |
autoOpen |
AvafliAutoOpen |
.always |
.always / .returningUsersOnly / .never |
environment |
AvafliEnvironment |
.production |
The only value; sandboxing is by key, not environment |
AvafliUser #
| Parameter | Type | Description |
|---|---|---|
id |
String |
Required. Your stable user id. AvafliUser.guest when nobody is signed in. |
firstName, lastName |
String |
Optional (''). Letters, spaces, apostrophes, hyphens, max 50; otherwise dropped. Collected at prize-claim if missing. |
phone |
String? |
Optional. Must normalise to 10 US digits; otherwise dropped. |
email |
String? |
Optional. Pre-fills and locks the capture field; consent is still ticked in the flow. A malformed value is ignored. |
AvafliOptions #
| Parameter | Type | Default | Description |
|---|---|---|---|
logging |
LoggingLevel |
.error |
.none, .error, .info, .debug |
analyticsAdapter |
AnalyticsAdapter? |
null |
Receives the events below |
enablePushReminders |
bool |
true |
false disables token registration |
AvafliAutoOpen #
always (default), returningUsersOnly, never. AvafliAutoOpen.mostRestrictive(a, b) and AvafliAutoOpen.fromWire(string) are the helpers the SDK uses to combine the server's mode with yours.
Errors #
AvafliException (implements Exception) wraps an AvafliError and carries serverMessage, displayMessage, details / reason (the backend's structured payload, e.g. claim_expired), transport (the request never completed), retryable / statusCode / retryAfter (an infrastructure 429/5xx). Only registerForPushNotifications() throws it to the host app; configure() and present() log and return false instead.
AvafliError: notConfigured, noUser, ineligibleToday, invalidApiKey, networkError, authenticationFailed, underage, invalidEmail, emailRequired, giveawayNotAvailable, geographyNotAllowed, serverError, serviceUnavailable (publisher suspended / key revoked), optedOut, unknown, invalidState, noPresentingViewController. Each has a message.
Analytics #
Implement AnalyticsAdapter (track, setUserProperty, identify) and pass it in AvafliOptions.analyticsAdapter:
class MyAnalyticsAdapter implements AnalyticsAdapter {
@override
void track(String eventName, [Map<String, dynamic>? parameters]) =>
analytics.track(eventName, parameters);
@override
void setUserProperty(String name, String value) =>
analytics.setUserProperty(name, value);
@override
void identify(String userId) => analytics.identify(userId);
}
Events the SDK emits in 3.3.1:
| Event | When | Parameters |
|---|---|---|
avafli_sdk_configured |
configure() ran |
— |
avafli_experience_presented |
the drawer opened (auto or present()) |
— |
avafli_experience_dismissed |
the drawer closed without a new claim | — |
avafli_daily_entry_claimed |
the day's entries were granted | day, entries; weekly_bonus, monthly_bonus, milestone_day, milestone_bonus when present; recovered_offline: true when a queued claim landed later |
avafli_email_verified |
the "Verify your email" code was confirmed | — |
avafli_winner_claim_shown |
the winner splash opened | giveaway_id |
avafli_prize_claim_submitted |
the claim form was submitted | giveaway_id, claim_number |
identify(userId) is called on configure() for a non-guest user. Events emitted while offline are buffered (last 100, persisted) and flushed on resume / next launch with original_timestamp and original_timestamp_ms added. The AvafliAnalyticsEvents constants that have no row above are reserved names that 3.3.1 does not emit.
Push #
AvafliPushNotificationManager.instance.didReceiveRegistrationToken(token) — forward an FCM token; queues it before configure(), skips an unchanged token. getCachedToken() / clearToken() read and clear the locally cached token.
Models #
Giveaway (with streakLadder, milestones, streakMode / isVisitMode, scope / sponsorDisclosure / isNetworkGiveaway, latestWinner, rulesUrl, prizeImageUrl), MilestoneConfig, GiveawayWinner, StreakConfig, GiveawayPeriod, AvafliSdkConfig (branding, experience, copy, ageGateEnabled, ageGateMinAge, …), StreakEngine / StreakState, DailyEntryGrant and AvafliBranding are exported so you can inspect what the server sent; the drawer renders from them and they are not host-app configuration. AvafliBranding.defaultBranding() and its preset factories are the SDK's fallback palette; server branding overrides it at runtime.
Links #
- Dashboard: sdk.avafli.com/dashboard
- Flutter docs: sdk.avafli.com/flutter
- Package: pub.dev/packages/avafli_sdk
- Source: github.com/AVAFLI/avafli_flutter_sdk
- Support: info@avafli.com
© 2026 Avafli. All Rights Reserved.