winr_flutter_sdk 2.9.5

WINR Flutter SDK — A sweepstakes and engagement SDK for Flutter apps. Add daily streaks and sweepstakes campaigns to your app with a few lines of code.

WINR Flutter SDK

Drop-in sweepstakes, prizing, and gamification for your Flutter app

---

Overview

WINR 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 WINR 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 WINR.navigatorKey on your MaterialApp)
• Daily streak + auto-claim — Entries climb a +10/day ladder; the drawer auto-opens once per day and claims that day's entries — there is no manual present API
• 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, only prize-draw eligibility
• Winner claim flow — "WE HAVE A WINNER!" splash and an in-drawer prize-claim flow (name, shipping address incl. DC, claim number)
• 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 an in-app "Privacy choices → delete my data"
• Analytics forwarding — Route SDK events to your existing analytics stack

Quick Start

import 'package:winr_flutter_sdk/winr_flutter_sdk.dart';

await WINR.configure(WINRConfiguration(
  apiKey: 'YOUR_API_KEY', // debug builds: use your winr_test_ sandbox key
  bundleId: 'com.example.myapp',
  user: WINRUser(
    id: 'user_123',             // only id is required — pass whatever identity you have
    firstName: 'Jane',
    lastName: 'Doe',
    email: '[e-mail]',  // include it when you have it — pre-fills & locks the capture form (consent stays explicit)
  ),
  // Nobody signed in? use user: WINRUser.guest
  options: WINROptions(
    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: WINR.navigatorKey, ...)
// Splash screen that clears the nav stack? Call WINR.holdAutoOpen() before
// configure, then WINR.releaseAutoOpen() once your main screen mounts.
// Push reminders: forward FCM tokens with WINR.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. Call WINR.holdAutoOpen() before configure() during boot, then WINR.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 a WINRUser 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 WINR'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: WINRUser(id: 'user_123', firstName: 'Jane', lastName: 'Doe')   // no email

Even just WINRUser(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: WINRUser(id: 'user_123', firstName: 'Jane', lastName: 'Doe', email: '[e-mail]')

3. No signed-in user at all. Pass WINRUser.guest:

await WINR.configure(WINRConfiguration(
  apiKey: 'winr_live_…',
  bundleId: 'com.example.myapp',
  user: WINRUser.guest,
));

The SDK mints a stable per-install guest id (winr_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:
  winr_flutter_sdk: ^2.9.5

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 user and environment settings:

final config = WINRConfiguration(
  apiKey: 'winr_live_xxxxxxxxxx',
  bundleId: 'com.example.myapp',
  environment: WINREnvironment.production,
  user: WINRUser(
    id: 'user_abc123',
    firstName: 'Jane',
    lastName: 'Doe',
    phone: '[phone]',  // optional
  ),
  options: WINROptions(
    logging: LoggingLevel.debug,
    enablePushReminders: true,
    analyticsAdapter: myAdapter,  // optional
  ),
);

final success = await WINR.configure(config);

WINRConfiguration

Parameter	Type	Required	Description
apiKey	String	✅	Your WINR API key from the dashboard
bundleId	String	✅	App bundle ID (e.g., com.example.myapp)
environment	WINREnvironment	—	.production (default)
user	WINRUser	✅	The authenticated user
options	WINROptions?	—	Optional behavior toggles

WINRUser

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
winr_live_…	Release builds — your real giveaway
winr_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

There is no manual launch API — the WINR experience is exclusively SDK-driven. The V2 bottom-drawer experience presents itself automatically at most once per calendar day (first app-open of the day) when WINR.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 — an opted-out user never sees the experience again.

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 WINR.holdAutoOpen() / WINR.releaseAutoOpen() (see Quick Start).

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 WINR 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 — the user keeps earning entries — it only affects prize-draw eligibility until the address is confirmed.

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.

Push Notifications

Drive re-engagement with daily reminders. Publishers forward their FCM token to WINR:

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 WINR
final fcmToken = await FirebaseMessaging.instance.getToken();
if (fcmToken != null) {
  await WINRPushNotificationManager.instance.didReceiveRegistrationToken(fcmToken);
}

// Listen for token refreshes
FirebaseMessaging.instance.onTokenRefresh.listen((token) {
  WINRPushNotificationManager.instance.didReceiveRegistrationToken(token);
});

Or the one-line equivalent:

FirebaseMessaging.instance.onTokenRefresh.listen(WINR.registerPushToken);

3. Upload FCM Service Account Key

Upload your FCM service account key via the WINR Dashboard to enable push notifications.

4. Enable Push Reminders

Set enablePushReminders: true in WINROptions during configuration, then call WINR.registerForPushNotifications() after configure(). It is a no-op when enablePushReminders is false.

await WINR.registerForPushNotifications();

Customization

The V2 experience is hardcoded to the WINR design; publishers customize exactly three things through the WINR 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 WINR 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);
  }
}

// Pass during configuration
await WINR.configure(WINRConfiguration(
  // ... other config
  options: WINROptions(
    analyticsAdapter: MyAnalyticsAdapter(),
  ),
));

Events emitted by the SDK:

• winr_sdk_configured — SDK configured successfully
• winr_experience_presented — User opened the WINR experience
• winr_daily_entry_claimed — Daily entries awarded (auto-claimed on open). Params: day, entries.
• winr_experience_dismissed — User closed the WINR experience without a new claim

GDPR / CCPA

Handle erasure requests with optOut():

await WINR.optOut();

This is the complete Right-to-be-Forgotten path. It removes the person's personal information everywhere it is held — including prize-claim records, which carry name, address and phone — links their devices together so one call covers all of them, and permanently silences the experience on the device so it survives a reinstall.

De-identified entry records are deliberately retained. They are the evidence that a drawing was fair and that a prize went to a real eligible person, which a sweepstakes operator must be able to show; GDPR Art. 17(3) exempts data needed for legal claims. The person is erased, the proof is kept.

Users can also self-serve without any code from you: the experience's Privacy choices → delete my data flow runs the same erasure as optOut().

API Reference

Core Methods

Method	Returns	Description
WINR.configure(config)	Future<bool>	Initialize the SDK with user and settings
WINR.navigatorKey	GlobalKey<NavigatorState>	Attach to your MaterialApp so the experience can auto-open (required)
WINR.holdAutoOpen()	void	Pause the once-a-day auto-open during a boot flow that clears the nav stack
WINR.releaseAutoOpen()	Future<void>	Release a holdAutoOpen() and open immediately if the day is due
WINR.optOut()	Future<void>	RTD opt-out — permanently silence the experience

Push Notifications

Method	Returns	Description
WINR.registerForPushNotifications()	Future<void>	Enable streak reminders; no-op when enablePushReminders is false
WINR.registerPushToken(token)	Future<void>	Forward an FCM token to WINR (one-line onTokenRefresh listener)
WINRPushNotificationManager.instance.didReceiveRegistrationToken(token)	Future<void>	Forward FCM token to WINR

For detailed API documentation, see the WINR Docs.

Links

• Dashboard: https://winrmedia.com/sdk/dashboard
• Documentation: https://winrmedia.com/sdk/flutter
• Support: [e-mail]

---

© 2026 Avafli. All Rights Reserved.