Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/workflows/checks.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
58 changes: 50 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -157,18 +157,25 @@ 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.
`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:
Expand Down Expand Up @@ -213,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
Expand Down Expand Up @@ -450,6 +476,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).
20 changes: 18 additions & 2 deletions lib/src/multi_instance/rees46.dart
Original file line number Diff line number Diff line change
@@ -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';
Expand Down Expand Up @@ -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<String> get liveShopIds => _instance._live.keys.toList()..sort();

Expand Down Expand Up @@ -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;
}
}
22 changes: 12 additions & 10 deletions lib/src/personalization_sdk.dart
Original file line number Diff line number Diff line change
Expand Up @@ -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<void> presentPopup(InAppPopup popup) => _popups.present(popup);

Expand Down
14 changes: 11 additions & 3 deletions lib/src/popups/in_app_popup.dart
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -30,10 +32,11 @@ class InAppPopup {
this.json = const <String, Object?>{},
});

/// 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<String, Object?> json, {
String? shopId,
TargetPlatform? platform,
}) {
final components = _map(json['components']);
Expand All @@ -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,
Expand All @@ -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.
Expand Down
4 changes: 3 additions & 1 deletion lib/src/popups/popup_dispatcher.dart
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,9 @@ class PopupDispatcher implements pigeon.PersonalizationPopupFlutterApi {
return;
}
if (decoded is! Map) return;
presenter.receive(InAppPopup.fromJson(decoded.cast<String, Object?>()));
presenter.receive(
InAppPopup.fromJson(decoded.cast<String, Object?>(), shopId: shopId),
);
}

/// Test-only: drops all registrations.
Expand Down
50 changes: 36 additions & 14 deletions lib/src/popups/popup_presenter.dart
Original file line number Diff line number Diff line change
Expand Up @@ -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<void> Function(int popupId) trackShown,
Expand All @@ -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);

Expand All @@ -53,8 +61,11 @@ class PopupPresenter {

final Map<int, DateTime> _shownAt = <int, DateTime>{};
final Set<int> _delayed = <int>{};
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) {
Expand All @@ -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);
Expand All @@ -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<void> 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;
Expand All @@ -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();
});
}
Expand Down Expand Up @@ -366,8 +386,10 @@ class _PopupRoute extends RawDialogRoute<void> {
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<void> done = Completer<void>();
}
Expand Down
Loading
Loading