From c0301ef4e11aec40fb71902ebd847880ac3e29d9 Mon Sep 17 00:00:00 2001 From: andreykropotov Date: Tue, 27 Oct 2026 20:23:07 +0400 Subject: [PATCH 1/4] docs: example app and native SDK documentation links in README --- README.md | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 18c2a23..21d4e7c 100644 --- a/README.md +++ b/README.md @@ -60,9 +60,9 @@ 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 is -read-only since 2 December 2026, so the pod is taken straight from its repository. -The tag is the version the plugin requires — the `REES46` dependency in +`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`](ios/rees46_sdk.podspec): ```ruby @@ -157,7 +157,6 @@ 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 @@ -450,6 +449,22 @@ A per-call `source` wins over the stored one, and an order is attributed by the | `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/`](example): + +```bash +cd example +flutter run +``` + +## Links + +- [Android SDK documentation](https://rees46.ru/help/integration/cdp/sdk/kotlin.html) +- [iOS SDK documentation](https://rees46.ru/help/integration/cdp/sdk/swift.html) +- [Issue tracker](https://github.com/rees46/flutter-sdk/issues) + ## License MIT — see [LICENSE](LICENSE). From 8945d3afd89afdc0f372039fb0c593d790696ca8 Mon Sep 17 00:00:00 2001 From: andreykropotov Date: Tue, 27 Oct 2026 20:36:53 +0400 Subject: [PATCH 2/4] feat(popups): one handler for the popups of every shop, one popup on screen across shops --- lib/src/multi_instance/rees46.dart | 20 +++++++++-- lib/src/personalization_sdk.dart | 22 ++++++------ lib/src/popups/in_app_popup.dart | 14 ++++++-- lib/src/popups/popup_dispatcher.dart | 4 ++- lib/src/popups/popup_presenter.dart | 50 ++++++++++++++++++-------- test/popups/popup_presenter_test.dart | 51 +++++++++++++++++++++++++++ test/popups/popup_sdk_test.dart | 30 ++++++++++++++-- 7 files changed, 158 insertions(+), 33 deletions(-) diff --git a/lib/src/multi_instance/rees46.dart b/lib/src/multi_instance/rees46.dart index 09dcbce..a424142 100644 --- a/lib/src/multi_instance/rees46.dart +++ b/lib/src/multi_instance/rees46.dart @@ -1,6 +1,8 @@ import 'package:flutter/foundation.dart'; import '../personalization_sdk.dart'; +import '../popups/in_app_popup.dart'; +import '../popups/popup_presenter.dart'; import 'instance_resolver.dart'; import 'push_event.dart'; import 'rees46_config.dart'; @@ -115,6 +117,19 @@ class REES46 { PushEvent event, ) => _instance._handlePush(payload, event); + /// Takes the server popups of every shop instead of the SDK showing them — one + /// handler for an app with several shops. A shop's own + /// [PersonalizationSdk.onPopup] wins over it; otherwise it works the same. + /// + /// [InAppPopup.shopId] tells the shop a popup came for. Show or report it through + /// that shop's handle, so it counts for the right shop: + /// `REES46.getInstance(popup.shopId).presentPopup(popup)`. + static void Function(InAppPopup popup)? get onPopup => + PopupPresenter.sharedOnPopup; + + static set onPopup(void Function(InAppPopup popup)? handler) => + PopupPresenter.sharedOnPopup = handler; + /// Shops that are live (initialized), sorted. static List get liveShopIds => _instance._live.keys.toList()..sort(); @@ -213,12 +228,13 @@ class REES46 { static set debugFactory(REES46SdkFactory factory) => _instance._factory = factory; - /// Test-only: drops all live and pending registrations and restores the - /// default factory. + /// Test-only: drops all live and pending registrations and the popup handler, + /// and restores the default factory. @visibleForTesting static void reset() { _instance._live.clear(); _instance._pending.clear(); _instance._factory = _defaultFactory; + PopupPresenter.sharedOnPopup = null; } } diff --git a/lib/src/personalization_sdk.dart b/lib/src/personalization_sdk.dart index ccfad8a..43807e3 100644 --- a/lib/src/personalization_sdk.dart +++ b/lib/src/personalization_sdk.dart @@ -110,23 +110,25 @@ class PersonalizationSdk { return _initHandler.initialize(config); } - /// Takes the server popups (in-app messages) instead of the SDK showing them. + /// Takes the server popups (in-app messages) of this shop instead of the SDK showing + /// them. /// - /// Popups arrive with the responses to init and tracking calls. Without a handler the - /// SDK shows each over the app's root navigator, unless - /// `enableAutoPopupPresentation` is off. With one, the SDK shows nothing: the handler - /// gets every popup once its delay has passed and decides — draw it (for instance with - /// `PersonalizationInAppPopup`) and report it with `tracking.popupShown(popup.id)`, - /// let the SDK show it with [presentPopup], or drop it. A popup shown within the last - /// minute is not handed over again. Called on the main isolate. + /// Popups arrive with the responses to init and tracking calls. Without a handler — + /// this one or the app-wide `REES46.onPopup`, which this one wins over — the SDK + /// shows each over the app's root navigator, unless `enableAutoPopupPresentation` is + /// off. With one, the SDK shows nothing: the handler gets every popup once its delay + /// has passed and decides — draw it (for instance with `PersonalizationInAppPopup`) + /// and report it with `tracking.popupShown(popup.id)`, let the SDK show it with + /// [presentPopup], or drop it. A popup shown within the last minute is not handed + /// over again. Called on the main isolate. void Function(InAppPopup popup)? get onPopup => _popups.onPopup; set onPopup(void Function(InAppPopup popup)? handler) => _popups.onPopup = handler; /// Shows [popup] the way the SDK shows server popups — over the app's root navigator, - /// after any popup already on screen — and reports it as shown. For a popup taken with - /// [onPopup] and held back. Completes when the popup closes, or at once when it cannot + /// after any popup already on screen, from whichever shop — and reports it as shown + /// for this shop. For a popup taken with [onPopup] and held back. Completes when the popup closes, or at once when it cannot /// be shown. Future presentPopup(InAppPopup popup) => _popups.present(popup); diff --git a/lib/src/popups/in_app_popup.dart b/lib/src/popups/in_app_popup.dart index d51831f..0652347 100644 --- a/lib/src/popups/in_app_popup.dart +++ b/lib/src/popups/in_app_popup.dart @@ -13,11 +13,13 @@ enum InAppPopupPosition { } /// A server popup (in-app message). Popups arrive with the responses to init and tracking -/// calls; see `PersonalizationSdk.onPopup` for how they reach the screen. +/// calls; see `PersonalizationSdk.onPopup` and `REES46.onPopup` for how they reach the +/// screen. @immutable class InAppPopup { const InAppPopup({ required this.id, + this.shopId, this.position = InAppPopupPosition.unknown, this.delay = Duration.zero, this.title, @@ -30,10 +32,11 @@ class InAppPopup { this.json = const {}, }); - /// Parses the popup as the server sends it. [platform] picks the link for this platform - /// (`link_android` / `link_ios`), falling back to the web one. + /// Parses the popup as the server sends it for [shopId]. [platform] picks the link for + /// this platform (`link_android` / `link_ios`), falling back to the web one. factory InAppPopup.fromJson( Map json, { + String? shopId, TargetPlatform? platform, }) { final components = _map(json['components']); @@ -45,6 +48,7 @@ class InAppPopup { return InAppPopup( id: _int(json['id']) ?? 0, + shopId: shopId, position: switch (json['position']) { 'centered' => InAppPopupPosition.center, 'top' => InAppPopupPosition.top, @@ -66,6 +70,10 @@ class InAppPopup { } final int id; + + /// The shop the popup came for; `null` for one the app built itself. + final String? shopId; + final InAppPopupPosition position; /// How long after it arrives the shop wants the popup shown. diff --git a/lib/src/popups/popup_dispatcher.dart b/lib/src/popups/popup_dispatcher.dart index de171a5..f1978bb 100644 --- a/lib/src/popups/popup_dispatcher.dart +++ b/lib/src/popups/popup_dispatcher.dart @@ -38,7 +38,9 @@ class PopupDispatcher implements pigeon.PersonalizationPopupFlutterApi { return; } if (decoded is! Map) return; - presenter.receive(InAppPopup.fromJson(decoded.cast())); + presenter.receive( + InAppPopup.fromJson(decoded.cast(), shopId: shopId), + ); } /// Test-only: drops all registrations. diff --git a/lib/src/popups/popup_presenter.dart b/lib/src/popups/popup_presenter.dart index 24936d9..58a867c 100644 --- a/lib/src/popups/popup_presenter.dart +++ b/lib/src/popups/popup_presenter.dart @@ -17,6 +17,10 @@ import 'in_app_popup.dart'; /// server sends it again, one popup is on screen at a time, and a popup that never reached /// the screen is neither reported nor remembered. Unlike them it waits out the delay the /// shop set, as the React Native SDK does. +/// +/// The handles of several shops share the screen: one popup is on it at a time whichever +/// shop it came for, and [sharedOnPopup] takes the popups of every handle without an +/// [onPopup] of its own. class PopupPresenter { PopupPresenter({ required Future Function(int popupId) trackShown, @@ -42,6 +46,10 @@ class PopupPresenter { /// Takes every popup instead of the SDK showing it. void Function(InAppPopup popup)? onPopup; + /// Takes the popups of every handle with no [onPopup] of its own. The app's one + /// handler for all its shops, set through `REES46.onPopup`. + static void Function(InAppPopup popup)? sharedOnPopup; + /// A popup shown within this window is not shown again. static const Duration repeatWindow = Duration(minutes: 1); @@ -53,8 +61,11 @@ class PopupPresenter { final Map _shownAt = {}; final Set _delayed = {}; - final Queue<_Request> _queue = Queue<_Request>(); - _Request? _current; + + // One queue for the app, not one per handle: popups of two shops would otherwise open + // over each other. + static final Queue<_Request> _queue = Queue<_Request>(); + static _Request? _current; /// A popup from the server: waits out its delay, then goes to [onPopup] or on screen. void receive(InAppPopup popup) { @@ -67,7 +78,7 @@ class PopupPresenter { Timer(popup.delay, () { _delayed.remove(popup.id); if (_isRepeat(popup.id)) return; - final handler = onPopup; + final handler = onPopup ?? sharedOnPopup; if (handler != null) { try { handler(popup); @@ -84,16 +95,15 @@ class PopupPresenter { }); } - /// Shows [popup] after the one on screen, if any. Completes when the popup closes, or - /// at once when it cannot be shown. + /// Shows [popup] after the one on screen, if any, whichever shop that one came for. + /// Completes when the popup closes, or at once when it cannot be shown. Future present(InAppPopup popup) { - final same = <_Request>[ - ?_current, - ..._queue, - ].where((request) => request.popup.id == popup.id); + final same = <_Request>[?_current, ..._queue].where( + (request) => request.presenter == this && request.popup.id == popup.id, + ); if (same.isNotEmpty) return same.first.done.future; - final request = _Request(popup); + final request = _Request(this, popup); _queue.add(request); _next(); return request.done.future; @@ -110,16 +120,26 @@ class PopupPresenter { return false; } - void _next() { + /// Test-only: forgets the shared handler and the queue. + @visibleForTesting + static void reset() { + sharedOnPopup = null; + _queue.clear(); + _current = null; + } + + static void _next() { if (_current != null || _queue.isEmpty) return; final request = _current = _queue.removeFirst(); - _show(request) + request.presenter + ._show(request) .catchError((Object error, StackTrace stack) { _log('popup ${request.popup.id} not shown: $error\n$stack'); }) .whenComplete(() { if (!request.done.isCompleted) request.done.complete(); - _current = null; + // Past a reset the queue has moved on without this request. + if (_current == request) _current = null; _next(); }); } @@ -366,8 +386,10 @@ class _PopupRoute extends RawDialogRoute { typedef _Picture = ({ImageProvider image, double aspect}); class _Request { - _Request(this.popup); + _Request(this.presenter, this.popup); + /// The handle that shows the popup and reports it for its shop. + final PopupPresenter presenter; final InAppPopup popup; final Completer done = Completer(); } diff --git a/test/popups/popup_presenter_test.dart b/test/popups/popup_presenter_test.dart index 45faa16..337fb7f 100644 --- a/test/popups/popup_presenter_test.dart +++ b/test/popups/popup_presenter_test.dart @@ -93,6 +93,8 @@ final Finder _cross = find.byWidgetPredicate( ); void main() { + tearDown(PopupPresenter.reset); + testWidgets('shows a popup over the navigator and reports it once', ( tester, ) async { @@ -178,6 +180,55 @@ void main() { expect(h.tracked, [1, 2]); }); + testWidgets( + 'popups of two shops: one at a time, each reported for its shop', + (tester) async { + final a = await _pumpApp(tester); + final b = _Harness(); + + a.presenter.receive(_popup(id: 1)); + b.presenter + ..receive(_popup(id: 2)) + // The same id from another shop is another popup. + ..receive(_popup(id: 1)); + await tester.pumpAndSettle(); + expect(find.text('Title 1'), findsOneWidget); + expect(find.text('Title 2'), findsNothing); + + await tester.tap(_cross); + await tester.pumpAndSettle(); + expect(find.text('Title 1'), findsNothing); + expect(find.text('Title 2'), findsOneWidget); + + await tester.tap(_cross); + await tester.pumpAndSettle(); + expect(find.text('Title 1'), findsOneWidget); + expect(a.tracked, [1]); + expect(b.tracked, [2, 1]); + }, + ); + + testWidgets('the shared handler takes popups of a handle without its own', ( + tester, + ) async { + final h = await _pumpApp(tester); + final shared = []; + final own = []; + PopupPresenter.sharedOnPopup = shared.add; + + h.presenter.receive(_popup(id: 1)); + await tester.pumpAndSettle(); + expect(shared.map((popup) => popup.id), [1]); + expect(find.text('Title 1'), findsNothing); + expect(h.tracked, isEmpty); + + h.presenter.onPopup = own.add; + h.presenter.receive(_popup(id: 2)); + await tester.pumpAndSettle(); + expect(own.map((popup) => popup.id), [2]); + expect(shared, hasLength(1)); + }); + testWidgets('onPopup takes the popup; the SDK neither shows nor reports it', ( tester, ) async { diff --git a/test/popups/popup_sdk_test.dart b/test/popups/popup_sdk_test.dart index 1790c85..7440666 100644 --- a/test/popups/popup_sdk_test.dart +++ b/test/popups/popup_sdk_test.dart @@ -4,6 +4,7 @@ import 'package:flutter_test/flutter_test.dart'; import 'package:rees46_sdk/rees46_sdk.dart'; import 'package:rees46_sdk/src/pigeon/personalization_api.g.dart' as pigeon; import 'package:rees46_sdk/src/popups/popup_dispatcher.dart'; +import 'package:rees46_sdk/src/popups/popup_presenter.dart'; class _FakeApi extends pigeon.PersonalizationHostApi { final List<(int, String?)> tracked = <(int, String?)>[]; @@ -27,14 +28,16 @@ void main() { TestWidgetsFlutterBinding.ensureInitialized(); tearDown(PopupDispatcher.instance.reset); + tearDown(PopupPresenter.reset); Future<(PersonalizationSdk, _FakeApi, List)> initialized( - String shopId, - ) async { + String shopId, { + bool ownHandler = true, + }) async { final api = _FakeApi(); final sdk = PersonalizationSdk(api: api, shopId: shopId); final taken = []; - sdk.onPopup = taken.add; + if (ownHandler) sdk.onPopup = taken.add; await sdk.initialize(SdkInitConfig(shopId: shopId)); return (sdk, api, taken); } @@ -53,8 +56,29 @@ void main() { expect(takenA, isEmpty); expect(takenB.map((popup) => popup.title), ['Popup 2']); + expect(takenB.single.shopId, 'shop-b'); }); + testWidgets( + 'REES46.onPopup takes popups of shops without a handler of their own', + (tester) async { + await initialized('shop-a', ownHandler: false); + final (_, _, takenB) = await initialized('shop-b'); + final shared = []; + REES46.onPopup = shared.add; + + PopupDispatcher.instance + ..onPopup('shop-a', _json(1)) + ..onPopup('shop-b', _json(2)); + await tester.pump(Duration.zero); + + expect(shared.map((popup) => (popup.id, popup.shopId)), <(int, String?)>[ + (1, 'shop-a'), + ]); + expect(takenB.map((popup) => popup.id), [2]); + }, + ); + testWidgets('tracking.popupShown reports for the shop and stops a repeat', ( tester, ) async { From 0b3c06194e29c856e9aabd2525da272344cfc024 Mon Sep 17 00:00:00 2001 From: andreykropotov Date: Tue, 27 Oct 2026 20:36:53 +0400 Subject: [PATCH 3/4] docs: popups of several shops, the navigator wait and links in README --- README.md | 35 +++++++++++++++++++++++++++++++---- 1 file changed, 31 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 21d4e7c..177af6e 100644 --- a/README.md +++ b/README.md @@ -161,13 +161,21 @@ never registered). 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. +`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, -one is shown at a time, and one shown within the last minute is not shown again. -The link button opens its link, the push-subscription button opens the app's -notification settings. A popup is reported as shown once it is on screen. +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](#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: @@ -212,6 +220,25 @@ sdk.onPopup = (InAppPopup popup) { `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: + +```dart +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 From da2579e6b6613a08d5857d96413fc89704200e52 Mon Sep 17 00:00:00 2001 From: andreykropotov Date: Tue, 27 Oct 2026 20:47:27 +0400 Subject: [PATCH 4/4] ci: name the iOS builds by how they take the plugin --- .github/workflows/checks.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/checks.yaml b/.github/workflows/checks.yaml index 06aeb0d..068d4c0 100644 --- a/.github/workflows/checks.yaml +++ b/.github/workflows/checks.yaml @@ -66,6 +66,7 @@ jobs: # support turned off still use. Both point at the same sources and the same # native SDK version, and either can drift on its own. ios: + name: ios (${{ matrix.swift-package-manager == 'true' && 'Swift Package Manager' || 'CocoaPods' }}) if: github.event.pull_request.draft == false runs-on: macos-latest strategy: