flutter_elevok_widget
Your Elevok rewards programme inside your Flutter app: points, campaigns, games, streaks, badges, levels, drops, leaderboards and referral, behind a launcher on every screen, signed in with your customers' accounts.
Everything customers see is set in Elevok Cockpit › Widget: change it there and the app follows within a minute, with no app release.
- Native launcher drawn from your Cockpit settings (style, shape, picture, size, place, badge); customers can drag it.
- Instant panel: loaded once when the app starts, kept alive, it slides up over the app.
- One session: your app signs the customer in; signing in or out in the panel reaches your app.
- Your buttons earn points (
ElevokAnimatedButton), and the panel can show where they are. - Light and dark, every language of your programme (Arabic right to left), Android back button, safe areas, offline retry, screen readers.
Install
dependencies:
flutter_elevok_widget: ^1.1.0
Requires Flutter 3.27+ (Dart 3.6+), iOS 13+, Android 5.0+ (API 21).
Android
Release builds need the Internet permission (Flutter adds it to debug builds only). Links the panel opens outside the
app (a campaign's page, a share, a store, phone, email) need these queries on Android 11+. In
android/app/src/main/AndroidManifest.xml:
<manifest ...>
<uses-permission android:name="android.permission.INTERNET" />
<queries>
<intent><action android:name="android.intent.action.VIEW" /><data android:scheme="https" /></intent>
<intent><action android:name="android.intent.action.DIAL" /><data android:scheme="tel" /></intent>
<intent><action android:name="android.intent.action.SENDTO" /><data android:scheme="mailto" /></intent>
</queries>
</manifest>
iOS
Nothing to add. Xcode 26+ builds need iOS 15 as your app's deployment target, and iOS 27 requires the UIScene lifecycle (see Flutter's UIScene migration).
Wrap your app
Once, at the root, around your MaterialApp (or CupertinoApp). Your store id is in Cockpit › Widget › Install.
import 'package:flutter_elevok_widget/flutter_elevok_widget.dart';
void main() => runApp(
ElevokWidget(
appID: 'YOUR_STORE_ID',
locale: const Locale('fr'), // the panel speaks the app's language
themeMode: ThemeMode.system, // and follows its theme
// partner sign-in: a guest wants to sign in
signInRedirection: (context) => Navigator.of(context).pushNamed('/sign-in'),
launcherInsets: const EdgeInsets.only(bottom: 64), // above your tab bar
child: MaterialApp(...),
),
);
| Option | What it does |
|---|---|
appID |
Your store id (required). |
child |
Your app (required). |
locale |
The app's language (fr, en, ar… also fr-fr, fr_FR). Used when your programme offers it. |
themeMode |
Light, dark or system: used when your widget's colours follow the site/app (Cockpit › Widget › Design). |
signInRedirection |
Partner sign-in: a guest asked to sign in; open your sign-in. The context is your app's navigator. |
onLocate |
"Show me the button" in the panel: open the screen that has that button (see below). |
launcherInsets |
Room the launcher keeps around it, on top of the safe areas (your bottom bar). |
showLauncher |
false: no launcher; open the panel from your own buttons. |
onEvent |
What happens in the panel (see Events). |
navigatorKey |
Your app's navigator key, if you have one (found by itself otherwise). |
Sign your customers in
How customers sign in is your store's choice (Cockpit › Loyalty › Programme › Sign-in), the same for your website and your app:
| Mode | Who signs the customer in | In your app |
|---|---|---|
| Store accounts | The panel (phone, email or username) | Nothing to do |
| Aggregator (e.g. a store on BONO) | The panel, with the aggregator's account | Nothing to do |
| Partner | Your app, with your own accounts | The steps below |
Inside an app the panel leaves out Google, Facebook and QR-code sign-in (they don't work in a web view).
Partner sign-in
Your server gets the customer's Elevok session (the store's secret key never goes in an app):
POST https://api.elevok.com/cauth/clogin
{ "client": "YOUR_STORE_ID", "publicKey": "…", "secretKey": "…" }
→ { "accessToken": "API_TOKEN" }
POST https://api.elevok.com/api/v1/players/login
Authorization: Bearer API_TOKEN
{ "identifier": "CUSTOMER_ID_IN_YOUR_SYSTEM", "email": "ann@example.com", "firstName": "Ann" }
→ { "data": { "accessToken": "CUSTOMER_TOKEN" } }
The first call of an identifier creates the customer (card, wallets, welcome bonus); later ones sign them in and update their profile. Your keys are in Cockpit › Integrations › Developers. Your app hands the session to the panel:
await ElevokFunctions.signIn(customerToken, player: 'CUSTOMER_ID_IN_YOUR_SYSTEM');
await ElevokFunctions.signOutWidget(); // on your sign-out
final signedIn = await ElevokFunctions.isUserLoggedIn();
A guest who taps "Sign in" in the panel lands on your sign-in (signInRedirection); after signIn, the panel opens
again, signed in, where they were. The session is kept on the phone until it expires or someone signs out.
Without a server (1.0.x apps): ElevokFunctions.signInWidget(publicKey:, secretKey:, appID:, identifier:, …) does
both steps from the app and answers a code: 0 wrong keys, 1 guest, 3 sign-in failed, 4 signed in. Prefer the server.
Guest mode
Cockpit › Widget › Content › Guest mode (on by default). Off, on a partner store, the widget is for members only:
no launcher until your app signs the customer in, and opening the panel as a guest runs signInRedirection instead.
ElevokController.instance.guestsHidden says when it is hidden.
Open the panel
ElevokFunctions.open(); // the home
ElevokFunctions.open(section: 'GAMES');
ElevokFunctions.openCampaign('CAMPAIGN_ID');
ElevokFunctions.openGame('GAME_CODE');
ElevokFunctions.openLeaderboard();
ElevokFunctions.close();
Sections: POINTS, CAMPAIGNS, GAMES, LEADERBOARD, STREAKS, BADGES, LEVELS, CHALLENGES, DROPS, SHOP,
DONATIONS, REFERRAL, CARD. Open the panel from a push notification or a deep link the same way.
Your buttons that earn points
A campaign can reward something done in your app (share a product, add to a wishlist, review…): add it in Cockpit › Widget › Site buttons, then wrap your button with its code:
ElevokAnimatedButton(
activityID: 'SHARE_PRODUCT_FACEBOOK',
// your own action (the share sheet…) stays in your code
child: IconButton(icon: const Icon(Icons.share), onPressed: null),
)
A tap opens the panel, which does the campaign and celebrates (a guest signs in first). While the customer can earn it, the button gently breathes.
The panel lists these campaigns with how often they repeat and a live countdown until they come back, and a
Show me the button: open the screen that has it with onLocate. There, the button scrolls into view and pulses.
ElevokWidget(
onLocate: (context, code) {
if (code == 'SHARE_PRODUCT_FACEBOOK') Navigator.of(context).pushNamed('/product');
},
...
)
ElevokController.instance.highlight('CODE') makes a button pulse from your own code.
Points from your app
After signInWidget (the store's keys), or call the same endpoints from your server (/api/v1/loyalty/push,
/deduct, /balance):
// a purchase, counted once per transactionId
await ElevokFunctions.pushAmountToUser(amount: 45.5, transactionId: 'ORDER-0001');
// paying with points
await ElevokFunctions.deductCoinsFromUser(amount: 10);
// points and level
final balance = await ElevokFunctions.checkUserWalletAndReputation();
The panel shows the new points at once.
Events
onEvent on ElevokWidget, or the stream ElevokFunctions.events:
| Event | Detail | When |
|---|---|---|
open, close |
– | The panel opened or closed |
login |
firstName, restored |
A customer is signed in (restored: a kept session at start) |
logout |
by: 'app' when your app asked |
The customer signed out (else in the panel: sign your app out too) |
signin |
reason |
A guest wants to sign in (partner stores) |
reward |
points, quest, code |
The customer earned something |
locate |
code |
"Show me the button" |
section |
the section | The customer opened a section |
unlink |
– | The aggregator's account was unlinked |
ElevokController.instance.state (signed in, points, first name, what they can do now) is a ValueListenable you can
show in your own header.
Launcher, theme and language
Set in Cockpit › Widget › Design, the same as on your website, with the phone size: button, live pill (the balance and what to earn next, taking turns), coin or edge tab; your logo, a picture (animated GIF too), an icon, the points or the customer's photo; its corner, distance and movement; a badge, and a pulse until the panel is opened once (none with reduced motion).
Colour mode "Follow the site" uses your themeMode; the language is your locale when your programme offers it.
Upgrading from 1.0.x
1.1.0 is a rewrite on the Elevok web widget (the same as on your website): the native screens and 25 dependencies are gone, and your code keeps compiling.
ElevokWidgetno longer builds its ownMaterialApp: pass your app aschild. ItsMaterialAppoptions (theme,routes,home…) are still accepted and ignored: set them on your own app.ElevokFunctionskeeps its methods and answers; they call the Elevok partner API.ElevokAnimatedButton(activityID:)also takes the button's code;elevokSocialMediaDatais ignored (the share comes from the campaign).- Partner stores: move the keys to your server and use
signIn(token).
Troubleshooting
| Check | Fix |
|---|---|
| No launcher | The widget is on (or you are a tester), something is live, "Show on phones" is on, showLauncher isn't false. Partner store with guest mode off: it shows once the customer is signed in. |
| The panel says it can't load | The phone is online; Android release builds need the Internet permission. |
| Partner: still a guest after signing in | signIn needs the customer's token (/api/v1/players/login), not the API token. |
| "Sign in" does nothing (partner) | Pass signInRedirection. |
| A button gives nothing | Its campaign is live, its code is right (Site buttons), and the customer can still earn it. |
| Links don't open on Android 11+ | Add the <queries> above. |
ElevokConfig.debug = true; before runApp logs what the app and the panel say (debug builds only).
Questions: support@elevok.com, with your store name, the app version and the debug log.
Libraries
- flutter_elevok_widget
- The Elevok rewards widget for Flutter apps.