avafli_sdk 3.3.1
avafli_sdk: ^3.3.1 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 Engagement SDK for Flutter #
Drop-in sweepstakes, prizing, and gamification for your Flutter app
Overview #
Avafli lets you add daily-entry sweepstakes and prize experiences to your app in under 20 lines of code. The entire UI — branding, theming, copy, and prize configuration — is managed server-side from the Avafli dashboard. You integrate once; your marketing team controls the rest.
Key capabilities:
- Daily entry sweepstakes — Users earn entries every day they engage
- V2 auto-open experience — The bottom-drawer experience opens itself on the first app-open of each day and grants entries automatically (requires
Avafli.navigatorKeyon yourMaterialApp) - Daily streak + auto-claim — Entries climb a +10/day ladder; the drawer auto-opens once per day and claims that day's entries (or you open it yourself with
Avafli.present()— see Controlling when the drawer opens) - Email capture — The SDK captures an email through its own opt-in screen, with an UNCHECKED-by-default marketing-consent tick and a publisher-configurable age gate
- Cross-device verified adoption — When a typed email matches an existing account, the SDK confirms a 6-digit code before merging the streak across devices
- Soft email verification — A brand-new typed email shows a persistent, dismissible "Verify your email" chip; it never blocks play or the prize draw; confirming early means no code step if they win
- Winner claim flow — "WE HAVE A WINNER!" splash and an in-drawer prize-claim flow (name, shipping address incl. DC, claim number)
- Shared giveaway sponsor line — When a publisher opts into the shared giveaway (Avafli LLC as Sponsor of Record), a small "Sponsored by Avafli LLC" line renders under the prize; exclusive giveaways show nothing extra
- Visit mode — A never-resetting streak variant for low-frequency apps
- Push reminders — Drive re-engagement with daily nudges (FCM)
- Server-driven branding — Logo, prize image, and primary color update without app releases
- GDPR/CCPA compliant — Built-in consent flows, RTD opt-out via
optOut(), and a self-serve "Delete my data & stop participating" section inside the in-app Privacy Policy - Analytics forwarding — Route SDK events to your existing analytics stack
Quick Start #
import 'package:avafli_sdk/avafli_sdk.dart';
await Avafli.configure(AvafliConfiguration(
apiKey: 'YOUR_API_KEY', // debug builds: use your avafli_test_ sandbox key
bundleId: 'com.example.myapp',
autoOpen: AvafliAutoOpen.always, // or .returningUsersOnly / .never
user: AvafliUser(
id: 'user_123', // only id is required — pass whatever identity you have
firstName: 'Jane',
lastName: 'Doe',
email: 'jane@example.com', // include it when you have it — pre-fills & locks the capture form (consent stays explicit)
),
// Nobody signed in? use user: AvafliUser.guest
options: AvafliOptions(
logging: LoggingLevel.error, // LoggingLevel.debug while integrating
enablePushReminders: true, // streak reminders via YOUR Firebase project (upload the key in your dashboard)
),
));
// Attach the navigator key so the daily auto-open can present:
// MaterialApp(navigatorKey: Avafli.navigatorKey, ...)
// Splash screen that clears the nav stack? Call Avafli.holdAutoOpen() before
// configure, then Avafli.releaseAutoOpen() once your main screen mounts.
// Push reminders: forward FCM tokens with Avafli.registerPushToken(token).
That's the whole integration — the experience presents itself once per day.
Boot flows that clear the nav stack. If your app boots through a splash screen or auth gate that ends by clearing the navigation stack (
Get.offAll,Navigator.pushAndRemoveUntil, …), that navigation can destroy the drawer the instant it auto-opens. CallAvafli.holdAutoOpen()beforeconfigure()during boot, thenAvafli.releaseAutoOpen()once your main screen is mounted — it releases the hold and immediately opens if the day is due.
Identity — pass what you have, the SDK captures the rest #
Only id is required. Construct an AvafliUser from whatever identity data you
already hold — even just an id — and the SDK fills in the gaps: it captures the
email through its own screen, and the name at prize-claim time if the user wins.
There are three cases:
1. Signed-in user without an email (the common case, and Avafli's main value).
Pass the id plus whatever you have and OMIT email. The SDK shows its capture
screen and the user types their email — so you capture an address you didn't
have before:
user: AvafliUser(id: 'user_123', firstName: 'Jane', lastName: 'Doe') // no email
Even just AvafliUser(id: 'user_123') is valid — name is collected later at
prize-claim, only if they win.
2. Signed-in user with an email. Pass email too and it pre-fills and
locks the capture field (consent is still an explicit tick inside the flow).
email is a plain String:
user: AvafliUser(id: 'user_123', firstName: 'Jane', lastName: 'Doe', email: 'jane@example.com')
3. No signed-in user at all. Pass AvafliUser.guest:
await Avafli.configure(AvafliConfiguration(
apiKey: 'YOUR_API_KEY',
bundleId: 'com.example.myapp',
user: AvafliUser.guest,
));
The SDK mints a stable per-install guest id (avafli_guest_…) for attribution —
never fabricate placeholder ids yourself. The experience is fully functional
for guests. When the user signs in, call configure again with the real user:
attribution upgrades in place and the streak carries over automatically.
Installation #
Add the SDK to your pubspec.yaml:
dependencies:
avafli_sdk: ^3.3.1
Published on pub.dev. A git dependency on this repo also works if you need an unreleased revision.
Then run:
flutter pub get
Note: Contact AVAFLI to obtain an API key.
Configuration #
Initialize the SDK with your API key and user:
final config = AvafliConfiguration(
apiKey: 'avafli_live_xxxxxxxxxx',
bundleId: 'com.example.myapp',
autoOpen: AvafliAutoOpen.always, // or .returningUsersOnly / .never
user: AvafliUser(
id: 'user_abc123',
firstName: 'Jane',
lastName: 'Doe',
phone: '+15551234567', // optional
),
options: AvafliOptions(
logging: LoggingLevel.debug,
enablePushReminders: true,
analyticsAdapter: myAdapter, // optional
),
);
final success = await Avafli.configure(config);
AvafliConfiguration #
| Parameter | Type | Required | Description |
|---|---|---|---|
apiKey |
String |
✅ | Your Avafli API key from the dashboard |
bundleId |
String |
✅ | App bundle ID (e.g., com.example.myapp) |
user |
AvafliUser |
✅ | The authenticated user |
options |
AvafliOptions? |
— | Optional behavior toggles |
autoOpen |
AvafliAutoOpen |
— | .always (default), .returningUsersOnly, or .never — see Controlling when the drawer opens |
AvafliUser #
| Parameter | Type | Required | Description |
|---|---|---|---|
id |
String |
✅ | Unique, stable user identifier (the only required field) |
firstName |
String |
— | User's first name; captured at prize-claim if omitted |
lastName |
String |
— | User's last name; captured at prize-claim if omitted |
phone |
String? |
— | Phone number in E.164 format |
email |
String? |
— | If passed, pre-fills and locks the capture field; if omitted, the SDK captures it |
Email: Omit it and the SDK captures an address through its own opt-in screen (the common case). Pass it and that address pre-fills and locks — consent is still an explicit tick inside the flow. See the three identity cases above.
Test in Development: Your Sandbox Key #
Your publisher dashboard shows two API keys:
| Key | Use it in |
|---|---|
avafli_live_… |
Release builds — your real giveaway |
avafli_test_… |
Debug/dev builds and CI — an isolated sandbox |
The sandbox key hits the same production backend with identical behavior — registration, streaks, entries, the full experience — but every user and entry lands in a separate sandbox tenant with its own always-active test giveaway. That means:
- Your developers and testers 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 automatically.
Swap keys per build configuration and nothing else about your integration changes.
The Experience Presents Itself #
By default the Avafli experience is SDK-driven. The V2 bottom-drawer experience presents itself automatically at most once per calendar day (first app-open of the day) when Avafli.navigatorKey is attached to your MaterialApp. Auto-open respects the server-side kill switch (sdkConfig.experience.autoOpenEnabled), an unregistered-impression cap (default 3 impressions until the user confirms their email), and the RTD opt-out — a user who deleted their data sees nothing for 24 hours, after which they may join again as a new participant (see Account deletion in your app). Want to pick the moment yourself? See Controlling when the drawer opens.
Entries are claimed automatically when the drawer opens, and the celebration is the first thing the user sees: the dashboard opens with today's grant already showing — the day tile checks off with a confetti burst, the total counts up and pops, and the bar leads with a "YOU'RE ON A ROLL!" toast before settling into the come-back message. There is no button to tap to collect entries; the pill just reads GOT IT and closes. Brand-new users first submit their email, then land straight on the same celebrating dashboard — the toast just reads "YOU'RE IN!" on Day 1.
If your app boots through a splash/auth flow that clears the navigation stack, guard the auto-open with Avafli.holdAutoOpen() / Avafli.releaseAutoOpen() (see Quick Start).
Controlling when the drawer opens #
The default is unchanged: with nothing set, the drawer auto-opens once per day exactly as before. Whatever you choose below, device registration and analytics (the DAU/MAU heartbeat) still happen on Avafli.configure() — only the presentation is affected.
AvafliConfiguration.autoOpen takes one of three AvafliAutoOpen modes:
| Mode | Behavior |
|---|---|
AvafliAutoOpen.always (default) |
Auto-open once per calendar day when eligible — today's behavior. |
AvafliAutoOpen.returningUsersOnly |
Skip the auto-open for the session in which the device registered for the first time (isNewUser), so it never pops over your first-run onboarding. Every later launch auto-opens as normal. |
AvafliAutoOpen.never |
The SDK never auto-opens; you call Avafli.present(). |
Your dashboard can also set a server-side mode (experience.autoOpenMode); the SDK applies the more restrictive of the server's and your app's setting, and the server kill switch (autoOpenEnabled: false) always wins.
Avafli.present()— opens the drawer on demand (from a button, a screen, after onboarding). Same guards as the auto-open (configured, not opted out, publisher not suspended, an active giveaway, not already open — each resolvesfalserather than throwing), waits for a registration still in flight, ignores the once-a-day mark and the unregistered impression cap, never counts an impression, and on close writes the once-a-day mark so an auto-open later that day won't double-pop. Resolvestrueonce the drawer has been shown and closed.Avafli.holdAutoOpen()/Avafli.releaseAutoOpen()— pause and resume the once-a-day auto-open around a boot flow (nothing is burned while held;present()still works).releaseAutoOpen()immediately re-runs the eligibility check with the effective mode.
Show the drawer after onboarding:
await Avafli.configure(AvafliConfiguration(
apiKey: 'YOUR_API_KEY',
bundleId: 'com.example.myapp',
user: AvafliUser(id: 'user_123'),
// Never pop over onboarding; we decide when. (returningUsersOnly skips
// only the very first session and auto-opens from the next launch on.)
autoOpen: AvafliAutoOpen.never,
));
// ... later, once your onboarding flow completes:
final shown = await Avafli.present(); // false if no giveaway is live etc.
Email Capture & Verification #
Email is captured inside the SDK's own opt-in screen (see the identity section above). The screen shows a publisher-configurable age gate — an affirmative tick that gates the CTA — and a marketing-consent checkbox that is unchecked by default and never gates entry (declining it costs neither the entry nor, if drawn, winner contact).
Two verification paths run from that screen:
- Cross-device verified adoption. When the typed email matches an existing Avafli account (from another device or install), the SDK asks for a 6-digit code emailed to that address before the two identities are merged — so a streak follows the person across devices without letting anyone attach to someone else's record.
- Soft email verification (2.7.0+). A brand-new, never-before-seen typed email surfaces a persistent, dismissible "Verify your email" chip on the dashboard. It never blocks play or the prize draw — every active account is eligible. Confirming early just means the person skips the code step if they win.
Winner Experience #
When one of your users is drawn as a giveaway winner, the drawer automatically opens on a winner splash instead of the dashboard, then walks them through a prize-claim form (name, shipping address) and a confirmation with their claim number. This requires no integration work — the flow appears only for the drawn winner and disappears once their claim is submitted.
Prize claims (3.2.0+). Before the claim form opens, a winner enters a 6-digit code emailed to the address their account registered with — proof that they control that inbox. People who proved it earlier skip the step. The state lives on the server, so a winner who closes the drawer, restarts the app or switches device picks up exactly where they left off. Nothing for the host app to do.
A winner can always get back to an unfinished claim: while a claim is pending the drawer re-opens on every app launch, and on a return to the foreground at most once every 30 minutes — regardless of the once-a-day rule, the unregistered-impression cap and returningUsersOnly. holdAutoOpen(), the opt-out, the kill switch and autoOpen: AvafliAutoOpen.never still apply; on never, call Avafli.present() and it opens on the winner splash. This holds when no giveaway is active, too — the usual case, since a giveaway has ended by the time its winner is drawn: present() resolves true for a winner even though it resolves false for everyone else.
Shared giveaways: sponsor disclosure (3.3.0+). A publisher can opt into the shared giveaway — one shared prize pool across many Avafli apps, with Avafli LLC as Sponsor of Record. The served Giveaway then carries scope: "network" and a short sponsorDisclosure string (for example "Sponsored by Avafli LLC"; isNetworkGiveaway is true), and so does the winner's PrizeClaimBlock. The SDK shows that line, small and muted, directly under the prize wherever the prize is presented: the Day-1 email-capture strip, the dashboard prize card and the winner splash. The disclosure is legally required and cannot be turned off. For an exclusive (publisher-sponsored) giveaway both fields are absent and nothing changes — the drawer looks exactly as it did in 3.2.2. Nothing for the host app to do.
Resilience to a busy backend #
The SDK tells apart a backend answer from the platform refusing to take the request. When a traffic spike outruns the warm server instances, the platform turns the overflow away at once with an HTTP 429 or 5xx and a plain-text or HTML body (no callable error); fresh instances arrive within seconds. From 3.2.1 the SDK retries exactly those responses on its own — up to four times on a jittered backoff (1 s, 2 s, 4 s, 8 s base, about 15 s worst case; a Retry-After header is honoured up to 10 s) — and only surfaces AvafliError.serverError once that is exhausted. Retrying is safe: entries dedup per day on the server and reads are pure. A real backend answer (a callable error: rate limit, cooldown, geo, consent, already-claimed) is never retried and is surfaced as-is. Nothing for the host app to do.
Push Notifications #
Drive re-engagement with daily reminders. Publishers forward their FCM token to Avafli:
1. Setup Firebase Cloud Messaging #
Follow the Firebase setup guide for Flutter.
2. Forward FCM Token #
import 'package:firebase_messaging/firebase_messaging.dart';
// Get the FCM token and forward it to Avafli
final fcmToken = await FirebaseMessaging.instance.getToken();
if (fcmToken != null) {
await AvafliPushNotificationManager.instance.didReceiveRegistrationToken(fcmToken);
}
// Listen for token refreshes
FirebaseMessaging.instance.onTokenRefresh.listen((token) {
AvafliPushNotificationManager.instance.didReceiveRegistrationToken(token);
});
Or the one-line equivalent:
FirebaseMessaging.instance.onTokenRefresh.listen(Avafli.registerPushToken);
3. Upload FCM Service Account Key #
Upload your FCM service account key via the Avafli Dashboard to enable push notifications.
4. Enable Push Reminders #
Set enablePushReminders: true in AvafliOptions during configuration, then call
Avafli.registerForPushNotifications() after configure(). It is a no-op when
enablePushReminders is false.
await Avafli.registerForPushNotifications();
Customization #
The V2 experience is hardcoded to the Avafli design; publishers customize exactly three things through the Avafli Dashboard:
- Logo — Shown in the drawer header
- Prize image — Art for the dashboard prize card
- Primary color — Accent for CTAs, streak tiles, and highlights
Plus prize configuration (active giveaways, the entry ladder) and push reminder schedules.
Changes apply instantly across all app installations without requiring an app update.
Analytics #
Forward Avafli events to your existing analytics stack:
class MyAnalyticsAdapter implements AnalyticsAdapter {
@override
void track(String eventName, [Map<String, dynamic>? parameters]) {
// Forward to Segment, Amplitude, Mixpanel, etc.
analytics.track(eventName, parameters);
}
@override
void setUserProperty(String name, String value) {
analytics.setUserProperty(name, value);
}
@override
void identify(String userId) {
analytics.identify(userId);
}
}
// Pass during configuration
await Avafli.configure(AvafliConfiguration(
apiKey: 'YOUR_API_KEY',
bundleId: 'com.example.myapp',
user: AvafliUser(id: 'user_123'),
options: AvafliOptions(
analyticsAdapter: MyAnalyticsAdapter(),
),
));
Events emitted by the SDK:
avafli_sdk_configured— SDK configured successfullyavafli_experience_presented— User opened the Avafli experienceavafli_daily_entry_claimed— Daily entries awarded (auto-claimed on open). Params:day,entries.avafli_experience_dismissed— User closed the Avafli experience without a new claim
Account deletion in your app #
If your app has its own delete-account flow, call optOut() from it so the
user's Avafli data is erased along with their account. Users can also delete
their data themselves at any time from the Privacy Policy screen inside the
experience — no integration required.
// From your delete-account flow
await Avafli.optOut();
The erasure is identity-wide (one call covers all of the person's devices) and includes prize-claim records. Entries and streaks are forfeited and cannot be restored. De-identified entry records are retained as the legally required evidence that drawings were fair (GDPR Art. 17(3)): the person is erased, the proof is kept.
Delete my data — 24-hour rejoin. For 24 hours after a deletion, that email
and that device cannot register and the experience stays silent (present()
resolves false). After 24 hours the SDK clears what is left of the old
session on the next configure() or app-foreground and registers the device
again: the person joins as a brand-new participant, with no connection to the
old profile, and sees the normal email-capture flow. Nothing for the host app
to do.
API Reference #
Core Methods #
| Method | Returns | Description |
|---|---|---|
Avafli.configure(config) |
Future<bool> |
Initialize the SDK with user and settings |
Avafli.navigatorKey |
GlobalKey<NavigatorState> |
Attach to your MaterialApp so the experience can open (required) |
Avafli.present() |
Future<bool> |
Open the drawer on demand (pair with autoOpen: AvafliAutoOpen.never / returningUsersOnly) |
Avafli.holdAutoOpen() |
void |
Pause the once-a-day auto-open during a boot flow that clears the nav stack |
Avafli.releaseAutoOpen() |
Future<void> |
Release a holdAutoOpen() and open immediately if the day is due |
Avafli.optOut() |
Future<void> |
RTD opt-out — erase the person's data; they may rejoin as a new participant after 24 hours |
Push Notifications #
| Method | Returns | Description |
|---|---|---|
Avafli.registerForPushNotifications() |
Future<void> |
Enable streak reminders; no-op when enablePushReminders is false |
Avafli.registerPushToken(token) |
Future<void> |
Forward an FCM token to Avafli (one-line onTokenRefresh listener) |
AvafliPushNotificationManager.instance.didReceiveRegistrationToken(token) |
Future<void> |
Forward FCM token to Avafli |
For detailed API documentation, see the Avafli Docs.
Links #
- Dashboard: https://sdk.avafli.com/dashboard
- Documentation: https://sdk.avafli.com/flutter
- Support: info@avafli.com
© 2026 Avafli. All Rights Reserved.