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.

  • ElevokWidget no longer builds its own MaterialApp: pass your app as child. Its MaterialApp options (theme, routes, home…) are still accepted and ignored: set them on your own app.
  • ElevokFunctions keeps its methods and answers; they call the Elevok partner API.
  • ElevokAnimatedButton(activityID:) also takes the button's code; elevokSocialMediaData is 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.