rees46_sdk 1.6.2
rees46_sdk: ^1.6.2 copied to clipboard
Flutter plugin wrapping the REES46 native personalization SDKs for Android and iOS.
rees46_sdk #
Flutter plugin for the REES46 personalization platform — a thin bridge over the native Android and iOS SDKs. Storage, sessions, identity and push delivery happen natively; Dart only routes calls to the right shop instance.
Add the package #
flutter pub add rees46_sdk
Everything is exported from a single import:
import 'package:rees46_sdk/rees46_sdk.dart';
The native dependencies come with it — com.github.rees46:android-sdk from
JitPack and the iOS SDK through Swift Package
Manager or CocoaPods.
Android #
The plugin brings its own Gradle settings; the only value your app must agree on
is minSdk 24. Current Flutter versions already default to it, so a freshly
generated project needs no changes — set it only if you hardcoded something lower:
android {
defaultConfig {
minSdk = 24
}
}
Your app's Java version does not have to match the plugin's — compileOptions
and jvmTarget only govern the module they are declared in.
If your android/settings.gradle.kts centralizes repositories
(RepositoriesMode.FAIL_ON_PROJECT_REPOS / PREFER_SETTINGS), add JitPack there —
otherwise the native SDK cannot be resolved:
maven(url = "https://jitpack.io")
iOS #
The plugin declares the iOS 13.0 minimum itself and registers its own application
delegate — your AppDelegate stays untouched.
With Swift Package Manager — the default since Flutter 3.44, and on earlier
versions after flutter config --enable-swift-package-manager — there is nothing to
add: the plugin's package pulls the native SDK.
With CocoaPods (Swift Package Manager support turned off, or Flutter older than
3.44 without the setting above) add the native pod to ios/Podfile, inside
target 'Runner'. CocoaPods trunk goes read-only on 2 December 2026 and new SDK
versions are no longer published there, so the pod is taken straight from its
repository. The tag is the version the plugin requires — the REES46 dependency in
ios/rees46_sdk.podspec:
pod 'REES46', :git => 'https://github.com/rees46/ios-sdk.git', :tag => 'v3.37.1'
pod install then runs as part of flutter run. Update the tag together with the
plugin, and drop the line once Swift Package Manager support is on — the plugin's
package brings the SDK then, and keeping the pod would link it twice.
Initialize #
Initialize once, as early as possible — typically in main(), before runApp:
import 'package:flutter/widgets.dart';
import 'package:rees46_sdk/rees46_sdk.dart';
late final PersonalizationSdk sdk;
void main() {
WidgetsFlutterBinding.ensureInitialized();
sdk = REES46.initialize(
const REES46Config(shopId: 'YOUR_SHOP_ID'),
);
runApp(const MyApp());
}
REES46 is the entry point. REES46.initialize returns the handle
synchronously and starts native initialization in the background; calls issued
right after are queued natively until the session is ready, so the handle is
usable straight away. A broken setup surfaces as a PlatformException on the
first call you make with it (bad_args for an empty shopId, init_failed if
native init threw).
shopId is the only required field:
| Field | Default | Notes |
|---|---|---|
shopId |
— (required) | Your REES46 shop key |
apiDomain |
api.rees46.ru |
API host |
stream |
android / ios |
Traffic stream label; defaults to the current platform |
autoSendPushToken |
true |
Fetches and sends the push token during init; on iOS it also asks for notification permission. With false the app asks and sends the token itself |
needReInitialization |
false |
Forces a fresh session / device id |
enableAutoPopupPresentation |
true |
Shows server popups without an onPopup handler, see Popups |
Push delivery needs platform setup of its own — a Firebase config on Android, the Push Notifications capability on iOS. Without it initialization still succeeds; there is simply no token to send.
Keep one place that owns the handle, so no widget re-initializes:
class REES46Service {
static const _shopId = 'YOUR_SHOP_ID';
static PersonalizationSdk get sdk => REES46.isInitialized(_shopId)
? REES46.getInstance(_shopId)
: REES46.initialize(const REES46Config(shopId: _shopId));
}
Check that it worked #
final sid = await sdk.getSid(); // session id
final did = await sdk.getDid(); // device id issued by REES46
A non-empty did means the native SDK completed its handshake with the API.
Several shops in one app #
One app can run several shops at once — regional storefronts, super-app tenants.
Each gets its own native instance with isolated storage, session and did.
// Registered now, initialized on first use.
REES46.registerShops(const [
REES46Config(shopId: 'shop-a'),
REES46Config(shopId: 'shop-b'),
]); // pass eagerInit: true to initialize up front
final shopA = REES46.getInstance('shop-a');
Address instances explicitly once more than one is registered: getInstance()
without an id resolves only while exactly one shop is registered, and throws
AmbiguousShopException otherwise (UnknownShopIdException for an id that was
never registered).
Popups #
Popups made in the REES46 admin arrive with the responses to init and tracking
calls. The SDK shows them over the app's root navigator — the one MaterialApp,
CupertinoApp or MaterialApp.router builds — with nothing to set up. A popup that
finds no navigator within 10 seconds is dropped.
A popup sits in the centre, at the top or at the bottom as set in the admin, and fills the screen when no position is set. It waits out the delay set in the admin, and one shown within the last minute is not shown again. One popup is on screen at a time, whichever shop it came from. A popup is reported as shown once it is on screen.
The link button opens the link set for the platform, or the web one when there is none, with the system handler: a link into the app itself reaches it through the app's own deep-link handling. The push-subscription button opens the app's notification settings.
To see popups in your theme without making one in the admin, run the example app: it shows a test popup in each position.
To decide yourself — hold a popup back on a checkout screen, or draw it your way —
take popups with onPopup. The SDK then shows nothing:
sdk.onPopup = (InAppPopup popup) {
if (onCheckout) {
held = popup; // later: sdk.presentPopup(held!)
return;
}
showDialog(
context: context,
builder: (context) => Center(
child: SizedBox(
width: 370,
// Unbounded in height, the popup takes the height of its content.
child: SingleChildScrollView(
child: PersonalizationInAppPopup(
view: popup.imageUrl == null
? PersonalizationInAppPopupView.text
: PersonalizationInAppPopupView.image,
title: popup.title,
text: popup.text,
actionText: popup.actionText,
closeText: popup.closeText,
image: popup.imageUrl == null ? null : NetworkImage(popup.imageUrl!),
onAction: () {
Navigator.pop(context);
// Open popup.linkUrl, or the notification settings when
// popup.pushSubscribeText is set — with url_launcher, for instance.
},
onClose: () => Navigator.pop(context),
),
),
),
),
);
sdk.tracking.popupShown(popup.id); // the SDK reports only what it shows itself
};
sdk.presentPopup(popup) shows a popup the way the SDK does and reports it. With
enableAutoPopupPresentation: false and no onPopup, popups are not shown.
Several shops #
sdk.onPopup takes the popups of its own shop. To take the popups of every shop in
one place, set REES46.onPopup; popup.shopId tells which shop a popup came from:
REES46.onPopup = (InAppPopup popup) {
if (onCheckout) {
held = popup; // later: REES46.getInstance(held!.shopId).presentPopup(held!)
return;
}
REES46.getInstance(popup.shopId).presentPopup(popup);
};
A shop's own onPopup wins over REES46.onPopup. Show or report a popup through
the handle of its shop, as above: presentPopup and tracking.popupShown count it
for the shop they are called on.
UI theme #
The SDK's UI (popups, for now) is drawn in the REES46 design. Set your brand once, in
main before runApp; it applies in MaterialApp, CupertinoApp and without
either:
PersonalizationTheme.configure(
lightColors: PersonalizationColors.light.copyWith(
brandPrimary: const Color(0xFF7C3AED),
buttonPrimary: const Color(0xFF7C3AED),
),
darkColors: PersonalizationColors.dark.copyWith(
brandPrimary: const Color(0xFFA78BFA),
buttonPrimary: const Color(0xFFA78BFA),
),
fontFamily: const PersonalizationFontFamily(regular: 'Inter', emphasized: 'Inter'),
);
- Colours are set per scheme, font and radii once for both. Anything left out stays
as designed, so start from
PersonalizationColors.light/.darkand change only what you need. - Without
darkColorsthe dark scheme takes the brand colours (brand, primary button, brand line and text) fromlightColors, the rest from the design. - The font families must be declared in your
pubspec.yaml; passpackage:for fonts that come from another package.
Light or dark follows the app — its Material theme, else its Cupertino theme, else the device setting. To keep the SDK's UI one way whatever the app is in:
PersonalizationTheme.mode = ThemeMode.dark; // or ThemeMode.light; ThemeMode.system by default
Both settings can change at runtime; what is on screen is redrawn.
Track events #
Standard events live in the tracking namespace of the handle:
await sdk.tracking.productView('sku-1');
Each method returns a Future<void> that completes once the native SDK has the
API's answer; a rejected request throws a PlatformException (track_failed, or
track_event_failed / track_purchase_failed for custom events and orders).
Awaiting is optional — fire-and-forget from UI code is fine.
With several shops the namespace follows the instance:
await REES46.getInstance('shop-b').tracking.productView('sku-1');
Catalog #
// Product page opened.
await sdk.tracking.productView('sku-1');
// Category listing opened.
await sdk.tracking.categoryView('boots');
// The user searched. Pass `results` when your app runs the search itself and
// knows the ids it showed.
await sdk.tracking.search('winter boots', results: ['sku-1', 'sku-2']);
Cart #
// One product added.
await sdk.tracking.addToCart(
const TrackingItem(id: 'sku-1', quantity: 2, price: 49.9, fashionSize: '42'),
);
// The cart as it looks after a change — replaces the stored contents.
await sdk.tracking.syncCart(const [
TrackingItem(id: 'sku-1', quantity: 2, price: 49.9),
TrackingItem(id: 'sku-2'), // quantity defaults to 1
]);
// One product removed.
await sdk.tracking.removeFromCart('sku-1');
TrackingItem needs only an id; quantity defaults to 1, price and
fashionSize are optional.
Favorites #
await sdk.tracking.addToFavorites('sku-1');
await sdk.tracking.syncFavorites(const ['sku-1', 'sku-2']);
await sdk.tracking.removeFromFavorites('sku-1');
An empty list is how an emptied cart or wishlist is reported: items goes on
the wire as [] alongside full_cart / full_wish, which is what the native
SDKs send. Removing a single product is still removeFromCart /
removeFromFavorites.
Stories #
Only needed when you render stories yourself — the built-in stories view tracks its own views and taps.
await sdk.tracking.storyView(
storyId: '4321',
slideId: '2',
code: 'main_stories',
);
await sdk.tracking.storyClick(
storyId: '4321',
slideId: '2',
code: 'main_stories',
);
code is the stories block; omit it and the native SDK uses the block it loaded
last. A tracked story also becomes the source of the events that follow it — the
same rule as setSource.
Purchase #
await sdk.tracking.purchase(
orderId: 'order-1024',
orderPrice: 149.8,
items: const [
PurchaseLineItem(id: 'sku-1', amount: 2, price: 49.9, fashionSize: '42'),
PurchaseLineItem(id: 'sku-2', amount: 1, price: 50.0),
],
);
Those three are required; everything else is optional:
await sdk.tracking.purchase(
orderId: 'order-1024',
orderPrice: 149.8,
items: const [PurchaseLineItem(id: 'sku-1', amount: 1, price: 149.8)],
deliveryType: 'courier',
deliveryAddress: 'Tverskaya 1, Moscow',
paymentType: 'card',
isTaxFree: false,
isGiftPackage: true,
promocode: 'WINTER20',
orderCash: 100.0,
orderBonuses: 49.8,
orderDelivery: 5.0,
orderDiscount: 20.0,
channel: 'mobile_app',
custom: const {'store_id': 'msk-01'},
recommendedSource: const {'from': 'dynamic', 'code': 'main_page_block'},
stream: 'flutter',
segment: 'a',
);
custom goes on the wire under custom; keys that collide with the order's own
fields (order_id, items, event, shop_id, …) are rejected natively.
Custom event #
await sdk.tracking.custom(
'subscribed_to_newsletter',
category: 'account',
label: 'footer_form',
value: 1,
time: DateTime.now().millisecondsSinceEpoch ~/ 1000, // UNIX seconds
customFields: const {'plan': 'weekly'},
);
customFields is the free-form part: its entries are sent at the top level and
duplicated under payload. The SDK's own keys are reserved and rejected —
event, time, category, label, value, source, payload, from,
code, stream, shop_id, did, sid, seance, segment.
Attribution #
Events can carry the campaign the user arrived from — a bulk mobile push, a
chain. Both values come from the link that opened the app, which carries them as
recommended_by and recommended_code:
myshop://product/sku-1?recommended_by=bulk&recommended_code=jkIWdXSRfwVyK
A campaign brings the user in and then colours everything they do next, so store it once when you handle the link:
await sdk.tracking.setSource(
const TrackingSource(type: TrackingSourceType.bulk, code: 'jkIWdXSRfwVyK'),
);
// Carries recommended_by=bulk without being told to.
await sdk.tracking.productView('sku-1');
The stored source lives natively per shop, survives restarts, and is kept for 48 hours or until it is replaced.
To attribute a single event instead of everything that follows, pass source per
call — productView, addToCart and addToFavorites accept it:
await sdk.tracking.addToCart(
const TrackingItem(id: 'sku-1', quantity: 1),
source: const TrackingSource(type: TrackingSourceType.chain, code: 'welcome_2'),
);
A per-call source wins over the stored one, and an order is attributed by the
recommendedSource of the purchase call itself.
TrackingSourceType |
Wire value | Set by |
|---|---|---|
dynamicBlock |
dynamic |
Dynamic recommender block |
chain |
chain |
Recommendation chain |
bulk |
bulk |
Bulk mailing |
transactional |
transactional |
Transactional mailing |
instantSearch |
instant_search |
Search suggestions |
fullSearch |
full_search |
Full search results page |
stories |
stories |
Stories block |
webPushDigest |
web_push_digest |
Web push digest |
Example app #
A full demo — tracking, recommendations, search, catalog, loyalty, popups, push
and two shops side by side — lives in example/:
cd example
flutter run
Links #
License #
MIT — see LICENSE.