From 027330f00effea4ef48d50e1f8d015f514f3c040 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Mon, 26 Oct 2026 14:57:09 -0400 Subject: [PATCH 01/28] feat!: send desktop events through capture v1 Windows and Linux post to /i/v1/analytics/events with bearer auth, per-event results and the v1 retry rules. --- .changeset/v6-desktop-capture-v1.md | 6 + example/integration_test/desktop_test.dart | 4 +- posthog_flutter/lib/src/core/capture_v1.dart | 153 +++++++ .../lib/src/core/feature_flag_utils.dart | 4 + .../lib/src/core/posthog_core_stateless.dart | 351 +++++++++++---- .../lib/src/posthog_flutter_desktop.dart | 2 +- .../test/core/capture_v1_test.dart | 412 ++++++++++++++++++ .../test/core/compression_test.dart | 6 +- .../core/desktop_parity_regressions_test.dart | 6 +- .../test/core/file_queue_test.dart | 4 +- .../test/core/queue_flush_test.dart | 84 ++-- posthog_flutter/test/core/requests_test.dart | 46 +- posthog_flutter/test/posthog_api_fake.dart | 28 +- .../test/posthog_desktop_transport_test.dart | 13 +- .../test/posthog_flutter_desktop_test.dart | 4 +- 15 files changed, 985 insertions(+), 138 deletions(-) create mode 100644 .changeset/v6-desktop-capture-v1.md create mode 100644 posthog_flutter/lib/src/core/capture_v1.dart create mode 100644 posthog_flutter/test/core/capture_v1_test.dart diff --git a/.changeset/v6-desktop-capture-v1.md b/.changeset/v6-desktop-capture-v1.md new file mode 100644 index 00000000..0f3c6c91 --- /dev/null +++ b/.changeset/v6-desktop-capture-v1.md @@ -0,0 +1,6 @@ +--- +"posthog_flutter": major +--- + +- **Breaking:** on Windows and Linux, events now go to capture v1 (`/i/v1/analytics/events`) instead of `/batch/`, like iOS and Android in 6.0. A reverse proxy or self-hosted instance must serve the new path: a 404 drops the events. Events queued before the upgrade are sent through the new endpoint +- **Breaking:** on Windows and Linux, a 429 or a redirect drops the batch instead of retrying it (only same-origin 307/308 redirects are followed), and a `Retry-After` wait is capped at 30 seconds diff --git a/example/integration_test/desktop_test.dart b/example/integration_test/desktop_test.dart index e4b3c8b9..acee9fb5 100644 --- a/example/integration_test/desktop_test.dart +++ b/example/integration_test/desktop_test.dart @@ -68,7 +68,7 @@ void main() { final event = await server.waitForEvent('e2e event'); final properties = event['properties'] as Map; expect(properties['source'], 'integration test'); - expect(properties[r'$lib'], 'posthog-flutter'); + expect(event['session_id'], allOf(isA(), isNotEmpty)); expect(properties[r'$os_name'], Platform.isWindows ? 'Windows' : 'Linux'); expect(properties[r'$os_version'], allOf(isA(), isNotEmpty)); expect(properties[r'$device_type'], 'Desktop'); @@ -201,7 +201,7 @@ class _FakePostHog { final response = request.response; switch (request.uri.path) { - case '/batch/': + case '/i/v1/analytics/events': response.statusCode = batchStatus; if (batchStatus == HttpStatus.ok) _batches.add(body); case '/flags/': diff --git a/posthog_flutter/lib/src/core/capture_v1.dart b/posthog_flutter/lib/src/core/capture_v1.dart new file mode 100644 index 00000000..b8c29891 --- /dev/null +++ b/posthog_flutter/lib/src/core/capture_v1.dart @@ -0,0 +1,153 @@ +import 'dart:convert'; + +import 'logger.dart'; + +/// The capture v1 endpoint for analytics events. +const captureV1Path = '/i/v1/analytics/events'; + +/// Capture v1 statuses worth retrying. Everything else is terminal, +/// including 429 and 3xx; 413 halves the batch instead. +bool isRetriableCaptureV1Status(int status) => + status == 408 || + status == 500 || + status == 502 || + status == 503 || + status == 504; + +/// Legacy event properties and the capture v1 option each one fills. +const legacyOptionProperties = { + r'$cookieless_mode': 'cookieless_mode', + r'$ignore_sent_at': 'disable_skew_correction', + r'$product_tour_id': 'product_tour_id', + r'$process_person_profile': 'process_person_profile', +}; + +/// Shapes a queued event for capture v1. +/// +/// `$session_id` and `$window_id` move to the event root, and `$lib` and +/// `$lib_version` are left out: the server reads them from the +/// `PostHog-Sdk-Info` header. +/// +/// The legacy option properties are moved into `options` here, when the +/// request is built, so that events queued by earlier versions are converted +/// too. Each one is always removed from the properties and fills its option +/// only when the event's `options` leave it unset or null. Values are sent +/// as they are: the server validates them. +Map captureV1Event( + Map queued, + CoreLogger logger, +) { + final properties = { + if (queued['properties'] case final Map stored) + for (final MapEntry(:key, :value) in stored.entries) '$key': value, + } + ..remove(r'$lib') + ..remove(r'$lib_version'); + + final options = { + if (queued['options'] case final Map stored) + for (final MapEntry(:key, :value) in stored.entries) '$key': value, + }; + for (final MapEntry(key: property, value: option) + in legacyOptionProperties.entries) { + if (!properties.containsKey(property)) continue; + final legacy = properties.remove(property); + if (legacy != null && options[option] == null) options[option] = legacy; + } + + final sessionId = _liftString(r'$session_id', properties, logger); + final windowId = _liftString(r'$window_id', properties, logger); + return { + 'event': queued['event'], + 'uuid': queued['uuid'], + 'distinct_id': queued['distinct_id'], + 'timestamp': queued['timestamp'], + if (sessionId != null) 'session_id': sessionId, + if (windowId != null) 'window_id': windowId, + if (options.isNotEmpty) 'options': options, + 'properties': properties, + }; +} + +/// Removes [key] from [properties] and returns its value when it is a +/// string, an empty one included. Capture v1 rejects the whole request when +/// a root `session_id` or `window_id` is not a string, so any other value is +/// dropped with a warning naming its JSON type, never the value. Null counts +/// as unset. +String? _liftString( + String key, + Map properties, + CoreLogger logger, +) { + final value = properties.remove(key); + if (value == null || value is String) return value as String?; + logger.warn('Dropping $key: a ${_jsonType(value)} value is not a string.'); + return null; +} + +String _jsonType(Object value) => switch (value) { + bool() => 'bool', + num() => 'number', + Map() => 'object', + List() => 'array', + _ => value.runtimeType.toString(), + }; + +/// The identity of a capture v1 request. A retry of the same events reuses +/// the request id and `created_at`, with the next attempt number. +class CaptureV1Identity { + CaptureV1Identity({ + required this.uuids, + required this.requestId, + required this.createdAt, + this.attempt = 1, + }); + + /// The events the request carries. + final Set uuids; + final String requestId; + final String createdAt; + final int attempt; + + /// The identity of the retry of [uuids], the events among [this.uuids] + /// that are still to be delivered. + CaptureV1Identity withUuids(Set uuids) => CaptureV1Identity( + uuids: uuids, + requestId: requestId, + createdAt: createdAt, + attempt: attempt, + ); + + /// The identity of the next attempt to send the same events. + CaptureV1Identity next() => CaptureV1Identity( + uuids: uuids, + requestId: requestId, + createdAt: createdAt, + attempt: attempt + 1, + ); +} + +/// The uuids among [uuids] that a capture v1 response [body] asks to +/// retry, or null when the body has no readable per-event results. +/// +/// `ok`, `warning`, `drop`, `limited` and any unknown result are final. +/// An event missing from the results counts as delivered. +Set? captureV1RetryUuids(String? body, Iterable uuids) { + if (body == null) return null; + final Object? results; + try { + final decoded = jsonDecode(body); + results = decoded is Map ? decoded['results'] : null; + } on FormatException { + return null; + } + if (results is! Map) return null; + return { + for (final uuid in uuids) + if (results[uuid] case {'result': 'retry'}) uuid, + }; +} + +/// Whether two `Set`s hold the same elements. +bool sameUuids(Set a, Set b) => + a.length == b.length && a.containsAll(b); diff --git a/posthog_flutter/lib/src/core/feature_flag_utils.dart b/posthog_flutter/lib/src/core/feature_flag_utils.dart index 210f0770..af7cc708 100644 --- a/posthog_flutter/lib/src/core/feature_flag_utils.dart +++ b/posthog_flutter/lib/src/core/feature_flag_utils.dart @@ -79,6 +79,10 @@ const minimalFeatureFlagCalledProperties = { r'$feature_flag_error', r'$groups', r'$process_person_profile', + // Converted to capture v1 options when the request is built. + r'$cookieless_mode', + r'$ignore_sent_at', + r'$product_tour_id', r'$geoip_disable', r'$session_id', r'$window_id', diff --git a/posthog_flutter/lib/src/core/posthog_core_stateless.dart b/posthog_flutter/lib/src/core/posthog_core_stateless.dart index 9e97bae3..83b53561 100644 --- a/posthog_flutter/lib/src/core/posthog_core_stateless.dart +++ b/posthog_flutter/lib/src/core/posthog_core_stateless.dart @@ -6,6 +6,7 @@ import 'package:meta/meta.dart'; import '../posthog_config.dart'; import '../posthog_flutter_version.dart'; +import 'capture_v1.dart'; import 'event_emitter.dart'; import 'feature_flag_utils.dart'; import 'feature_flags.dart'; @@ -39,17 +40,11 @@ class PostHogFetchNetworkError implements Exception { String toString() => 'PostHogFetchNetworkError: $cause'; } -/// Network failures and transient HTTP statuses are worth retrying; -/// hard 4xx (invalid token, bad payload) will fail the same way again. -/// A redirect is not followed for a POST, so the batch never reached -/// ingestion and stays queued. -bool _isTransientFetchError(Object err) => +/// Network failures and the retriable capture v1 statuses are worth +/// retrying; any other status will fail the same way again. +bool _isTransientCaptureError(Object err) => err is PostHogFetchNetworkError || - (err is PostHogFetchHttpError && - (err.status >= 500 || - err.status == 429 || - err.status == 408 || - (err.status >= 300 && err.status < 400))); + (err is PostHogFetchHttpError && isRetriableCaptureV1Status(err.status)); /// Only transport failures and gateway errors are worth retrying for /// `/flags`: any other status is the server's answer for this evaluation. @@ -79,6 +74,16 @@ abstract class PostHogCoreStateless { static const _flagsRetryCount = 1; static const _flagsRetryDelay = Duration(milliseconds: 300); + /// The longest `Retry-After` pause honored for events. + static const _maxRetryAfter = Duration(seconds: 30); + + /// How many same-origin 307/308 redirects a capture request follows. + static const _maxCaptureRedirects = 5; + + /// The identity of the last capture request whose events are still to be + /// retried. Kept in memory: after a restart the retry is a new request. + CaptureV1Identity? _pendingCaptureIdentity; + /// The latest consent decision made through this client. It wins over the /// stored one: [clearPersistedOptOut] removes the stored decision while /// this client keeps honoring it, and a decision the storage cannot @@ -266,6 +271,7 @@ abstract class PostHogCoreStateless { String distinctId, String event, { required Map properties, + Map? options, }) { _enqueue( 'capture', @@ -274,6 +280,7 @@ abstract class PostHogCoreStateless { event: event, properties: properties, ), + options: options, ); } @@ -399,11 +406,20 @@ abstract class PostHogCoreStateless { }); } - void _enqueue(String type, Map message) { + /// Queues [message]. Its capture v1 [options] are queued with it; the + /// legacy option properties are converted only when the request is built, + /// see [captureV1Event]. + void _enqueue( + String type, + Map message, { + Map? options, + }) { final prepared = { ...message, if (message['properties'] case final Map properties) 'properties': _serializableProperties(properties), + if (options != null && options.isNotEmpty) + 'options': _serializableProperties(options), 'type': type, 'library': postHogFlutterSdkName, 'library_version': postHogFlutterVersion, @@ -460,11 +476,15 @@ abstract class PostHogCoreStateless { _flushTimer = null; } + /// Stops sending events for [delay], the server's `Retry-After`, kept + /// between the retry delay and [_maxRetryAfter]. void _pauseFlush(Duration delay) { _clearFlushTimer(); _retryAfterTimer?.cancel(); - _retryAfterTimer = - Timer(delay < _fetchRetryDelay ? _fetchRetryDelay : delay, () { + final pause = delay < _fetchRetryDelay + ? _fetchRetryDelay + : (delay > _maxRetryAfter ? _maxRetryAfter : delay); + _retryAfterTimer = Timer(pause, () { _retryAfterTimer = null; if (!_closed && _flushInterval > Duration.zero && @@ -496,47 +516,69 @@ abstract class PostHogCoreStateless { final queue = storage.queue; final sentMessages = >[]; - while (!_closed) { - // Peeked again after every request, so events queued in the meantime - // go out with the same flush. - final batch = queue.peek(_maxBatchSize); - if (batch.isEmpty) { - if (queue.length > 0) _scheduleFlush(); - break; + try { + while (!_closed) { + // Peeked again after every request, so events queued in the meantime + // go out with the same flush. + final batch = queue.peek(_maxBatchSize); + if (batch.isEmpty) { + if (queue.length > 0) _scheduleFlush(); + break; + } + if (!await _sendBatch(batch, sentMessages)) break; } - final batchMessages = [for (final queued in batch) queued.event]; - - final data = { - 'api_key': _apiKey, - 'batch': batchMessages, - 'sent_at': currentISOTime(), - }; + } finally { + if (sentMessages.isNotEmpty) { + events.emit('flush', sentMessages); + } + } + } - final payload = jsonEncode(data); - final url = '$_host/batch/'; + /// Sends [batch] to capture v1, retrying what is worth it, and removes + /// from the queue the events that are done: delivered, or dropped for + /// good. Adds the delivered ones to [sent]. + /// + /// Returns whether the flush goes on with the rest of the queue. It stops + /// while events of [batch] wait for a later retry; the periodic flush or + /// the server's `Retry-After` sends them again. + Future _sendBatch( + List batch, + List> sent, + ) async { + final queue = storage.queue; + var pending = batch; + for (var attempt = 0;; attempt++) { + if (attempt > 0) { + await Future.delayed(_fetchRetryDelay); + // A client closed meanwhile leaves the queue to the next one. + if (_closed) return false; + } + final Set retryUuids; + final Duration? retryAfter; try { - await _fetchWithRetry(url, payload, honorRetryAfter: true); + (:retryUuids, :retryAfter) = await _postCaptureV1(pending); } catch (e) { - // A client closed meanwhile leaves the queue to the next one. if (_closed) rethrow; if (e is PostHogFetchHttpError && - e.status == 413 && - batchMessages.length > 1) { - _maxBatchSize = (batchMessages.length ~/ 2).clamp(1, _maxBatchSize); + e.status == HttpStatus.requestEntityTooLarge && + pending.length > 1) { + _maxBatchSize = (pending.length ~/ 2).clamp(1, _maxBatchSize); logger.warn('Received 413, reducing batch size to $_maxBatchSize'); + return true; + } + final transient = _isTransientCaptureError(e); + final retryAfter = e is PostHogFetchHttpError ? e.retryAfter : null; + if (transient && retryAfter == null && attempt < _fetchRetryCount) { continue; } - - if (!_isTransientFetchError(e)) { - queue.remove([for (final queued in batch) queued.id]); + if (!transient) { + queue.remove([for (final queued in pending) queued.id]); } // Re-arm the periodic flush: otherwise queued events sit until the // next capture (forever in an idle app after an offline failure). - if (_isTransientFetchError(e) && - e is PostHogFetchHttpError && - e.retryAfter != null) { - _pauseFlush(e.retryAfter!); + if (transient && retryAfter != null) { + _pauseFlush(retryAfter); } else { _scheduleFlush(); } @@ -544,14 +586,128 @@ abstract class PostHogCoreStateless { rethrow; } + final retained = [ + for (final queued in pending) + if (retryUuids.contains(queued.event['uuid'])) queued, + ]; + final delivered = [ + for (final queued in pending) + if (!retryUuids.contains(queued.event['uuid'])) queued, + ]; // Removed by id: the queue may have changed while the batch was in // flight, e.g. its oldest events dropped to make room. - queue.remove([for (final queued in batch) queued.id]); - sentMessages.addAll(batchMessages); + queue.remove([for (final queued in delivered) queued.id]); + sent.addAll([for (final queued in delivered) queued.event]); + if (retained.isEmpty) return true; + + // Counts only: uuids and server details can identify users. + logger.info('Capture asked to retry ${retained.length} of ' + '${pending.length} events.'); + pending = retained; + if (retryAfter != null) { + _pauseFlush(retryAfter); + return false; + } + if (attempt >= _fetchRetryCount) { + _scheduleFlush(); + return false; + } } + } + + /// Posts [batch] to capture v1 and returns the uuids of the events the + /// server asked to retry, with its `Retry-After`. Every other event was + /// delivered or dropped for good. + /// + /// A 2xx whose per-event results cannot be read, also when the response + /// fails after its status arrived, counts as delivered: the server stored + /// the events, and sending them again would store them twice. + /// + /// Throws [PostHogFetchHttpError] for a non-2xx status and + /// [PostHogFetchNetworkError] for a transport failure. + Future<({Set retryUuids, Duration? retryAfter})> _postCaptureV1( + List batch, + ) async { + final uuids = { + for (final queued in batch) + if (queued.event['uuid'] case final String uuid) uuid, + }; + final pending = _pendingCaptureIdentity; + final identity = pending != null && sameUuids(pending.uuids, uuids) + ? pending.next() + : CaptureV1Identity( + uuids: uuids, + requestId: generateUuidV7(), + createdAt: currentISOTime(), + ); + _pendingCaptureIdentity = identity; - if (sentMessages.isNotEmpty) { - events.emit('flush', sentMessages); + final body = jsonEncode({ + 'created_at': identity.createdAt, + 'batch': [ + for (final queued in batch) captureV1Event(queued.event, logger), + ], + }); + final headers = { + HttpHeaders.authorizationHeader: 'Bearer $_apiKey', + 'PostHog-Sdk-Info': '$postHogFlutterSdkName/$postHogFlutterVersion', + 'PostHog-Attempt': '${identity.attempt}', + 'PostHog-Request-Id': identity.requestId, + 'PostHog-Request-Timestamp': currentISOTime(), + }; + + // A transport failure keeps the identity, so the resend reuses it. + final response = await _fetchCaptureV1(body, headers); + + if (response.status < 200 || response.status >= 300) { + if (!isRetriableCaptureV1Status(response.status)) { + _pendingCaptureIdentity = null; + } + throw PostHogFetchHttpError( + response.status, + response.body ?? '', + body.length, + retryAfter: response.retryAfter, + ); + } + + var retryUuids = captureV1RetryUuids(response.body, uuids); + if (retryUuids == null) { + logger.info('Capture returned ${response.status} without readable ' + 'per-event results; ${uuids.length} events count as delivered.'); + retryUuids = const {}; + } + _pendingCaptureIdentity = + retryUuids.isEmpty ? null : identity.withUuids(retryUuids); + return (retryUuids: retryUuids, retryAfter: response.retryAfter); + } + + /// Posts a capture v1 [body], following only 307 and 308 redirects to the + /// origin of the configured host, at most [_maxCaptureRedirects] times, + /// with the same body and headers. Any other redirect is returned as it + /// is, and is terminal. + Future<({int status, String? body, Duration? retryAfter, String? location})> + _fetchCaptureV1( + String body, + Map headers, + ) async { + final origin = Uri.parse(_host); + var url = Uri.parse('$_host$captureV1Path'); + for (var redirects = 0;; redirects++) { + final response = await _fetchOnce(url, body, + headers: headers, deliveredOnBodyFailure: true); + if (response.status != 307 && response.status != 308) return response; + final location = response.location; + final target = location == null ? null : url.resolve(location); + if (redirects >= _maxCaptureRedirects || + target == null || + target.scheme != origin.scheme || + target.host.toLowerCase() != origin.host.toLowerCase() || + target.port != origin.port) { + logger.warn('Capture did not follow a ${response.status} redirect.'); + return response; + } + url = target; } } @@ -560,48 +716,71 @@ abstract class PostHogCoreStateless { Future _fetchWithRetry( String url, String body, { - int retryCount = _fetchRetryCount, - Duration retryDelay = _fetchRetryDelay, - bool Function(Object error) retryCheck = _isTransientFetchError, - bool honorRetryAfter = false, + required int retryCount, + required Duration retryDelay, + required bool Function(Object error) retryCheck, }) async { return retriable( () async { - final ({int status, String body, Duration? retryAfter}) response; - final attempt = _FetchAttempt(); - try { - response = await _fetch(url, body, attempt).timeout( - _requestTimeout, - onTimeout: () async { - await attempt.cancel(); - throw attempt.timeout; - }, - ); - } catch (e) { - throw PostHogFetchNetworkError(e); - } - + final response = await _fetchOnce(Uri.parse(url), body); if (response.status < 200 || response.status >= 300) { throw PostHogFetchHttpError( response.status, - response.body, + response.body ?? '', body.length, retryAfter: response.retryAfter, ); } - return response.body; + return response.body ?? ''; }, retryCount: retryCount, retryDelay: retryDelay, - retryCheck: (error) => - !_closed && - retryCheck(error) && - !(honorRetryAfter && - error is PostHogFetchHttpError && - error.retryAfter != null), + retryCheck: (error) => !_closed && retryCheck(error), ); } + /// Sends one request, bounded by [_requestTimeout]. A transport failure + /// is thrown as [PostHogFetchNetworkError], except, with + /// [deliveredOnBodyFailure], one that happens after a 2xx status arrived: + /// the response is then returned without a body. + Future< + ({ + int status, + String? body, + Duration? retryAfter, + String? location, + })> _fetchOnce( + Uri url, + String body, { + Map headers = const {}, + bool deliveredOnBodyFailure = false, + }) async { + final attempt = _FetchAttempt(); + try { + return await _fetch(url, body, attempt, headers).timeout( + _requestTimeout, + onTimeout: () async { + await attempt.cancel(); + throw attempt.timeout; + }, + ); + } catch (e) { + final status = attempt.status; + if (deliveredOnBodyFailure && + status != null && + status >= 200 && + status < 300) { + return ( + status: status, + body: null, + retryAfter: attempt.retryAfter, + location: null, + ); + } + throw PostHogFetchNetworkError(e); + } + } + static Duration? _parseRetryAfter(String? value) { if (value == null) return null; final seconds = int.tryParse(value.trim()); @@ -618,9 +797,19 @@ abstract class PostHogCoreStateless { return delay > Duration.zero ? delay : null; } - Future<({int status, String body, Duration? retryAfter})> _fetch( - String url, String body, _FetchAttempt attempt) async { - final request = await _httpClient.postUrl(Uri.parse(url)); + Future< + ({ + int status, + String? body, + Duration? retryAfter, + String? location, + })> _fetch( + Uri url, + String body, + _FetchAttempt attempt, + Map headers, + ) async { + final request = await _httpClient.postUrl(url); attempt.attachRequest(request); // A redirect is reported rather than followed, so a redirected batch is // not taken for delivered. @@ -632,6 +821,7 @@ abstract class PostHogCoreStateless { ..set(HttpHeaders.userAgentHeader, '$postHogFlutterSdkName/$postHogFlutterVersion') ..set(HttpHeaders.contentTypeHeader, 'application/json'); + headers.forEach(request.headers.set); final bytes = utf8.encode(body); final List payload; if (_compression == PostHogCompression.gzip) { @@ -644,12 +834,17 @@ abstract class PostHogCoreStateless { request.add(payload); final response = await request.close(); + final retryAfter = + _parseRetryAfter(response.headers.value(HttpHeaders.retryAfterHeader)); + attempt + ..status = response.statusCode + ..retryAfter = retryAfter; final responseBody = await attempt.readBody(response); return ( status: response.statusCode, body: responseBody, - retryAfter: _parseRetryAfter( - response.headers.value(HttpHeaders.retryAfterHeader)), + retryAfter: retryAfter, + location: response.headers.value(HttpHeaders.locationHeader), ); } @@ -671,6 +866,10 @@ class _FetchAttempt { final timeout = TimeoutException('PostHog request timed out'); HttpClientRequest? _request; + + /// The status and `Retry-After` of the response, once it has arrived. + int? status; + Duration? retryAfter; StreamSubscription? _responseSubscription; Completer? _responseBody; bool _cancelled = false; diff --git a/posthog_flutter/lib/src/posthog_flutter_desktop.dart b/posthog_flutter/lib/src/posthog_flutter_desktop.dart index f8baec36..7b7df894 100644 --- a/posthog_flutter/lib/src/posthog_flutter_desktop.dart +++ b/posthog_flutter/lib/src/posthog_flutter_desktop.dart @@ -749,7 +749,7 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { return merged.isNotEmpty ? merged : null; } - /// Converts the values jsonEncode cannot handle, which storage and /batch/ + /// Converts the values jsonEncode cannot handle, which storage and capture /// payloads need. Map? _normalize(Map? properties) { if (properties == null || properties.isEmpty) return properties; diff --git a/posthog_flutter/test/core/capture_v1_test.dart b/posthog_flutter/test/core/capture_v1_test.dart new file mode 100644 index 00000000..3c86308c --- /dev/null +++ b/posthog_flutter/test/core/capture_v1_test.dart @@ -0,0 +1,412 @@ +import 'dart:convert'; +import 'dart:io'; + +import 'package:fake_async/fake_async.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:posthog_flutter/src/core/capture_v1.dart'; +import 'package:posthog_flutter/src/core/file_storage.dart'; +import 'package:posthog_flutter/src/core/logger.dart'; +import 'package:posthog_flutter/src/core/posthog_core_stateless.dart'; +import 'package:posthog_flutter/src/core/uuid.dart'; +import 'package:posthog_flutter/src/posthog_flutter_version.dart'; + +import '../posthog_api_fake.dart'; +import 'test_client.dart'; + +final _uuidPattern = + RegExp(r'^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'); + +void main() { + group('Capture v1 request', () { + test('posts the v1 envelope with bearer auth and request headers', + () async { + final server = await LocalPostHogServer.start(); + final client = testClient(server); + + client.capture('first', properties: {'plan': 'pro'}); + client.capture('second'); + await client.flush(); + + final request = server.batchRequests.single; + expect(request.path, '/i/v1/analytics/events'); + expect(request.headers['authorization'], 'Bearer k'); + expect(request.headers['posthog-sdk-info'], + '$postHogFlutterSdkName/$postHogFlutterVersion'); + expect(request.headers['posthog-attempt'], '1'); + expect(request.headers['posthog-request-id'], matches(_uuidPattern)); + expect( + DateTime.parse(request.headers['posthog-request-timestamp']!).isUtc, + isTrue); + expect(request.body.keys, unorderedEquals(['created_at', 'batch'])); + expect( + DateTime.parse(request.body['created_at']! as String).isUtc, isTrue); + + for (final event in request.events) { + expect( + event.keys, + unorderedEquals([ + 'event', + 'uuid', + 'distinct_id', + 'timestamp', + 'session_id', + 'options', + 'properties', + ])); + expect(event['uuid'], matches(_uuidPattern)); + expect(event['distinct_id'], client.getDistinctId()); + expect(event['session_id'], client.getSessionId()); + expect(event['options'], {'process_person_profile': false}); + final properties = event['properties']! as Map; + for (final moved in [ + r'$lib', + r'$lib_version', + r'$session_id', + r'$process_person_profile', + ]) { + expect(properties, isNot(contains(moved))); + } + } + expect(request.events.first['properties'], containsPair('plan', 'pro')); + }); + + test('moves the legacy option properties into options', () async { + final server = await LocalPostHogServer.start(); + final client = testClient(server); + + client.capture('tour', properties: { + r'$cookieless_mode': true, + r'$ignore_sent_at': true, + r'$product_tour_id': 'tour-1', + }); + await client.flush(); + + final event = server.events.single; + expect(event['options'], { + 'cookieless_mode': true, + 'disable_skew_correction': true, + 'product_tour_id': 'tour-1', + 'process_person_profile': false, + }); + expect( + (event['properties']! as Map).keys, + isNot(anyOf(contains(r'$cookieless_mode'), + contains(r'$ignore_sent_at'), contains(r'$product_tour_id')))); + }); + }); + + group('captureV1Event', () { + final logger = CoreLogger((_) {}); + + test('keeps a set option over the legacy property, and fills a null one', + () { + final event = captureV1Event({ + 'event': 'e', + 'uuid': 'u', + 'distinct_id': 'd', + 'timestamp': 't', + 'options': {'process_person_profile': true, 'cookieless_mode': null}, + 'properties': { + r'$process_person_profile': false, + r'$cookieless_mode': true, + 'kept': 1, + }, + }, logger); + + expect(event['options'], { + 'process_person_profile': true, + 'cookieless_mode': true, + }); + expect(event['properties'], {'kept': 1}); + }); + + test('omits options when none is set', () { + final event = captureV1Event({ + 'event': 'e', + 'properties': {'kept': 1}, + }, logger); + + expect(event, isNot(contains('options'))); + }); + + test('lifts string session and window ids, empty ones included', () { + final event = captureV1Event({ + 'event': 'e', + 'properties': {r'$session_id': '', r'$window_id': 'w'}, + }, logger); + + expect(event['session_id'], ''); + expect(event['window_id'], 'w'); + expect(event['properties'], isEmpty); + }); + + test('drops a non-string session id with a warning naming its type', () { + final lines = []; + final event = captureV1Event({ + 'event': 'e', + 'properties': {r'$session_id': 42, r'$window_id': null}, + }, CoreLogger((log) => lines.addAll(printedLines(log)))); + + expect(event, isNot(contains('session_id'))); + expect(event, isNot(contains('window_id'))); + expect(event['properties'], isEmpty); + expect(lines.single, contains(r'$session_id')); + expect(lines.single, contains('number')); + expect(lines.single, isNot(contains('42'))); + }); + }); + + group('Capture v1 results', () { + test('resends only the events the server asks to retry', () { + final api = InProcessPostHogApi(); + final storage = tempStorage(); + final results = { + 'ok': 'ok', + 'warned': 'warning', + 'dropped': 'drop', + 'limited': 'limited', + 'unknown': 'unknown_future_result', + 'retried': 'retry', + }; + fakeAsync((async) { + final client = testClient(api, storage: storage); + results.keys.forEach(client.capture); + // Left out of the results: counts as delivered. + client.capture('missing'); + api.respond = (request) => api.batchRequests.length == 1 + ? PostHogResponse.json({ + 'results': { + for (final event in request.events) + if (event['event'] != 'missing') + '${event['uuid']}': { + 'result': results[event['event']], + 'details': 'detail', + }, + }, + }) + : PostHogResponse.results(request, (_) => 'ok'); + + client.flush(); + async.elapse(Duration.zero); + expect(api.batchRequests, hasLength(1)); + expect(queuedEvents(storage), ['retried']); + + async.elapse(const Duration(seconds: 3)); + expect(api.batchRequests, hasLength(2)); + final first = api.batchRequests[0]; + final retry = api.batchRequests[1]; + expect(retry.eventNames, ['retried']); + expect(retry.events.single['uuid'], + first.events.firstWhere((e) => e['event'] == 'retried')['uuid']); + expect(retry.headers['posthog-request-id'], + first.headers['posthog-request-id']); + expect(retry.headers['posthog-attempt'], '2'); + expect(retry.body['created_at'], first.body['created_at']); + expect(getQueue(storage), isEmpty); + async.elapse(const Duration(seconds: 30)); + expect(api.batchRequests, hasLength(2)); + }); + }); + + test('waits for the Retry-After of a partial retry, at most 30 seconds', + () { + final api = InProcessPostHogApi(); + final storage = tempStorage(); + api.respond = (request) => api.batchRequests.length == 1 + ? PostHogResponse.results( + request, (name) => name == 'later' ? 'retry' : null, + headers: {'Retry-After': '120'}) + : PostHogResponse.results(request, (_) => 'ok'); + fakeAsync((async) { + final client = testClient(api, storage: storage); + client.capture('now'); + client.capture('later'); + client.flush(); + + async.elapse(const Duration(seconds: 29)); + expect(api.batchRequests, hasLength(1)); + async.elapse(const Duration(seconds: 1)); + expect(api.batchRequests, hasLength(2)); + expect(api.batchRequests.last.eventNames, ['later']); + expect(api.batchRequests.last.headers['posthog-attempt'], '2'); + expect(getQueue(storage), isEmpty); + }); + }); + + test('starts a new request when new events join a retried batch', () { + final api = InProcessPostHogApi(); + final storage = tempStorage(); + api.respond = (request) => api.batchRequests.length == 1 + ? PostHogResponse.results( + request, (name) => name == 'retried' ? 'retry' : null, + headers: {'Retry-After': '5'}) + : PostHogResponse.results(request, (_) => 'ok'); + fakeAsync((async) { + final client = testClient(api, storage: storage); + client.capture('retried'); + client.flush(); + async.elapse(Duration.zero); + client.capture('joined'); + async.elapse(const Duration(seconds: 5)); + + final [first, second] = api.batchRequests; + expect(second.eventNames, ['retried', 'joined']); + expect(second.headers['posthog-request-id'], + isNot(first.headers['posthog-request-id'])); + expect(second.headers['posthog-attempt'], '1'); + expect(getQueue(storage), isEmpty); + }); + }); + + test('keeps the request identity across retries of a failed request', () { + final api = InProcessPostHogApi(); + var failures = 2; + api.respond = (_) => failures-- > 0 + ? const PostHogResponse(HttpStatus.badGateway) + : const PostHogResponse(HttpStatus.ok); + fakeAsync((async) { + final client = testClient(api); + client.capture('evt'); + client.flush(); + async.elapse(const Duration(seconds: 6)); + + final requests = api.batchRequests; + expect([for (final r in requests) r.headers['posthog-attempt']], + ['1', '2', '3']); + expect({for (final r in requests) r.headers['posthog-request-id']}, + hasLength(1)); + expect({for (final r in requests) r.body['created_at']}, hasLength(1)); + }); + }); + + test('counts a 2xx without readable results as delivered', () async { + final server = await LocalPostHogServer.start(); + final storage = tempStorage(); + final client = testClient(server, storage: storage); + server.respond = + (_) => const PostHogResponse(HttpStatus.ok, body: 'not json'); + + client.capture('evt'); + await client.flush(); + + expect(server.batchRequests, hasLength(1)); + expect(getQueue(storage), isEmpty); + }); + + test('drops a single event that is still too large', () async { + final server = await LocalPostHogServer.start(); + final storage = tempStorage(); + final client = testClient(server, storage: storage); + server.respond = + (_) => const PostHogResponse(HttpStatus.requestEntityTooLarge); + + client.capture('huge'); + await expectLater(client.flush(), throwsA(isA())); + + expect(server.batchRequests, hasLength(1)); + expect(getQueue(storage), isEmpty); + }); + + test('drops the batch on 404 without falling back to /batch', () async { + final server = await LocalPostHogServer.start(); + final storage = tempStorage(); + final client = testClient(server, storage: storage); + server.respond = (request) => request.isFlags + ? PostHogResponse.json({'flags': {}}) + : const PostHogResponse(HttpStatus.notFound); + + client.capture('evt'); + await expectLater(client.flush(), throwsA(isA())); + + expect([for (final r in server.requests) r.path], + ['/i/v1/analytics/events']); + expect(getQueue(storage), isEmpty); + }); + }); + + group('Capture v1 redirects', () { + test('follows a same-origin 307 with the body and headers', () async { + final server = await LocalPostHogServer.start(); + final storage = tempStorage(); + final client = testClient(server, storage: storage); + server.respond = (request) => request.path == '/i/v1/analytics/events' + ? PostHogResponse(HttpStatus.temporaryRedirect, + location: '${server.url}/moved/events') + : const PostHogResponse(HttpStatus.ok); + + client.capture('evt'); + await client.flush(); + + final [original, moved] = server.requests; + expect(moved.path, '/moved/events'); + expect(moved.body, original.body); + for (final header in [ + 'authorization', + 'posthog-request-id', + 'posthog-attempt', + 'content-encoding', + ]) { + expect(moved.headers[header], original.headers[header]); + } + expect(getQueue(storage), isEmpty); + }); + + test('stops after five redirects and drops the batch', () async { + final server = await LocalPostHogServer.start(); + final storage = tempStorage(); + final client = testClient(server, storage: storage); + server.respond = (request) => PostHogResponse( + HttpStatus.permanentRedirect, + location: '${server.url}/hop${server.requests.length}'); + + client.capture('evt'); + await expectLater( + client.flush(), + throwsA(isA() + .having((e) => e.status, 'status', 308))); + + expect(server.requests, hasLength(6)); + expect(getQueue(storage), isEmpty); + }); + }); + + test('sends events queued by posthog_flutter 5.x through capture v1', + () async { + final server = await LocalPostHogServer.start(); + final dir = tempDirectory(); + // An event as posthog_flutter 5.56 queued it for /batch/. + final legacy = { + 'distinct_id': 'user-1', + 'event': 'legacy event', + 'properties': { + 'plan': 'pro', + r'$lib': 'posthog-flutter', + r'$lib_version': '5.56.2', + r'$session_id': '0199aa00-0000-7000-8000-000000000001', + r'$process_person_profile': true, + r'$is_identified': true, + }, + 'type': 'capture', + 'library': 'posthog-flutter', + 'library_version': '5.56.2', + 'timestamp': '2026-10-01T12:00:00.000Z', + 'uuid': '0199aa00-0000-7000-8000-000000000002', + }; + File('${dir.path}/posthog_queue/${generateUuidV7()}.json') + ..createSync(recursive: true) + ..writeAsStringSync(jsonEncode(legacy)); + + await testClient(server, storage: FileStorage(dir.path)).flush(); + + expect(server.events.single, { + 'event': 'legacy event', + 'uuid': '0199aa00-0000-7000-8000-000000000002', + 'distinct_id': 'user-1', + 'timestamp': '2026-10-01T12:00:00.000Z', + 'session_id': '0199aa00-0000-7000-8000-000000000001', + 'options': {'process_person_profile': true}, + 'properties': {'plan': 'pro', r'$is_identified': true}, + }); + expect(Directory('${dir.path}/posthog_queue').listSync(), isEmpty); + }); +} diff --git a/posthog_flutter/test/core/compression_test.dart b/posthog_flutter/test/core/compression_test.dart index bae48946..72fe16c4 100644 --- a/posthog_flutter/test/core/compression_test.dart +++ b/posthog_flutter/test/core/compression_test.dart @@ -21,7 +21,11 @@ void main() { expect(request.headers['content-type'], 'application/json'); expect(request.headers['content-encoding'], compression == PostHogCompression.gzip ? 'gzip' : isNull); - expect(request.body['api_key'] ?? request.body['token'], 'k'); + if (request.isFlags) { + expect(request.body['token'], 'k'); + } else { + expect(request.headers['authorization'], 'Bearer k'); + } } }); } diff --git a/posthog_flutter/test/core/desktop_parity_regressions_test.dart b/posthog_flutter/test/core/desktop_parity_regressions_test.dart index 2728cd4d..05a79ac4 100644 --- a/posthog_flutter/test/core/desktop_parity_regressions_test.dart +++ b/posthog_flutter/test/core/desktop_parity_regressions_test.dart @@ -28,9 +28,9 @@ void main() { await client.reloadFeatureFlagsAsync(); await client.flush(); - final properties = server.events.single['properties']! as Map; - expect(properties['plan'], 'pro'); - expect(properties[r'$process_person_profile'], isFalse); + final event = server.events.single; + expect((event['properties']! as Map)['plan'], 'pro'); + expect(event['options'], {'process_person_profile': false}); expect(server.flagsRequests.last.body['groups'], isEmpty); client.group('company', 'acme'); diff --git a/posthog_flutter/test/core/file_queue_test.dart b/posthog_flutter/test/core/file_queue_test.dart index cb849826..4da822af 100644 --- a/posthog_flutter/test/core/file_queue_test.dart +++ b/posthog_flutter/test/core/file_queue_test.dart @@ -95,7 +95,9 @@ void main() { ['event_3', 'event_4']); expect(api.requests, isEmpty); async.elapse(const Duration(seconds: 30)); - expect(api.batchRequests.single.events, original); + expect( + [for (final event in api.batchRequests.single.events) event['uuid']], + [for (final event in original) (event as Map)['uuid']]); expect(_queueFiles(dir), isEmpty); }); }); diff --git a/posthog_flutter/test/core/queue_flush_test.dart b/posthog_flutter/test/core/queue_flush_test.dart index 21b55a5e..eefb746d 100644 --- a/posthog_flutter/test/core/queue_flush_test.dart +++ b/posthog_flutter/test/core/queue_flush_test.dart @@ -148,24 +148,7 @@ void main() { }); }); - // (status, reason the batch stays queued) - const transientStatuses = <(int, String)>[ - (408, 'the server timed out'), - (429, 'the server asks to slow down'), - (500, 'the server failed'), - ( - 301, - 'a POST redirect is not followed, so the batch never reached ' - 'ingestion' - ), - ( - 307, - 'a POST redirect is not followed, so the batch never reached ' - 'ingestion' - ), - ]; - - for (final (status, reason) in transientStatuses) { + for (final status in [408, 500, 502, 503, 504]) { test('HTTP $status keeps the batch queued after the retries', () { final api = InProcessPostHogApi() ..respond = (_) => PostHogResponse(status); @@ -182,7 +165,33 @@ void main() { expect(error, isA()); expect(api.batchRequests, hasLength(4)); - expect(getQueue(storage), hasLength(1), reason: reason); + expect(getQueue(storage), hasLength(1)); + }); + }); + } + + // Capture v1 retries only the statuses above: a rate limit, a redirect + // it does not follow, or a missing route fails the same way again. + for (final status in [301, 302, 307, 308, 401, 403, 404, 429, 501]) { + test('HTTP $status drops the batch without a retry', () { + final api = InProcessPostHogApi() + ..respond = (_) => PostHogResponse(status, + location: 'https://elsewhere.invalid/i/v1/analytics/events', + headers: {'Retry-After': '5'}); + final storage = tempStorage(); + fakeAsync((async) { + final client = testClient(api, storage: storage); + Object? error; + + client.capture('evt'); + client.flush().catchError((Object e) { + error = e; + }); + async.elapse(const Duration(seconds: 40)); + + expect(error, isA()); + expect(api.batchRequests, hasLength(1)); + expect(getQueue(storage), isEmpty); }); }); } @@ -247,7 +256,7 @@ void main() { }); group('Retry-After', () { - for (final status in [429, 503]) { + for (final status in [503]) { test('HTTP $status pauses every send path and resumes the queue', () { final api = InProcessPostHogApi(); final storage = tempStorage(); @@ -270,7 +279,8 @@ void main() { client.capture('second'); client.flush(); client.flush(); - async.elapse(const Duration(seconds: 119)); + // Retry-After 120 is capped at 30 seconds. + async.elapse(const Duration(seconds: 29)); expect(api.batchRequests, hasLength(1)); expect(queuedEvents(storage), ['first', 'second']); @@ -321,7 +331,7 @@ void main() { ..respond = (_) => PostHogResponse(HttpStatus.serviceUnavailable, headers: { 'retry-after': HttpDate.format( - DateTime.now().toUtc().add(const Duration(seconds: 120))) + DateTime.now().toUtc().add(const Duration(seconds: 20))) }); fakeAsync((async) { final client = testClient(api); @@ -333,7 +343,7 @@ void main() { async.elapse(Duration.zero); expect(error, isA()); api.respond = (_) => const PostHogResponse(HttpStatus.ok); - async.elapse(const Duration(seconds: 118)); + async.elapse(const Duration(seconds: 18)); expect(api.batchRequests, hasLength(1)); async.elapse(const Duration(seconds: 2)); expect(api.batchRequests, hasLength(2)); @@ -361,8 +371,8 @@ void main() { test('keeps the pause when consent changes and identity resets', () { final api = InProcessPostHogApi() - ..respond = (_) => const PostHogResponse(HttpStatus.tooManyRequests, - headers: {'retry-after': '120'}); + ..respond = (_) => const PostHogResponse(HttpStatus.serviceUnavailable, + headers: {'retry-after': '20'}); fakeAsync((async) { final client = testClient(api); final previousId = client.getDistinctId(); @@ -377,7 +387,7 @@ void main() { expect(nextId, isNot(previousId)); client.capture('after'); client.flush(); - async.elapse(const Duration(seconds: 119)); + async.elapse(const Duration(seconds: 19)); expect(api.batchRequests, hasLength(1)); async.elapse(const Duration(seconds: 1)); final events = api.batchRequests.last.events; @@ -389,7 +399,7 @@ void main() { test('does not send automatically when the interval is zero', () { final api = InProcessPostHogApi() - ..respond = (_) => const PostHogResponse(HttpStatus.tooManyRequests, + ..respond = (_) => const PostHogResponse(HttpStatus.serviceUnavailable, headers: {'retry-after': '120'}); fakeAsync((async) { final client = testClient(api, @@ -425,7 +435,8 @@ void main() { expect(api.flagsRequests, hasLength(2)); expect(api.batchRequests, hasLength(1)); api.respond = (_) => const PostHogResponse(HttpStatus.ok); - async.elapse(const Duration(milliseconds: 119700)); + // Retry-After 120 is capped at 30 seconds. + async.elapse(const Duration(milliseconds: 29700)); expect(api.batchRequests, hasLength(2)); }); }); @@ -450,17 +461,18 @@ void main() { test('a new rate limit starts a new pause with the minimum delay', () { final api = InProcessPostHogApi() - ..respond = (_) => const PostHogResponse(HttpStatus.tooManyRequests, - headers: {'retry-after': '60'}); + ..respond = (_) => const PostHogResponse(HttpStatus.serviceUnavailable, + headers: {'retry-after': '20'}); final storage = tempStorage(); fakeAsync((async) { final client = testClient(api, storage: storage); client.capture('event'); client.flush().catchError((Object _) {}); async.elapse(Duration.zero); - api.respond = (_) => const PostHogResponse(HttpStatus.tooManyRequests, + api.respond = (_) => const PostHogResponse( + HttpStatus.serviceUnavailable, headers: {'retry-after': '1'}); - async.elapse(const Duration(seconds: 60)); + async.elapse(const Duration(seconds: 20)); expect(api.batchRequests, hasLength(2)); api.respond = (_) => const PostHogResponse(HttpStatus.ok); client.flush(); @@ -475,8 +487,8 @@ void main() { test('close cancels the timer and preserves the queue for the next launch', () { final api = InProcessPostHogApi() - ..respond = (_) => const PostHogResponse(HttpStatus.tooManyRequests, - headers: {'retry-after': '120'}); + ..respond = (_) => const PostHogResponse(HttpStatus.serviceUnavailable, + headers: {'retry-after': '20'}); final dir = tempDirectory(); fakeAsync((async) { final client = testClient(api, storage: FileStorage(dir.path)); @@ -505,8 +517,8 @@ void main() { client.flush().catchError((Object _) {}); async.elapse(Duration.zero); client.close(); - response.complete(const PostHogResponse(HttpStatus.tooManyRequests, - headers: {'retry-after': '120'})); + response.complete(const PostHogResponse(HttpStatus.serviceUnavailable, + headers: {'retry-after': '20'})); async.flushMicrotasks(); expect(async.pendingTimers, isEmpty); expect(api.batchRequests, hasLength(1)); diff --git a/posthog_flutter/test/core/requests_test.dart b/posthog_flutter/test/core/requests_test.dart index 88e554ed..c5204a24 100644 --- a/posthog_flutter/test/core/requests_test.dart +++ b/posthog_flutter/test/core/requests_test.dart @@ -28,7 +28,7 @@ void main() { expect(request.headers['content-type'], 'application/json'); expect(request.headers['user-agent'], '$postHogFlutterSdkName/$postHogFlutterVersion'); - expect(request.body['api_key'], 'k'); + expect(request.headers['authorization'], 'Bearer k'); expect(request.eventNames, ['desktop_event']); }); @@ -61,8 +61,9 @@ void main() { test('respects HTTP Retry-After without waiting inside flush', () async { final client = testClient(server); - server.respond = (_) => const PostHogResponse(HttpStatus.tooManyRequests, - headers: {'Retry-After': '120'}); + server.respond = (_) => const PostHogResponse( + HttpStatus.serviceUnavailable, + headers: {'Retry-After': '20'}); client.capture('event'); await expectLater(client.flush().timeout(const Duration(seconds: 2)), @@ -122,8 +123,11 @@ void main() { return bodyCancellationDone.future; }, ); + // A 2xx whose body fails counts as delivered, so the status here is + // one that is retried. final request = _ControlledRequest( - response: _ControlledResponse(body.stream), + response: _ControlledResponse(body.stream, + statusCode: HttpStatus.serviceUnavailable), ); var openCalls = 0; final http = _ControlledHttpClient((_) async { @@ -158,6 +162,36 @@ void main() { client.close(); }); }); + + test('counts a 2xx whose body times out as delivered', () { + fakeAsync((async) { + // Cancelled in this zone: fake_async does not run the root zone's + // microtasks. + final body = + StreamController>(onCancel: () => Future.value()); + var openCalls = 0; + final http = _ControlledHttpClient((_) async { + openCalls++; + return _ControlledRequest(response: _ControlledResponse(body.stream)); + }); + final storage = tempStorage(); + late final client = HttpOverrides.runZoned( + () => testClient(server, storage: storage), + createHttpClient: (_) => http, + ); + client.capture('evt'); + var flushed = false; + client.flush().then((_) => flushed = true); + async.elapse(const Duration(seconds: 10)); + + expect(flushed, isTrue); + async.elapse(const Duration(seconds: 30)); + expect(openCalls, 1, + reason: 'a resend would store the events a second time'); + expect(getQueue(storage), isEmpty); + client.close(); + }); + }); }); } @@ -213,10 +247,10 @@ class _ControlledRequest implements HttpClientRequest { class _ControlledResponse extends StreamView> implements HttpClientResponse { - _ControlledResponse(super.stream); + _ControlledResponse(super.stream, {this.statusCode = HttpStatus.ok}); @override - int get statusCode => HttpStatus.ok; + final int statusCode; @override final headers = _ControlledHeaders(); diff --git a/posthog_flutter/test/posthog_api_fake.dart b/posthog_flutter/test/posthog_api_fake.dart index eb246b0b..312e0b36 100644 --- a/posthog_flutter/test/posthog_api_fake.dart +++ b/posthog_flutter/test/posthog_api_fake.dart @@ -24,7 +24,8 @@ class PostHogRequest { ); } - /// The path of the endpoint, such as `/batch/` or `/flags/`. + /// The path of the endpoint, such as `/i/v1/analytics/events` or + /// `/flags/`. final String path; /// The headers, by lowercase name. @@ -33,17 +34,18 @@ class PostHogRequest { /// The JSON body, decompressed and decoded. final Map body; - bool get isBatch => path == '/batch/'; + /// Whether this is a capture v1 request for analytics events. + bool get isBatch => path == '/i/v1/analytics/events'; bool get isFlags => path == '/flags/'; - /// The events of a `/batch/` request, oldest first. + /// The events of a capture request, oldest first. List> get events => [ for (final event in body['batch']! as List) Map.from(event as Map), ]; - /// The names of the events of a `/batch/` request, oldest first. + /// The names of the events of a capture request, oldest first. List get eventNames => [for (final event in events) event['event']]; } @@ -54,8 +56,22 @@ class PostHogResponse { : isDropped = false; /// A success with [json] as its body. - PostHogResponse.json(Object? json) - : this(HttpStatus.ok, body: jsonEncode(json)); + PostHogResponse.json(Object? json, {Map headers = const {}}) + : this(HttpStatus.ok, body: jsonEncode(json), headers: headers); + + /// A capture v1 success that answers each event of [request] with the + /// result [resultOf] gives its name, `ok` when it gives none. + factory PostHogResponse.results( + PostHogRequest request, + String? Function(Object? eventName) resultOf, { + Map headers = const {}, + }) => + PostHogResponse.json({ + 'results': { + for (final event in request.events) + '${event['uuid']}': {'result': resultOf(event['event']) ?? 'ok'}, + }, + }, headers: headers); /// No answer: the connection is closed instead. const PostHogResponse.dropped() diff --git a/posthog_flutter/test/posthog_desktop_transport_test.dart b/posthog_flutter/test/posthog_desktop_transport_test.dart index c36cfae2..12cadbc9 100644 --- a/posthog_flutter/test/posthog_desktop_transport_test.dart +++ b/posthog_flutter/test/posthog_desktop_transport_test.dart @@ -71,7 +71,7 @@ void main() { throw StateError('Unexpected directory access')); }); - test('facade sends a gzipped batch with envelope and event metadata', + test('facade sends a gzipped capture v1 batch with envelope and metadata', () async { await Posthog().setup(config(flushAt: 2)..preloadFeatureFlags = false); @@ -85,16 +85,21 @@ void main() { final request = server.batchRequests.single; expect(request.headers['content-encoding'], 'gzip'); expect(request.headers['content-type'], 'application/json'); - expect(request.body['api_key'], 'phc_transport'); - expect(DateTime.tryParse(request.body['sent_at']! as String), isNotNull); + expect(request.headers['authorization'], 'Bearer phc_transport'); + expect(request.headers['posthog-sdk-info'], + '$postHogFlutterSdkName/$postHogFlutterVersion'); + expect(request.body.keys, unorderedEquals(['created_at', 'batch'])); + expect(DateTime.tryParse(request.body['created_at']! as String), isNotNull); expect(request.eventNames, ['first event', 'second event']); for (final event in request.events) { expect(event['uuid'], isA()); expect(DateTime.tryParse(event['timestamp']! as String), isNotNull); expect(event['distinct_id'], isA()); + expect(event['session_id'], isA()); final properties = Map.from(event['properties']! as Map); - expect(properties[r'$lib'], postHogFlutterSdkName); + expect(properties, isNot(contains(r'$lib'))); + expect(properties, isNot(contains(r'$session_id'))); expect(properties[r'$device_type'], 'Desktop'); expect(properties[r'$app_version'], '1.2.3'); expect(properties[r'$app_build'], 42); diff --git a/posthog_flutter/test/posthog_flutter_desktop_test.dart b/posthog_flutter/test/posthog_flutter_desktop_test.dart index c2f51696..79b1f7c7 100644 --- a/posthog_flutter/test/posthog_flutter_desktop_test.dart +++ b/posthog_flutter/test/posthog_flutter_desktop_test.dart @@ -599,8 +599,8 @@ void main() { expect(seenProperties, {'plan': 'pro'}); // ...while the delivered event is still enriched after the hook ran. final properties = _propertiesOf(event); - expect(properties, containsPair(r'$lib', 'posthog-flutter')); - expect(properties.keys, contains(r'$session_id')); + expect(properties, containsPair(r'$device_type', 'Desktop')); + expect(event['session_id'], isA()); }); test('SDK-internal events bypass the callbacks', () async { From e4e5781e2a8039081c80f512bc36f56d88e4849d Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Tue, 27 Oct 2026 09:52:05 -0400 Subject: [PATCH 02/28] fix(desktop): log capture v1 per-event rejections Counts only: dropped and rate-limited events were deleted from the queue with no diagnostic, even in debug mode. Co-Authored-By: Claude Opus 5.5 --- posthog_flutter/lib/src/core/capture_v1.dart | 23 ++++++++++++++----- .../lib/src/core/posthog_core_stateless.dart | 9 +++++--- .../test/core/capture_v1_test.dart | 17 +++++++++++--- 3 files changed, 37 insertions(+), 12 deletions(-) diff --git a/posthog_flutter/lib/src/core/capture_v1.dart b/posthog_flutter/lib/src/core/capture_v1.dart index b8c29891..fd174f19 100644 --- a/posthog_flutter/lib/src/core/capture_v1.dart +++ b/posthog_flutter/lib/src/core/capture_v1.dart @@ -128,11 +128,15 @@ class CaptureV1Identity { } /// The uuids among [uuids] that a capture v1 response [body] asks to -/// retry, or null when the body has no readable per-event results. +/// retry, with how many of them it rejected (`drop` or `limited`), or null +/// when the body has no readable per-event results. /// /// `ok`, `warning`, `drop`, `limited` and any unknown result are final. /// An event missing from the results counts as delivered. -Set? captureV1RetryUuids(String? body, Iterable uuids) { +({Set retry, int rejected})? captureV1Results( + String? body, + Iterable uuids, +) { if (body == null) return null; final Object? results; try { @@ -142,10 +146,17 @@ Set? captureV1RetryUuids(String? body, Iterable uuids) { return null; } if (results is! Map) return null; - return { - for (final uuid in uuids) - if (results[uuid] case {'result': 'retry'}) uuid, - }; + final retry = {}; + var rejected = 0; + for (final uuid in uuids) { + switch (results[uuid]) { + case {'result': 'retry'}: + retry.add(uuid); + case {'result': 'drop' || 'limited'}: + rejected++; + } + } + return (retry: retry, rejected: rejected); } /// Whether two `Set`s hold the same elements. diff --git a/posthog_flutter/lib/src/core/posthog_core_stateless.dart b/posthog_flutter/lib/src/core/posthog_core_stateless.dart index 83b53561..ff78b29f 100644 --- a/posthog_flutter/lib/src/core/posthog_core_stateless.dart +++ b/posthog_flutter/lib/src/core/posthog_core_stateless.dart @@ -671,12 +671,15 @@ abstract class PostHogCoreStateless { ); } - var retryUuids = captureV1RetryUuids(response.body, uuids); - if (retryUuids == null) { + final results = captureV1Results(response.body, uuids); + if (results == null) { logger.info('Capture returned ${response.status} without readable ' 'per-event results; ${uuids.length} events count as delivered.'); - retryUuids = const {}; + } else if (results.rejected > 0) { + logger.warn('Capture dropped ${results.rejected} of ${uuids.length} ' + 'events for good.'); } + final retryUuids = results?.retry ?? const {}; _pendingCaptureIdentity = retryUuids.isEmpty ? null : identity.withUuids(retryUuids); return (retryUuids: retryUuids, retryAfter: response.retryAfter); diff --git a/posthog_flutter/test/core/capture_v1_test.dart b/posthog_flutter/test/core/capture_v1_test.dart index 3c86308c..585979ed 100644 --- a/posthog_flutter/test/core/capture_v1_test.dart +++ b/posthog_flutter/test/core/capture_v1_test.dart @@ -169,7 +169,8 @@ void main() { 'retried': 'retry', }; fakeAsync((async) { - final client = testClient(api, storage: storage); + final client = + testClient(api, config: testConfig(debug: true), storage: storage); results.keys.forEach(client.capture); // Left out of the results: counts as delivered. client.capture('missing'); @@ -186,10 +187,20 @@ void main() { }) : PostHogResponse.results(request, (_) => 'ok'); - client.flush(); - async.elapse(Duration.zero); + final lines = printedLines(() { + client.flush(); + async.elapse(Duration.zero); + }); expect(api.batchRequests, hasLength(1)); expect(queuedEvents(storage), ['retried']); + final uuids = [ + for (final event in api.batchRequests.single.events) event['uuid'], + ]; + final rejection = + lines.singleWhere((line) => line.contains('dropped 2 of 7')); + for (final uuid in uuids) { + expect(rejection, isNot(contains('$uuid'))); + } async.elapse(const Duration(seconds: 3)); expect(api.batchRequests, hasLength(2)); From cdaefeb912d38d9059dbab1515f02567760ea694 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Tue, 27 Oct 2026 17:08:36 -0400 Subject: [PATCH 03/28] docs: describe capture v1 for every platform in the 6.0 changeset Co-Authored-By: Claude Opus 5.5 --- .changeset/v6-desktop-capture-v1.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.changeset/v6-desktop-capture-v1.md b/.changeset/v6-desktop-capture-v1.md index 0f3c6c91..19d67a5b 100644 --- a/.changeset/v6-desktop-capture-v1.md +++ b/.changeset/v6-desktop-capture-v1.md @@ -2,5 +2,6 @@ "posthog_flutter": major --- -- **Breaking:** on Windows and Linux, events now go to capture v1 (`/i/v1/analytics/events`) instead of `/batch/`, like iOS and Android in 6.0. A reverse proxy or self-hosted instance must serve the new path: a 404 drops the events. Events queued before the upgrade are sent through the new endpoint +- **Breaking:** on every platform, events now go to capture v1 (`/i/v1/analytics/events`) instead of `/batch/`: iOS and macOS through `posthog-ios` 4.x, Android through `posthog-android` 4.x, and Windows and Linux in the Dart client. If you send events through your own reverse proxy, update it before you upgrade: forward `/i/v1/analytics/events` and `/i/v1/ai/events`, pass `Authorization` (the project token, sent as `Bearer `), every `PostHog-*` header, `Content-Type`, `Content-Encoding` and `User-Agent` through unchanged, and accept request bodies up to 20 MB. PostHog's managed reverse proxy already does this. See the [iOS](https://github.com/PostHog/posthog-ios/blob/main/docs/migration-3.x-to-4.0.md#hosts-without-capture-v1) and [Android](https://github.com/PostHog/posthog-android/blob/main/docs/migration-3.x-to-4.0.md#hosts-without-capture-v1) migration guides +- **Breaking:** on Windows and Linux, a reverse proxy or self-hosted instance must serve the new path: a 404 drops the events. Events queued before the upgrade are sent through the new endpoint - **Breaking:** on Windows and Linux, a 429 or a redirect drops the batch instead of retrying it (only same-origin 307/308 redirects are followed), and a `Retry-After` wait is capped at 30 seconds From e7eebbac83f11f609b7a9a075a03db9d075bc6b2 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Wed, 28 Oct 2026 11:51:48 -0400 Subject: [PATCH 04/28] fix(desktop): close capture v1 batches at 5 MiB of serialized events A batch closed only at maxBatchSize events, so large events could push a request past proxy and capture body limits. Each event's serialized size is now checked before it joins the batch; an event that doesn't fit starts the next one, and an event over the limit goes alone. Co-Authored-By: Claude Opus 5.5 --- posthog_flutter/lib/src/core/capture_v1.dart | 21 +++++++++++ .../lib/src/core/posthog_core_stateless.dart | 2 +- .../test/core/capture_v1_test.dart | 35 +++++++++++++++++++ .../test/core/queue_flush_test.dart | 23 ++++++++++++ 4 files changed, 80 insertions(+), 1 deletion(-) diff --git a/posthog_flutter/lib/src/core/capture_v1.dart b/posthog_flutter/lib/src/core/capture_v1.dart index fd174f19..1e5adc5b 100644 --- a/posthog_flutter/lib/src/core/capture_v1.dart +++ b/posthog_flutter/lib/src/core/capture_v1.dart @@ -1,10 +1,31 @@ import 'dart:convert'; +import 'file_storage.dart'; import 'logger.dart'; /// The capture v1 endpoint for analytics events. const captureV1Path = '/i/v1/analytics/events'; +/// The most serialized event bytes a capture v1 batch carries, so requests +/// stay under proxy and capture body limits. +const captureV1MaxBatchBytes = 5 * 1024 * 1024; + +/// The oldest events of [events] whose serialized size stays within +/// [maxBytes]. Each event is checked before it is added, so one that does +/// not fit starts the next batch, and the first event always goes, alone +/// when it is over the limit. +List takeCaptureV1Batch( + List events, { + int maxBytes = captureV1MaxBatchBytes, +}) { + var bytes = 0; + for (var i = 0; i < events.length; i++) { + bytes += utf8.encode(jsonEncode(events[i].event)).length; + if (i > 0 && bytes > maxBytes) return events.sublist(0, i); + } + return events; +} + /// Capture v1 statuses worth retrying. Everything else is terminal, /// including 429 and 3xx; 413 halves the batch instead. bool isRetriableCaptureV1Status(int status) => diff --git a/posthog_flutter/lib/src/core/posthog_core_stateless.dart b/posthog_flutter/lib/src/core/posthog_core_stateless.dart index ff78b29f..601f7e72 100644 --- a/posthog_flutter/lib/src/core/posthog_core_stateless.dart +++ b/posthog_flutter/lib/src/core/posthog_core_stateless.dart @@ -520,7 +520,7 @@ abstract class PostHogCoreStateless { while (!_closed) { // Peeked again after every request, so events queued in the meantime // go out with the same flush. - final batch = queue.peek(_maxBatchSize); + final batch = takeCaptureV1Batch(queue.peek(_maxBatchSize)); if (batch.isEmpty) { if (queue.length > 0) _scheduleFlush(); break; diff --git a/posthog_flutter/test/core/capture_v1_test.dart b/posthog_flutter/test/core/capture_v1_test.dart index 585979ed..87b280ed 100644 --- a/posthog_flutter/test/core/capture_v1_test.dart +++ b/posthog_flutter/test/core/capture_v1_test.dart @@ -95,6 +95,41 @@ void main() { }); }); + group('takeCaptureV1Batch', () { + PostHogQueuedEvent queued(String id, String padding) => + (id: id, event: {'p': padding}); + + test('closes the batch before the event that would pass the limit', () { + // Each event serializes to `{"p":""}`, 18 bytes here. + final events = [ + queued('a', 'x' * 10), + queued('b', 'x' * 10), + queued('c', 'x' * 10), + ]; + + final batch = takeCaptureV1Batch(events, maxBytes: 18 * 2); + + expect(batch.map((e) => e.id), ['a', 'b']); + }); + + test('sends an event over the limit alone', () { + final events = [queued('a', 'x' * 100), queued('b', 'x')]; + + final batch = takeCaptureV1Batch(events, maxBytes: 50); + + expect(batch.map((e) => e.id), ['a']); + }); + + test('counts UTF-8 bytes, not characters', () { + // Each event serializes to 18 characters but 28 bytes. + final events = [queued('a', 'é' * 10), queued('b', 'é' * 10)]; + + final batch = takeCaptureV1Batch(events, maxBytes: 18 * 2); + + expect(batch.map((e) => e.id), ['a']); + }); + }); + group('captureV1Event', () { final logger = CoreLogger((_) {}); diff --git a/posthog_flutter/test/core/queue_flush_test.dart b/posthog_flutter/test/core/queue_flush_test.dart index eefb746d..48f6aaa8 100644 --- a/posthog_flutter/test/core/queue_flush_test.dart +++ b/posthog_flutter/test/core/queue_flush_test.dart @@ -613,6 +613,29 @@ void main() { expect(getQueue(storage), isEmpty); }); }); + + test('closes a batch at 5 MiB of serialized events', () { + final api = InProcessPostHogApi(); + final storage = tempStorage(); + fakeAsync((async) { + final client = testClient(api, storage: storage); + final padding = 'x' * (2 * 1024 * 1024); + + for (var i = 0; i < 3; i++) { + client.capture('event_$i', properties: {'padding': padding}); + } + client.flush(); + async.elapse(Duration.zero); + + expect([ + for (final request in api.batchRequests) request.eventNames + ], [ + ['event_0', 'event_1'], + ['event_2'], + ]); + expect(getQueue(storage), isEmpty); + }); + }); }); group('Queue persistence', () { From 22d3e0ed4a8a024757005bd40bb44b2484ad7d80 Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Wed, 28 Oct 2026 16:27:54 -0400 Subject: [PATCH 05/28] fix: retry desktop capture v1 requests that get 404 or 429 (#678) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix: retry desktop capture v1 requests that get 404 or 429 A 404 usually means a misconfigured proxy and a 429 an overloaded Envoy; both are worth retrying with the same backoff, Retry-After handling and retry budget. Redirects stay terminal. * fix: back off across failed desktop flushes and warn once on a capture 404 After a batch fails its retries, later flushes make one attempt each and pause 6s doubling to 30s until a batch is delivered. Before, every flush, including the one each capture starts at flushAt, sent 4 requests, so a missing capture route kept resending the batch. A 404 prints one warning per client even without debug, naming the URL and the path a proxy or self-hosted instance must serve. * fix: leave the host out of the capture 404 warning A host with proxy credentials in its userinfo would print them to app logs. * fix(desktop): back off capture v1 retries like posthog-ios and posthog-android A transient failure or a 2xx whose per-event results ask to retry no longer resends within the flush (3 tries, 3 s apart). Each one pauses the queue for 1 s doubling to 30 s, with ±25% jitter from an injectable source. A Retry-After is a floor applied after the jitter, capped at 30 s, instead of replacing the backoff, so `Retry-After: 1` no longer resends every 3 s. A delivered or dropped batch resets the backoff. Co-Authored-By: Claude Opus 5.5 * fix(desktop): time out capture requests on inactivity, not on total duration The 10 s whole-call timeout could fail a large batch on a slow uplink on every attempt. A request now fails only after 10 s without progress: connecting (HttpClient.connectionTimeout), the socket taking a 64 KiB body chunk, the response headers, or a response body chunk. This is the closest dart:io gets to the per-read/per-write idle timeouts of OkHttp and URLSession: like them, it can't see the bytes still in the kernel send buffer, so the wait for headers starts once the last chunk is handed over. Co-Authored-By: Claude Opus 5.5 * fix(desktop): halve flushAt with the batch size on 413 and end the flush A 413 halved only the batch size and resent at once in the same flush. Like posthog-ios and posthog-android, it now also halves flushAt, kept within the batch size, and the smaller batches go out with the next flush (the next capture over flushAt, or the periodic flush). No backoff is added: posthog-ios ends the flush without one; posthog-android pauses. Co-Authored-By: Claude Opus 5.5 * fix(desktop): flush once 5 MiB of events are queued Like posthog-ios and posthog-android, a full capture v1 request's worth of queued bytes (captureV1MaxBatchBytes) now flushes as flushAt does, so a few large events go out before the queue starts dropping them. The file queue keeps each event's serialized size: measured when it is added, and read from the file sizes when a later process loads the queue. Co-Authored-By: Claude Opus 5.5 * fix(desktop): cap the response body read at 30 seconds A body that trickles in more often than the 10 s idle timeout reset it forever, holding the flush. The body now also fails after 30 s in total. Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --- .changeset/v6-desktop-capture-v1.md | 5 +- posthog_flutter/lib/src/core/capture_v1.dart | 4 +- .../lib/src/core/file_storage.dart | 45 ++- .../lib/src/core/posthog_core_stateless.dart | 300 ++++++++++++------ .../test/core/capture_v1_test.dart | 102 +++++- .../test/core/file_queue_test.dart | 26 ++ .../test/core/queue_flush_test.dart | 240 +++++++++++--- posthog_flutter/test/core/requests_test.dart | 149 ++++++++- posthog_flutter/test/core/test_client.dart | 6 +- posthog_flutter/test/posthog_api_fake.dart | 6 + 10 files changed, 716 insertions(+), 167 deletions(-) diff --git a/.changeset/v6-desktop-capture-v1.md b/.changeset/v6-desktop-capture-v1.md index 19d67a5b..644d4aa4 100644 --- a/.changeset/v6-desktop-capture-v1.md +++ b/.changeset/v6-desktop-capture-v1.md @@ -3,5 +3,6 @@ --- - **Breaking:** on every platform, events now go to capture v1 (`/i/v1/analytics/events`) instead of `/batch/`: iOS and macOS through `posthog-ios` 4.x, Android through `posthog-android` 4.x, and Windows and Linux in the Dart client. If you send events through your own reverse proxy, update it before you upgrade: forward `/i/v1/analytics/events` and `/i/v1/ai/events`, pass `Authorization` (the project token, sent as `Bearer `), every `PostHog-*` header, `Content-Type`, `Content-Encoding` and `User-Agent` through unchanged, and accept request bodies up to 20 MB. PostHog's managed reverse proxy already does this. See the [iOS](https://github.com/PostHog/posthog-ios/blob/main/docs/migration-3.x-to-4.0.md#hosts-without-capture-v1) and [Android](https://github.com/PostHog/posthog-android/blob/main/docs/migration-3.x-to-4.0.md#hosts-without-capture-v1) migration guides -- **Breaking:** on Windows and Linux, a reverse proxy or self-hosted instance must serve the new path: a 404 drops the events. Events queued before the upgrade are sent through the new endpoint -- **Breaking:** on Windows and Linux, a 429 or a redirect drops the batch instead of retrying it (only same-origin 307/308 redirects are followed), and a `Retry-After` wait is capped at 30 seconds +- **Breaking:** on Windows and Linux, a reverse proxy or self-hosted instance must serve the new path: a 404 is retried, the events stay queued, and the SDK prints a warning once, also without `debug`. Events queued before the upgrade are sent through the new endpoint +- **Breaking:** on Windows and Linux, a redirect drops the batch instead of retrying it (only same-origin 307/308 redirects are followed, while a 404 or 429 is retried), and a `Retry-After` wait is capped at 30 seconds +- On Windows and Linux, a failed batch, or one whose events the server asks to retry, is no longer resent within the same flush: the queue backs off like the iOS and Android SDKs, waiting 1 second and doubling up to 30 seconds with ±25% jitter, until a batch is delivered. A `Retry-After` is a floor under that wait rather than a replacement diff --git a/posthog_flutter/lib/src/core/capture_v1.dart b/posthog_flutter/lib/src/core/capture_v1.dart index 1e5adc5b..14e6d886 100644 --- a/posthog_flutter/lib/src/core/capture_v1.dart +++ b/posthog_flutter/lib/src/core/capture_v1.dart @@ -27,9 +27,11 @@ List takeCaptureV1Batch( } /// Capture v1 statuses worth retrying. Everything else is terminal, -/// including 429 and 3xx; 413 halves the batch instead. +/// including 3xx; 413 halves the batch instead. bool isRetriableCaptureV1Status(int status) => + status == 404 || status == 408 || + status == 429 || status == 500 || status == 502 || status == 503 || diff --git a/posthog_flutter/lib/src/core/file_storage.dart b/posthog_flutter/lib/src/core/file_storage.dart index 4c3a7402..96175bfc 100644 --- a/posthog_flutter/lib/src/core/file_storage.dart +++ b/posthog_flutter/lib/src/core/file_storage.dart @@ -310,6 +310,10 @@ class FileEventQueue { /// this client. final Map> _unwritten = {}; + /// The serialized size of each queued event, by id, and their total. + final Map _sizes = {}; + int _byteCount = 0; + List get _ids => _loadedIds ??= _load(); String _pathOf(String id) => @@ -319,7 +323,8 @@ class FileEventQueue { try { return [ for (final entity in Directory(_directory).listSync()) - if (entity is File && entity.path.endsWith(_extension)) _idOf(entity), + if (entity is File && entity.path.endsWith(_extension)) + _track(_idOf(entity), _lengthOf(entity)), ]..sort(); } on PathNotFoundException { return []; @@ -332,6 +337,22 @@ class FileEventQueue { } } + static int _lengthOf(File file) { + try { + return file.lengthSync(); + } on FileSystemException { + return 0; + } + } + + String _track(String id, int size) { + _sizes[id] = size; + _byteCount += size; + return id; + } + + void _untrack(String id) => _byteCount -= _sizes.remove(id) ?? 0; + static String _idOf(File file) { final name = file.uri.pathSegments.last; return name.substring(0, name.length - _extension.length); @@ -340,19 +361,31 @@ class FileEventQueue { /// The number of queued events. int get length => _ids.length; + /// The serialized size of the queued events, in bytes. + int get byteCount { + _ids; // Loads the queue, and the sizes, on first use. + return _byteCount; + } + /// Adds [event] at the end of the queue. void add(Map event) { // Loaded before the new file exists, which would otherwise be listed // on top of being added. final ids = _ids; final id = generateUuidV7(); - ids.add(id); + String? encoded; + try { + encoded = jsonEncode(event); + } catch (_) { + // Reported below when it is written. + } + ids.add(_track(id, encoded == null ? 0 : utf8.encode(encoded).length)); if (_directory.isEmpty) { _unwritten[id] = event; return; } try { - _writeAtomically(File(_pathOf(id)), jsonEncode(event)); + _writeAtomically(File(_pathOf(id)), encoded ?? jsonEncode(event)); } catch (e) { _unwritten[id] = event; _logger()?.warn( @@ -372,7 +405,10 @@ class FileEventQueue { final event = _unwritten[id] ?? _read(id, gone); if (event != null) events.add((id: id, event: event)); } - if (gone.isNotEmpty) _ids.removeWhere(gone.contains); + if (gone.isNotEmpty) { + _ids.removeWhere(gone.contains); + gone.forEach(_untrack); + } return events; } @@ -413,6 +449,7 @@ class FileEventQueue { } void _forget(String id) { + _untrack(id); if (_unwritten.remove(id) == null && _directory.isNotEmpty) { _delete(File(_pathOf(id))); } diff --git a/posthog_flutter/lib/src/core/posthog_core_stateless.dart b/posthog_flutter/lib/src/core/posthog_core_stateless.dart index 601f7e72..ee30b2df 100644 --- a/posthog_flutter/lib/src/core/posthog_core_stateless.dart +++ b/posthog_flutter/lib/src/core/posthog_core_stateless.dart @@ -1,7 +1,9 @@ import 'dart:async'; import 'dart:convert'; import 'dart:io'; +import 'dart:math'; +import 'package:flutter/foundation.dart' show debugPrint; import 'package:meta/meta.dart'; import '../posthog_config.dart'; @@ -52,12 +54,40 @@ bool _isRetryableFlagsError(Object err) => err is PostHogFetchNetworkError || (err is PostHogFetchHttpError && (err.status == 502 || err.status == 504)); +/// The largest fraction a capture retry wait moves either way, so clients +/// refused together don't all come back at the same moment. +const _retryJitter = 0.25; + +/// The wait before capture is sent again after the [attempt]-th failure in a +/// row: 1 second doubling up to 30 seconds, scaled by a jitter factor in +/// `[1 - _retryJitter, 1 + _retryJitter)` drawn from [jitterUnit] and capped +/// again. A server [retryAfter], capped at 30 seconds, is a floor applied +/// after the jitter, so a retry never comes earlier than the server asked. +/// A [jitterUnit] outside `[0, 1)` leaves the delay unjittered. +@visibleForTesting +Duration captureRetryDelay({ + required int attempt, + required double jitterUnit, + Duration? retryAfter, +}) { + const initialMs = 1000.0; + const maxMs = 30000.0; + final computed = + min(initialMs * pow(2, (attempt < 1 ? 1 : attempt) - 1), maxMs); + final factor = jitterUnit >= 0 && jitterUnit < 1 + ? 1 - _retryJitter + 2 * _retryJitter * jitterUnit + : 1.0; + final jittered = min(computed * factor, maxMs).round(); + final floor = min(retryAfter?.inMilliseconds ?? 0, maxMs.toInt()); + return Duration(milliseconds: jittered > floor ? jittered : floor); +} + /// Base stateless PostHog client: the queue of events, consent, super /// properties and the requests to PostHog. abstract class PostHogCoreStateless { final String _apiKey; final String _host; - final int _flushAt; + int _flushAt; int _maxBatchSize; final int _maxQueueSize; final Duration _flushInterval; @@ -65,17 +95,25 @@ abstract class PostHogCoreStateless { final bool _defaultOptIn; + /// How long a request may go without progress: connecting, a chunk of + /// the body taken by the socket, the response headers, or a chunk of the + /// response body. A slow but moving upload never times out. static const _requestTimeout = Duration(seconds: 10); - // A batch is retried after a transient failure; a flags request only after - // a network error or a gateway timeout. - static const _fetchRetryCount = 3; - static const _fetchRetryDelay = Duration(seconds: 3); + /// How long the response body may take in total, so a body that trickles + /// in without end can't hold the flush. + static const _responseBodyTimeout = Duration(seconds: 30); + + /// The size of the body chunks handed to the socket, each one progress. + static const _bodyChunkSize = 64 * 1024; + + // A flags request is retried only after a network error or a gateway + // timeout. A batch is not retried within a flush: the queue backs off. static const _flagsRetryCount = 1; static const _flagsRetryDelay = Duration(milliseconds: 300); - /// The longest `Retry-After` pause honored for events. - static const _maxRetryAfter = Duration(seconds: 30); + /// The [_failedFlushes] at which the backoff reaches its 30 second cap. + static const _maxBackoffStep = 6; /// How many same-origin 307/308 redirects a capture request follows. static const _maxCaptureRedirects = 5; @@ -84,6 +122,20 @@ abstract class PostHogCoreStateless { /// retried. Kept in memory: after a restart the retry is a new request. CaptureV1Identity? _pendingCaptureIdentity; + /// Flushes in a row whose batch failed with a transient error or had + /// events the server asked to retry. Each one pauses the queue for longer, + /// see [captureRetryDelay], so a failure that lasts, like a missing + /// capture route, doesn't resend the batch with every capture. A delivered + /// or dropped batch resets it. + int _failedFlushes = 0; + + /// The source of the backoff jitter: a uniform value in `[0, 1)`. + @visibleForTesting + double Function() jitterUnit = Random().nextDouble; + + /// Whether this client already warned that capture returned a 404. + bool _warnedCaptureNotFound = false; + /// The latest consent decision made through this client. It wins over the /// stored one: [clearPersistedOptOut] removes the stored decision while /// this client keeps honoring it, and a decision the storage cannot @@ -107,7 +159,8 @@ abstract class PostHogCoreStateless { @protected final FileStorage storage; - final _httpClient = HttpClient(); + final _httpClient = HttpClient() + ..connectionTimeout = PostHogCoreStateless._requestTimeout; PostHogCoreStateless( PostHogConfig config, { @@ -436,7 +489,9 @@ abstract class PostHogCoreStateless { events.emit(type, prepared); - if (queue.length >= _flushAt) { + // A full request's worth of bytes flushes like flushAt does, so large + // events go out before the queue starts dropping them. + if (queue.length >= _flushAt || queue.byteCount >= captureV1MaxBatchBytes) { _flushBackground(); } @@ -476,15 +531,22 @@ abstract class PostHogCoreStateless { _flushTimer = null; } - /// Stops sending events for [delay], the server's `Retry-After`, kept - /// between the retry delay and [_maxRetryAfter]. + /// Counts one more failed flush and stops sending events for the backoff + /// it calls for, at least the server's [retryAfter]. + void _backOff(Duration? retryAfter) { + if (_failedFlushes < _maxBackoffStep) _failedFlushes++; + _pauseFlush(captureRetryDelay( + attempt: _failedFlushes, + jitterUnit: jitterUnit(), + retryAfter: retryAfter, + )); + } + + /// Stops sending events for [delay]. void _pauseFlush(Duration delay) { _clearFlushTimer(); _retryAfterTimer?.cancel(); - final pause = delay < _fetchRetryDelay - ? _fetchRetryDelay - : (delay > _maxRetryAfter ? _maxRetryAfter : delay); - _retryAfterTimer = Timer(pause, () { + _retryAfterTimer = Timer(delay, () { _retryAfterTimer = null; if (!_closed && _flushInterval > Duration.zero && @@ -534,85 +596,80 @@ abstract class PostHogCoreStateless { } } - /// Sends [batch] to capture v1, retrying what is worth it, and removes - /// from the queue the events that are done: delivered, or dropped for - /// good. Adds the delivered ones to [sent]. + /// Sends [batch] to capture v1 and removes from the queue the events that + /// are done: delivered, or dropped for good. Adds the delivered ones to + /// [sent]. /// /// Returns whether the flush goes on with the rest of the queue. It stops - /// while events of [batch] wait for a later retry; the periodic flush or - /// the server's `Retry-After` sends them again. + /// while events of [batch] wait for a later retry: the queue backs off, + /// and sends them again once the pause is over. It also stops after a 413 + /// halves the batch size. Future _sendBatch( List batch, List> sent, ) async { final queue = storage.queue; - var pending = batch; - for (var attempt = 0;; attempt++) { - if (attempt > 0) { - await Future.delayed(_fetchRetryDelay); - // A client closed meanwhile leaves the queue to the next one. - if (_closed) return false; - } - - final Set retryUuids; - final Duration? retryAfter; - try { - (:retryUuids, :retryAfter) = await _postCaptureV1(pending); - } catch (e) { - if (_closed) rethrow; - if (e is PostHogFetchHttpError && - e.status == HttpStatus.requestEntityTooLarge && - pending.length > 1) { - _maxBatchSize = (pending.length ~/ 2).clamp(1, _maxBatchSize); - logger.warn('Received 413, reducing batch size to $_maxBatchSize'); - return true; - } - final transient = _isTransientCaptureError(e); - final retryAfter = e is PostHogFetchHttpError ? e.retryAfter : null; - if (transient && retryAfter == null && attempt < _fetchRetryCount) { - continue; - } - if (!transient) { - queue.remove([for (final queued in pending) queued.id]); - } - // Re-arm the periodic flush: otherwise queued events sit until the - // next capture (forever in an idle app after an offline failure). - if (transient && retryAfter != null) { - _pauseFlush(retryAfter); - } else { - _scheduleFlush(); - } - events.emit('error', e); - rethrow; - } - - final retained = [ - for (final queued in pending) - if (retryUuids.contains(queued.event['uuid'])) queued, - ]; - final delivered = [ - for (final queued in pending) - if (!retryUuids.contains(queued.event['uuid'])) queued, - ]; - // Removed by id: the queue may have changed while the batch was in - // flight, e.g. its oldest events dropped to make room. - queue.remove([for (final queued in delivered) queued.id]); - sent.addAll([for (final queued in delivered) queued.event]); - if (retained.isEmpty) return true; - - // Counts only: uuids and server details can identify users. - logger.info('Capture asked to retry ${retained.length} of ' - '${pending.length} events.'); - pending = retained; - if (retryAfter != null) { - _pauseFlush(retryAfter); + final Set retryUuids; + final Duration? retryAfter; + try { + (:retryUuids, :retryAfter) = await _postCaptureV1(batch); + } catch (e) { + if (_closed) rethrow; + if (e is PostHogFetchHttpError && + e.status == HttpStatus.requestEntityTooLarge && + batch.length > 1) { + // flushAt stays within the batch size, so the queue doesn't pile up + // more events than one batch can carry. + _maxBatchSize = (batch.length ~/ 2).clamp(1, _maxBatchSize); + _flushAt = (_flushAt ~/ 2).clamp(1, _maxBatchSize); + logger.warn('Received 413, reducing batch size to $_maxBatchSize'); + // The smaller batches go out with the next flush, not right away. + _scheduleFlush(); return false; } - if (attempt >= _fetchRetryCount) { + if (e is PostHogFetchHttpError && + e.status == HttpStatus.notFound && + !_warnedCaptureNotFound) { + _warnedCaptureNotFound = true; + // Printed even without debug: the events stay queued, and nothing + // else tells the app that the route is missing. + debugPrint('[PostHog] [WARN] $captureV1Path returned 404. ' + 'Events stay queued and are retried. If you use a reverse ' + 'proxy or self-host PostHog, make sure it serves ' + '$captureV1Path.'); + } + // The pause re-arms the periodic flush: otherwise queued events sit + // until the next capture (forever in an idle app after an offline + // failure). + if (_isTransientCaptureError(e)) { + _backOff(e is PostHogFetchHttpError ? e.retryAfter : null); + } else { + queue.remove([for (final queued in batch) queued.id]); + _failedFlushes = 0; _scheduleFlush(); - return false; } + events.emit('error', e); + rethrow; } + + final delivered = [ + for (final queued in batch) + if (!retryUuids.contains(queued.event['uuid'])) queued, + ]; + // Removed by id: the queue may have changed while the batch was in + // flight, e.g. its oldest events dropped to make room. + queue.remove([for (final queued in delivered) queued.id]); + sent.addAll([for (final queued in delivered) queued.event]); + if (delivered.length == batch.length) { + _failedFlushes = 0; + return true; + } + + // Counts only: uuids and server details can identify users. + logger.info('Capture asked to retry ${batch.length - delivered.length} ' + 'of ${batch.length} events.'); + _backOff(retryAfter); + return false; } /// Posts [batch] to capture v1 and returns the uuids of the events the @@ -742,10 +799,11 @@ abstract class PostHogCoreStateless { ); } - /// Sends one request, bounded by [_requestTimeout]. A transport failure - /// is thrown as [PostHogFetchNetworkError], except, with - /// [deliveredOnBodyFailure], one that happens after a 2xx status arrived: - /// the response is then returned without a body. + /// Sends one request, aborted once it makes no progress for + /// [_requestTimeout]. A transport failure is thrown as + /// [PostHogFetchNetworkError], except, with [deliveredOnBodyFailure], one + /// that happens after a 2xx status arrived: the response is then returned + /// without a body. Future< ({ int status, @@ -758,15 +816,9 @@ abstract class PostHogCoreStateless { Map headers = const {}, bool deliveredOnBodyFailure = false, }) async { - final attempt = _FetchAttempt(); + final attempt = _FetchAttempt(_requestTimeout, _responseBodyTimeout); try { - return await _fetch(url, body, attempt, headers).timeout( - _requestTimeout, - onTimeout: () async { - await attempt.cancel(); - throw attempt.timeout; - }, - ); + return await attempt.guard(_fetch(url, body, attempt, headers)); } catch (e) { final status = attempt.status; if (deliveredOnBodyFailure && @@ -834,9 +886,18 @@ abstract class PostHogCoreStateless { payload = bytes; } request.contentLength = payload.length; - request.add(payload); + // In chunks, so the socket taking each one counts as progress: it stops + // taking them while its buffers are full. + await request.addStream(() async* { + for (var start = 0; start < payload.length; start += _bodyChunkSize) { + attempt.progress(); + yield payload.sublist( + start, min(start + _bodyChunkSize, payload.length)); + } + }()); final response = await request.close(); + attempt.progress(); final retryAfter = _parseRetryAfter(response.headers.value(HttpHeaders.retryAfterHeader)); attempt @@ -866,7 +927,14 @@ abstract class PostHogCoreStateless { } class _FetchAttempt { + _FetchAttempt(this._idleTimeout, this._bodyTimeout); + + final Duration _idleTimeout; + final Duration _bodyTimeout; final timeout = TimeoutException('PostHog request timed out'); + Timer? _idleTimer; + Timer? _bodyTimer; + void Function()? _onIdle; HttpClientRequest? _request; @@ -877,7 +945,42 @@ class _FetchAttempt { Completer? _responseBody; bool _cancelled = false; + /// Completes with [work], or fails with [timeout] once the request has + /// made no [progress] for the idle timeout or its response body has taken + /// longer than the body timeout. The request is cancelled + /// before that failure is reported, so a retry never overlaps it. + Future guard(Future work) { + final result = Completer(); + var idle = false; + _onIdle = () async { + idle = true; + await cancel(); + if (!result.isCompleted) result.completeError(timeout); + }; + progress(); + work.then((value) { + if (!idle && !result.isCompleted) result.complete(value); + }, onError: (Object error, StackTrace stackTrace) { + if (!idle && !result.isCompleted) { + result.completeError(error, stackTrace); + } + }); + return result.future.whenComplete(() { + _idleTimer?.cancel(); + _bodyTimer?.cancel(); + }); + } + + /// Restarts the idle timeout. + void progress() { + _idleTimer?.cancel(); + if (_cancelled) return; + final onIdle = _onIdle; + if (onIdle != null) _idleTimer = Timer(_idleTimeout, onIdle); + } + void attachRequest(HttpClientRequest request) { + progress(); _request = request; if (_cancelled) { request.abort(timeout); @@ -886,12 +989,17 @@ class _FetchAttempt { } Future readBody(HttpClientResponse response) { + final onIdle = _onIdle; + if (onIdle != null) _bodyTimer = Timer(_bodyTimeout, onIdle); final contents = StringBuffer(); final body = Completer(); late final StreamSubscription subscription; subscription = response.transform(const Utf8Decoder(allowMalformed: true)).listen( - contents.write, + (chunk) { + progress(); + contents.write(chunk); + }, onError: (Object error, StackTrace stackTrace) { if (!body.isCompleted) body.completeError(error, stackTrace); }, diff --git a/posthog_flutter/test/core/capture_v1_test.dart b/posthog_flutter/test/core/capture_v1_test.dart index 87b280ed..65b35069 100644 --- a/posthog_flutter/test/core/capture_v1_test.dart +++ b/posthog_flutter/test/core/capture_v1_test.dart @@ -191,6 +191,38 @@ void main() { }); }); + group('captureRetryDelay', () { + Duration delay(int attempt, double unit, [int? retryAfterSeconds]) => + captureRetryDelay( + attempt: attempt, + jitterUnit: unit, + retryAfter: retryAfterSeconds == null + ? null + : Duration(seconds: retryAfterSeconds), + ); + + test('doubles from 1 second up to 30 seconds', () { + expect([for (var a = 1; a <= 7; a++) delay(a, 0.5).inSeconds], + [1, 2, 4, 8, 16, 30, 30]); + }); + + test('jitters by up to 25 percent and stays under 30 seconds', () { + expect(delay(1, 0), const Duration(milliseconds: 750)); + expect(delay(3, 0.75), const Duration(milliseconds: 4500)); + expect(delay(6, 0), const Duration(milliseconds: 22500)); + expect(delay(6, 0.999), const Duration(seconds: 30)); + expect(delay(1, double.nan), const Duration(seconds: 1)); + expect(delay(1, 1), const Duration(seconds: 1)); + }); + + test('takes Retry-After as a floor after the jitter, at most 30 s', () { + expect(delay(1, 0, 5), const Duration(seconds: 5)); + expect(delay(4, 0.5, 1), const Duration(seconds: 8)); + expect(delay(4, 0, 7), const Duration(seconds: 7)); + expect(delay(1, 0.5, 120), const Duration(seconds: 30)); + }); + }); + group('Capture v1 results', () { test('resends only the events the server asks to retry', () { final api = InProcessPostHogApi(); @@ -279,6 +311,43 @@ void main() { }); }); + test('a partial retry advances the backoff, a full delivery resets it', () { + final api = InProcessPostHogApi(); + final storage = tempStorage(); + var partial = 3; + api.respond = (request) => partial-- > 0 + ? PostHogResponse.results( + request, (name) => name == 'later' ? 'retry' : null) + : PostHogResponse.results(request, (_) => 'ok'); + fakeAsync((async) { + final client = testClient(api, storage: storage); + client.capture('now'); + client.capture('later'); + client.flush(); + async.elapse(Duration.zero); + + var now = Duration.zero; + var requests = 1; + for (final next in [1, 3, 7]) { + async.elapse(Duration(seconds: next) - now - _ms); + expect(api.batchRequests, hasLength(requests)); + async.elapse(_ms); + expect(api.batchRequests, hasLength(++requests)); + now = Duration(seconds: next); + } + expect(getQueue(storage), isEmpty); + + api.respond = (_) => const PostHogResponse(HttpStatus.badGateway); + client.capture('next'); + client.flush().catchError((Object _) {}); + async.elapse(const Duration(seconds: 1) - _ms); + expect(api.batchRequests, hasLength(5)); + async.elapse(_ms); + expect(api.batchRequests, hasLength(6), + reason: 'the backoff starts over at 1 second'); + }); + }); + test('starts a new request when new events join a retried batch', () { final api = InProcessPostHogApi(); final storage = tempStorage(); @@ -313,7 +382,7 @@ void main() { fakeAsync((async) { final client = testClient(api); client.capture('evt'); - client.flush(); + client.flush().catchError((Object _) {}); async.elapse(const Duration(seconds: 6)); final requests = api.batchRequests; @@ -353,20 +422,27 @@ void main() { expect(getQueue(storage), isEmpty); }); - test('drops the batch on 404 without falling back to /batch', () async { - final server = await LocalPostHogServer.start(); + test('retries a 404 without falling back to /batch', () { + final api = InProcessPostHogApi() + ..respond = (request) => request.isFlags + ? PostHogResponse.json({'flags': {}}) + : const PostHogResponse(HttpStatus.notFound); final storage = tempStorage(); - final client = testClient(server, storage: storage); - server.respond = (request) => request.isFlags - ? PostHogResponse.json({'flags': {}}) - : const PostHogResponse(HttpStatus.notFound); + fakeAsync((async) { + final client = testClient(api, storage: storage); + Object? error; - client.capture('evt'); - await expectLater(client.flush(), throwsA(isA())); + client.capture('evt'); + client.flush().catchError((Object e) { + error = e; + }); + async.elapse(const Duration(seconds: 9)); - expect([for (final r in server.requests) r.path], - ['/i/v1/analytics/events']); - expect(getQueue(storage), isEmpty); + expect(error, isA()); + expect([for (final r in api.requests) r.path], + List.filled(4, '/i/v1/analytics/events')); + expect(getQueue(storage), hasLength(1)); + }); }); }); @@ -456,3 +532,5 @@ void main() { expect(Directory('${dir.path}/posthog_queue').listSync(), isEmpty); }); } + +const _ms = Duration(milliseconds: 1); diff --git a/posthog_flutter/test/core/file_queue_test.dart b/posthog_flutter/test/core/file_queue_test.dart index 4da822af..75dfad4b 100644 --- a/posthog_flutter/test/core/file_queue_test.dart +++ b/posthog_flutter/test/core/file_queue_test.dart @@ -44,6 +44,32 @@ void main() { hasLength(1)); }); + test('counts the serialized bytes of the queued events', () { + int size(Map event) => + utf8.encode(jsonEncode(event)).length; + final first = {'event': 'first', 'padding': 'é' * 10}; + final second = {'event': 'second'}; + final third = {'event': 'third'}; + final storage = FileStorage(dir.path); + final queue = storage.queue + ..add(first) + ..add(second) + ..add(third); + expect(queue.byteCount, size(first) + size(second) + size(third)); + + queue.removeOldest(1); + expect(queue.byteCount, size(second) + size(third)); + + // Read back from the files by the next process. + storage.close(); + final next = FileStorage(dir.path); + addTearDown(next.close); + final restored = next.queue; + expect(restored.byteCount, size(second) + size(third)); + restored.remove([restored.peek(1).single.id]); + expect(restored.byteCount, size(third)); + }); + test('keeps the queue order across a restart', () async { final before = client(); for (var i = 0; i < 50; i++) { diff --git a/posthog_flutter/test/core/queue_flush_test.dart b/posthog_flutter/test/core/queue_flush_test.dart index 48f6aaa8..f5483cc5 100644 --- a/posthog_flutter/test/core/queue_flush_test.dart +++ b/posthog_flutter/test/core/queue_flush_test.dart @@ -2,6 +2,7 @@ import 'dart:async'; import 'dart:io'; import 'package:fake_async/fake_async.dart'; +import 'package:flutter/foundation.dart' show debugPrint; import 'package:flutter_test/flutter_test.dart'; import 'package:posthog_flutter/src/core/file_storage.dart'; import 'package:posthog_flutter/src/core/persistence.dart'; @@ -68,27 +69,67 @@ void main() { expect(getQueue(storage), isEmpty); }); - test('halves the batch size on HTTP 413 until the server accepts', - () async { + test('halves the batch size and flushAt on HTTP 413, sending next flush', + () { + final api = InProcessPostHogApi() + // This server rejects anything bigger than two events per request. + ..respond = (request) => PostHogResponse(request.events.length > 2 + ? HttpStatus.requestEntityTooLarge + : HttpStatus.ok); final storage = tempStorage(); - final client = testClient(server, storage: storage); - // This server rejects anything bigger than two events per request. - server.respond = (request) => PostHogResponse(request.events.length > 2 - ? HttpStatus.requestEntityTooLarge - : HttpStatus.ok); + fakeAsync((async) { + final client = testClient(api, + config: testConfig(flushAt: 10, maxBatchSize: 10), + storage: storage); + List sizes() => + [for (final request in api.batchRequests) request.events.length]; - for (var i = 0; i < 8; i++) { - client.capture('event_$i'); - } - await client.flush(); + for (var i = 0; i < 10; i++) { + client.capture('event_$i'); + } + async.elapse(Duration.zero); + expect(sizes(), [10], reason: 'a 413 ends the flush'); - final batches = [ - for (final request in server.batchRequests) request.eventNames, - ]; - expect(batches.map((batch) => batch.length).toList(), [8, 4, 2, 2, 2, 2]); - expect(batches.skip(2).expand((batch) => batch).toList(), - [for (var i = 0; i < 8; i++) 'event_$i']); - expect(getQueue(storage), isEmpty); + // flushAt is 5 now: the next capture flushes. + client.capture('event_10'); + async.elapse(Duration.zero); + expect(sizes(), [10, 5]); + + // flushAt is 2 now, as is the batch size. + client.capture('event_11'); + async.elapse(Duration.zero); + expect(sizes(), [10, 5, 2, 2, 2, 2, 2, 2]); + expect(api.batchRequests.skip(2).expand((r) => r.eventNames).toList(), + [for (var i = 0; i < 12; i++) 'event_$i']); + expect(getQueue(storage), isEmpty); + + client.capture('event_12'); + async.elapse(Duration.zero); + expect(getQueue(storage), hasLength(1), + reason: 'flushAt stays at 2 after the deliveries'); + }); + }); + + test('sends the halved batches with the periodic flush after a 413', () { + final api = InProcessPostHogApi() + ..respond = (request) => PostHogResponse(request.events.length > 2 + ? HttpStatus.requestEntityTooLarge + : HttpStatus.ok); + final storage = tempStorage(); + fakeAsync((async) { + final client = testClient(api, storage: storage); + for (var i = 0; i < 4; i++) { + client.capture('event_$i'); + } + client.flush(); + async.elapse(Duration.zero); + expect(api.batchRequests, hasLength(1)); + expect(getQueue(storage), hasLength(4)); + + async.elapse(const Duration(seconds: 30)); + expect([for (final r in api.batchRequests) r.events.length], [4, 2, 2]); + expect(getQueue(storage), isEmpty); + }); }); test('shares one network cycle between concurrent calls', () async { @@ -122,7 +163,8 @@ void main() { expect(getQueue(storage), isEmpty); }); - test('retries a transient failure three times, three seconds apart', () { + test('backs off 1, 2, 4, 8, 16, then 30 seconds after transient failures', + () { final api = InProcessPostHogApi() ..respond = (_) => const PostHogResponse(HttpStatus.serviceUnavailable); final storage = tempStorage(); @@ -136,20 +178,42 @@ void main() { }); async.elapse(Duration.zero); + expect(error, isA(), + reason: 'a flush does not wait for the backoff'); expect(api.batchRequests, hasLength(1)); - for (final attempts in [2, 3, 4]) { - async.elapse(const Duration(milliseconds: 2999)); - expect(api.batchRequests, hasLength(attempts - 1)); - async.elapse(const Duration(milliseconds: 1)); - expect(api.batchRequests, hasLength(attempts)); + var now = Duration.zero; + var requests = 1; + for (final next in [1, 3, 7, 15, 31, 61, 91]) { + async.elapse(Duration(seconds: next) - now - _ms); + expect(api.batchRequests, hasLength(requests)); + async.elapse(_ms); + expect(api.batchRequests, hasLength(++requests)); + now = Duration(seconds: next); } - expect(error, isA()); expect(getQueue(storage), hasLength(1)); }); }); - for (final status in [408, 500, 502, 503, 504]) { - test('HTTP $status keeps the batch queued after the retries', () { + test('jitters the backoff by up to 25 percent either way', () { + for (final (unit, first) in [(0.0, 750), (0.999, 1250)]) { + final api = InProcessPostHogApi() + ..respond = + (_) => const PostHogResponse(HttpStatus.serviceUnavailable); + fakeAsync((async) { + final client = testClient(api, jitterUnit: unit); + client.capture('evt'); + client.flush().catchError((Object _) {}); + async.elapse(Duration(milliseconds: first - 1)); + expect(api.batchRequests, hasLength(1), reason: 'unit $unit'); + async.elapse(_ms); + expect(api.batchRequests, hasLength(2), reason: 'unit $unit'); + client.close(); + }); + } + }); + + for (final status in [404, 408, 429, 500, 502, 503, 504]) { + test('HTTP $status keeps the batch queued and backs off', () { final api = InProcessPostHogApi() ..respond = (_) => PostHogResponse(status); final storage = tempStorage(); @@ -170,9 +234,7 @@ void main() { }); } - // Capture v1 retries only the statuses above: a rate limit, a redirect - // it does not follow, or a missing route fails the same way again. - for (final status in [301, 302, 307, 308, 401, 403, 404, 429, 501]) { + for (final status in [301, 302, 307, 308, 401, 403, 501]) { test('HTTP $status drops the batch without a retry', () { final api = InProcessPostHogApi() ..respond = (_) => PostHogResponse(status, @@ -219,16 +281,60 @@ void main() { }); }); + test('a delivered batch resets the backoff', () { + final api = InProcessPostHogApi(); + var status = HttpStatus.notFound; + api.respond = (_) => PostHogResponse(status); + final storage = tempStorage(); + fakeAsync((async) { + final client = + testClient(api, storage: storage, config: testConfig(flushAt: 1)); + + client.capture('first'); + async.elapse(const Duration(seconds: 9)); + status = HttpStatus.ok; + async.elapse(const Duration(seconds: 6)); + expect(api.batchRequests, hasLength(5)); + expect(getQueue(storage), isEmpty); + + status = HttpStatus.serviceUnavailable; + client.capture('second'); + async.elapse(const Duration(seconds: 9)); + expect(api.batchRequests, hasLength(9)); + }); + }); + + test('warns once about a 404, also without debug', () { + final printed = []; + final originalDebugPrint = debugPrint; + debugPrint = (String? message, {int? wrapWidth}) => printed.add(message); + addTearDown(() => debugPrint = originalDebugPrint); + final api = InProcessPostHogApi() + ..respond = (_) => const PostHogResponse(HttpStatus.notFound); + fakeAsync((async) { + final client = testClient(api, config: testConfig(flushAt: 1)); + + client.capture('evt'); + async.elapse(const Duration(seconds: 60)); + + expect(api.batchRequests.length, greaterThan(4)); + expect(printed, [ + '[PostHog] [WARN] /i/v1/analytics/events returned 404. ' + 'Events stay queued and are retried. If you use a reverse ' + 'proxy or self-host PostHog, make sure it serves ' + '/i/v1/analytics/events.', + ]); + }); + }); + test('the timer firing while a flush is in flight stays re-armable', () { final api = InProcessPostHogApi(); final storage = tempStorage(); fakeAsync((async) { final release = Completer(); - var online = false; api.respond = (_) async { await release.future; - return PostHogResponse( - online ? HttpStatus.ok : HttpStatus.serviceUnavailable); + return const PostHogResponse(HttpStatus.ok); }; final client = testClient(api, config: testConfig(flushInterval: const Duration(milliseconds: 20)), @@ -241,22 +347,20 @@ void main() { client.capture('second'); async.elapse(const Duration(milliseconds: 60)); release.complete(); - // The flush and its retries fail. - async.elapse(const Duration(seconds: 9)); - expect(api.batchRequests, hasLength(4)); + async.elapse(Duration.zero); + expect(getQueue(storage), isEmpty); - online = true; + client.capture('third'); async.elapse(const Duration(milliseconds: 20)); - expect(api.batchRequests.last.eventNames, ['first', 'second'], + expect(api.batchRequests.last.eventNames, ['third'], reason: 'only a re-armed timer sends the queue again'); - expect(getQueue(storage), isEmpty); }); }); }); group('Retry-After', () { - for (final status in [503]) { + for (final status in [429, 503]) { test('HTTP $status pauses every send path and resumes the queue', () { final api = InProcessPostHogApi(); final storage = tempStorage(); @@ -308,7 +412,7 @@ void main() { '', 'Sun, 06 Nov 1994 08:49:37 GMT', ]) { - test('ignores Retry-After "$header" and keeps three retries', () { + test('ignores Retry-After "$header" and backs off as without it', () { final api = InProcessPostHogApi() ..respond = (_) => PostHogResponse(HttpStatus.serviceUnavailable, headers: {'retry-after': header}); @@ -459,27 +563,40 @@ void main() { }); }); - test('a new rate limit starts a new pause with the minimum delay', () { + test('Retry-After is a floor under the backoff, not a replacement', () { final api = InProcessPostHogApi() ..respond = (_) => const PostHogResponse(HttpStatus.serviceUnavailable, - headers: {'retry-after': '20'}); + headers: {'retry-after': '5'}); final storage = tempStorage(); fakeAsync((async) { final client = testClient(api, storage: storage); client.capture('event'); client.flush().catchError((Object _) {}); async.elapse(Duration.zero); + // Over the 1 second backoff: the server's 5 seconds win. + async.elapse(const Duration(seconds: 5) - _ms); + expect(api.batchRequests, hasLength(1)); + async.elapse(_ms); + expect(api.batchRequests, hasLength(2)); + // 2, then 4 seconds of backoff are under it: 5 seconds again, then + // the 8 seconds of the 4th failure are over it. + async.elapse(const Duration(seconds: 10)); + expect(api.batchRequests, hasLength(4)); api.respond = (_) => const PostHogResponse( HttpStatus.serviceUnavailable, headers: {'retry-after': '1'}); - async.elapse(const Duration(seconds: 20)); - expect(api.batchRequests, hasLength(2)); + async.elapse(const Duration(seconds: 8) - _ms); + expect(api.batchRequests, hasLength(4)); + async.elapse(_ms); + expect(api.batchRequests, hasLength(5)); + + // A short Retry-After does not resend every second: the 5th + // failure's 16 second backoff wins. api.respond = (_) => const PostHogResponse(HttpStatus.ok); - client.flush(); - async.elapse(const Duration(milliseconds: 2999)); - expect(api.batchRequests, hasLength(2)); - async.elapse(const Duration(milliseconds: 1)); - expect(api.batchRequests, hasLength(3)); + async.elapse(const Duration(seconds: 16) - _ms); + expect(api.batchRequests, hasLength(5)); + async.elapse(_ms); + expect(api.batchRequests, hasLength(6)); expect(getQueue(storage), isEmpty); }); }); @@ -614,6 +731,27 @@ void main() { }); }); + test('flushes once 5 MiB of serialized events are queued', () { + final api = InProcessPostHogApi(); + final storage = tempStorage(); + fakeAsync((async) { + final client = testClient(api, storage: storage); + final padding = 'x' * (2 * 1024 * 1024 + 512 * 1024); + + client.capture('event_0', properties: {'padding': padding}); + async.elapse(Duration.zero); + expect(api.batchRequests, isEmpty); + + client.capture('event_1', properties: {'padding': padding}); + async.elapse(Duration.zero); + expect( + [for (final r in api.batchRequests) r.eventNames].expand((n) => n), + ['event_0', 'event_1'], + reason: 'well below flushAt and before the periodic flush'); + expect(getQueue(storage), isEmpty); + }); + }); + test('closes a batch at 5 MiB of serialized events', () { final api = InProcessPostHogApi(); final storage = tempStorage(); @@ -837,3 +975,5 @@ void main() { }); }); } + +const _ms = Duration(milliseconds: 1); diff --git a/posthog_flutter/test/core/requests_test.dart b/posthog_flutter/test/core/requests_test.dart index c5204a24..004768ce 100644 --- a/posthog_flutter/test/core/requests_test.dart +++ b/posthog_flutter/test/core/requests_test.dart @@ -1,9 +1,12 @@ import 'dart:async'; +import 'dart:convert'; import 'dart:io'; +import 'dart:math'; import 'package:fake_async/fake_async.dart'; import 'package:flutter_test/flutter_test.dart'; import 'package:posthog_flutter/src/core/posthog_core_stateless.dart'; +import 'package:posthog_flutter/src/posthog_desktop_client.dart'; import 'package:posthog_flutter/src/posthog_flutter_version.dart'; import '../posthog_api_fake.dart'; @@ -163,6 +166,122 @@ void main() { }); }); + test('keeps a slow upload that makes progress going past 10 seconds', () { + fakeAsync((async) { + late final _ControlledRequest request; + final http = + _ControlledHttpClient((_) async => request = _ControlledRequest( + takeChunk: () => + Future.delayed(const Duration(seconds: 6)), + )); + final storage = tempStorage(); + late final client = HttpOverrides.runZoned( + () => testClient(server, storage: storage), + createHttpClient: (_) => http, + ); + _captureLargeEvent(client); + Object? error; + var flushed = false; + client.flush().then((_) => flushed = true, onError: (Object e) { + error = e; + }); + async.elapse(const Duration(seconds: 60)); + + expect(request.chunks, greaterThan(2)); + expect(error, isNull); + expect(flushed, isTrue); + expect(request.abortCalls, 0); + expect(getQueue(storage), isEmpty); + }); + }); + + test('times out an upload that stalls for 10 seconds', () { + fakeAsync((async) { + final stalled = Completer(); + var taken = 0; + final request = _ControlledRequest( + takeChunk: () => taken++ == 0 ? Future.value() : stalled.future, + ); + final http = _ControlledHttpClient((_) async => request); + final storage = tempStorage(); + late final client = HttpOverrides.runZoned( + () => testClient(server, storage: storage), + createHttpClient: (_) => http, + ); + _captureLargeEvent(client); + Object? error; + client.flush().catchError((Object e) { + error = e; + }); + async.elapse(const Duration(seconds: 10) - _ms); + expect(error, isNull); + async.elapse(_ms); + + expect(error, isA()); + expect(request.abortCalls, 1); + expect(getQueue(storage), hasLength(1)); + client.close(); + }); + }); + + test('keeps a response that trickles in going past 10 seconds', () { + fakeAsync((async) { + final body = StreamController>(); + final http = _ControlledHttpClient((_) async => + _ControlledRequest(response: _ControlledResponse(body.stream))); + late final client = HttpOverrides.runZoned( + () => testClient(server), + createHttpClient: (_) => http, + ); + client.capture('evt'); + Object? error; + var flushed = false; + client.flush().then((_) => flushed = true, onError: (Object e) { + error = e; + }); + for (var i = 0; i < 4; i++) { + async.elapse(const Duration(seconds: 6)); + body.add(utf8.encode(' ')); + } + body.close(); + async.flushMicrotasks(); + + expect(error, isNull); + expect(flushed, isTrue); + }); + }); + + test('times out a response that trickles in for 30 seconds', () { + fakeAsync((async) { + final body = + StreamController>(onCancel: () => Future.value()); + final http = _ControlledHttpClient((_) async => _ControlledRequest( + response: _ControlledResponse(body.stream, + statusCode: HttpStatus.serviceUnavailable))); + final storage = tempStorage(); + late final client = HttpOverrides.runZoned( + () => testClient(server, storage: storage), + createHttpClient: (_) => http, + ); + client.capture('evt'); + Object? error; + client.flush().catchError((Object e) { + error = e; + }); + for (var i = 0; i < 5; i++) { + async.elapse(const Duration(seconds: 6) - _ms); + body.add(utf8.encode(' ')); + } + async.flushMicrotasks(); + expect(error, isNull); + async.elapse(const Duration(seconds: 1)); + + expect(error, isA()); + expect(getQueue(storage), hasLength(1)); + client.close(); + }); + }); + test('counts a 2xx whose body times out as delivered', () { fakeAsync((async) { // Cancelled in this zone: fake_async does not run the root zone's @@ -203,6 +322,9 @@ class _ControlledHttpClient implements HttpClient { @override Future postUrl(Uri url) => openRequest(url); + @override + Duration? connectionTimeout; + @override void close({bool force = false}) {} @@ -211,12 +333,17 @@ class _ControlledHttpClient implements HttpClient { } class _ControlledRequest implements HttpClientRequest { - _ControlledRequest({HttpClientResponse? response}) + _ControlledRequest({HttpClientResponse? response, this.takeChunk}) : _response = response ?? _ControlledResponse(Stream.value([])); final HttpClientResponse _response; + + /// How long the socket takes to accept each body chunk; immediate when + /// null. + final Future Function()? takeChunk; int abortCalls = 0; int closeCalls = 0; + int chunks = 0; @override final headers = _ControlledHeaders(); @@ -230,6 +357,14 @@ class _ControlledRequest implements HttpClientRequest { @override void add(List data) {} + @override + Future addStream(Stream> stream) async { + await for (final _ in stream) { + await takeChunk?.call(); + chunks++; + } + } + @override void abort([Object? exception, StackTrace? stackTrace]) { abortCalls++; @@ -245,6 +380,16 @@ class _ControlledRequest implements HttpClientRequest { dynamic noSuchMethod(Invocation invocation) => super.noSuchMethod(invocation); } +/// A request whose body is several 64 KiB chunks once compressed: random +/// text does not compress much. +void _captureLargeEvent(DesktopPostHog client) { + final random = Random(1); + client.capture('large', properties: { + 'padding': + base64.encode([for (var i = 0; i < 200000; i++) random.nextInt(256)]), + }); +} + class _ControlledResponse extends StreamView> implements HttpClientResponse { _ControlledResponse(super.stream, {this.statusCode = HttpStatus.ok}); @@ -269,3 +414,5 @@ class _ControlledHeaders implements HttpHeaders { @override dynamic noSuchMethod(Invocation invocation) => super.noSuchMethod(invocation); } + +const _ms = Duration(milliseconds: 1); diff --git a/posthog_flutter/test/core/test_client.dart b/posthog_flutter/test/core/test_client.dart index 62a96f13..5af59e7f 100644 --- a/posthog_flutter/test/core/test_client.dart +++ b/posthog_flutter/test/core/test_client.dart @@ -44,13 +44,16 @@ FileStorage tempStorage() => FileStorage(tempDirectory().path); /// A client of [api] with [config], closed at the end of the test. It keeps /// its state in [storage], a new temporary directory by default, and -/// attaches [context] and [timezone] to its events. +/// attaches [context] and [timezone] to its events. Its backoff has no +/// jitter unless [jitterUnit] says otherwise, so retries come 1, 2, 4, 8, 16 +/// and then 30 seconds apart. DesktopPostHog testClient( PostHogApiFake api, { PostHogConfig? config, FileStorage? storage, Map context = const {}, String? timezone, + double jitterUnit = 0.5, }) { final client = api.connect( () => DesktopPostHog( @@ -60,6 +63,7 @@ DesktopPostHog testClient( timezone: timezone, ), ); + client.jitterUnit = () => jitterUnit; addTearDown(client.close); return client; } diff --git a/posthog_flutter/test/posthog_api_fake.dart b/posthog_flutter/test/posthog_api_fake.dart index 312e0b36..b2c7646c 100644 --- a/posthog_flutter/test/posthog_api_fake.dart +++ b/posthog_flutter/test/posthog_api_fake.dart @@ -254,6 +254,9 @@ class _InProcessHttpClient implements HttpClient { Future postUrl(Uri url) async => _InProcessRequest(_api, url); + @override + Duration? connectionTimeout; + @override void close({bool force = false}) {} @@ -283,6 +286,9 @@ class _InProcessRequest implements HttpClientRequest { @override void add(List data) => _body.addAll(data); + @override + Future addStream(Stream> stream) => stream.forEach(add); + @override void abort([Object? exception, StackTrace? stackTrace]) { if (!_aborted.isCompleted) { From cf0d1e20db19556cb1bdcf5d4a5e1abb41a029b3 Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Thu, 29 Oct 2026 17:05:41 -0400 Subject: [PATCH 06/28] feat(desktop): captureAi on the AI endpoint, native property order and options passthrough (#679) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * chore!: adopt posthog-ios 4.0 - Require posthog-ios 4.x. - Adapt to the reloadFeatureFlags(_:) callback that now passes a PostHogFeatureFlagsLoaded (PostHog/posthog-ios#913). - Note the payload decoding changes from PostHog/posthog-ios#903. Co-Authored-By: Claude Opus 5.5 (1M context) * docs(changeset): note posthog-ios 4.0 drops lifecycle version and build PostHog/posthog-ios#905 removes the legacy version/build properties from lifecycle events in 4.0, so Flutter iOS and macOS apps stop sending them. Co-Authored-By: Claude Opus 5.5 (1M context) * chore(ios): drive onFeatureFlags from the posthog-ios onFeatureFlags listener posthog-ios 4.0 removes the didReceiveFeatureFlags notification. * chore!: adopt posthog-android 4.0 * feat: add per-event capture options and captureAi Passes options and captureAi through to posthog-ios and posthog-android 4.0; Windows, Linux and web send known options as their legacy properties. * feat: add captureAi queue and request settings to PostHogConfig Add captureAiCompression, captureAiMaxQueueSize, captureAiTimeout and captureAiMaxEventBytes. Set values are sent to native setup and applied to the posthog-ios and posthog-android config; unset values are omitted so the native defaults apply. They have no effect on Windows, Linux and web. Co-Authored-By: Claude Opus 5.5 * docs: spell out when captureAi returns null null means the event wasn't admitted: dropped by beforeSend, oversized on iOS and macOS, SDK disabled or opted out, or an unsupported platform. On Windows, Linux and web captureAi is a no-op that sends nothing. Co-Authored-By: Claude Opus 5.5 * docs: captureAi returns null for an oversized event on Android too posthog-android now checks the size before queuing (f46a9711). Co-Authored-By: Claude Opus 5.5 * fix: retry desktop capture v1 requests that get 404 or 429 A 404 usually means a misconfigured proxy and a 429 an overloaded Envoy; both are worth retrying with the same backoff, Retry-After handling and retry budget. Redirects stay terminal. * fix: back off across failed desktop flushes and warn once on a capture 404 After a batch fails its retries, later flushes make one attempt each and pause 6s doubling to 30s until a batch is delivered. Before, every flush, including the one each capture starts at flushAt, sent 4 requests, so a missing capture route kept resending the batch. A 404 prints one warning per client even without debug, naming the URL and the path a proxy or self-hosted instance must serve. * fix: leave the host out of the capture 404 warning A host with proxy credentials in its userinfo would print them to app logs. * chore!: pass the loaded flags to onFeatureFlags and reloadFeatureFlags (#664) * chore!: pass the loaded flags to onFeatureFlags and reloadFeatureFlags onFeatureFlags and reloadFeatureFlags now carry a PostHogFeatureFlagsLoaded with the enabled flags, their values and whether loading failed, matching posthog-ios 4.0 and posthog-android 4.0. On web, reloadFeatureFlags completes right away with the flags loaded so far, because posthog-js doesn't report when a reload finishes. * fix: complete the web reloadFeatureFlags with the reloaded flags Wait for the next posthog-js onFeatureFlags call instead of returning the flags already loaded, so a failed reload reports errorsLoading. Complete right away when flags are disabled, and after twice the flags request timeout when posthog-js skips the request without calling back. * chore: use PostHogFeatureFlagsCallback from posthog-android 4.0 * chore: fix ktlint function-signature * fix: await posthog-js reloadFeatureFlagsAsync on web The next onFeatureFlags callback can carry a response from a request already in flight, so reloadFeatureFlags() could complete with flags from before the reload. posthog-js 1.438.2+ settles reloadFeatureFlagsAsync() after this reload's own request; use it when present and keep the callback path for older posthog-js. * docs: pass the loaded flags in the setup example * docs: drop best-effort web note from the person and group property methods * fix(web): wait for posthog-js flags retries before reporting a reload failure posthog-js retries a timed-out /flags request once by default, 500 ms later, inside the same reload. The older-JS deadline of twice the request timeout reported cached flags with errorsLoading set before a successful retry landed. * docs: note where onFeatureFlags and errorsLoading differ on Android and web * docs: describe the older posthog-js reload timeout as the full retry budget Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 * feat(desktop): send event options unchanged in the capture v1 event On Windows and Linux, the options of capture, screen, captureException, identify, setPersonProperties, alias and group now go into the event's capture v1 `options` as they are, unknown keys included, instead of being mapped to legacy `$` properties. An option still wins over its legacy property, which is moved into `options` only when the option is unset. Co-Authored-By: Claude Opus 5.5 * feat(desktop): build event properties in the native 4.0 order On Windows and Linux, an event's properties are now the ones the SDK sets, then the registered ones, then the event's own, each winning over the ones before, and the Dart beforeSend callbacks run after that merge. They see and can change every property and option the SDK adds, and the event is queued as they leave it. A caller or registered value changes that event only. Person processing is no longer a `$process_person_profile` property: the event carries `process_person_profile: false` in its options only while person processing is off and neither an option nor a property sets it, and omits it otherwise. The event's timestamp is taken before the callbacks run. Co-Authored-By: Claude Opus 5.5 * fix(desktop): back off capture v1 retries like posthog-ios and posthog-android A transient failure or a 2xx whose per-event results ask to retry no longer resends within the flush (3 tries, 3 s apart). Each one pauses the queue for 1 s doubling to 30 s, with ±25% jitter from an injectable source. A Retry-After is a floor applied after the jitter, capped at 30 s, instead of replacing the backoff, so `Retry-After: 1` no longer resends every 3 s. A delivered or dropped batch resets the backoff. Co-Authored-By: Claude Opus 5.5 * fix(desktop): time out capture requests on inactivity, not on total duration The 10 s whole-call timeout could fail a large batch on a slow uplink on every attempt. A request now fails only after 10 s without progress: connecting (HttpClient.connectionTimeout), the socket taking a 64 KiB body chunk, the response headers, or a response body chunk. This is the closest dart:io gets to the per-read/per-write idle timeouts of OkHttp and URLSession: like them, it can't see the bytes still in the kernel send buffer, so the wait for headers starts once the last chunk is handed over. Co-Authored-By: Claude Opus 5.5 * fix(desktop): halve flushAt with the batch size on 413 and end the flush A 413 halved only the batch size and resent at once in the same flush. Like posthog-ios and posthog-android, it now also halves flushAt, kept within the batch size, and the smaller batches go out with the next flush (the next capture over flushAt, or the periodic flush). No backoff is added: posthog-ios ends the flush without one; posthog-android pauses. Co-Authored-By: Claude Opus 5.5 * feat(desktop): send captureAi events to the capture v1 AI endpoint On Windows and Linux, captureAi now builds the event like capture, runs the Dart beforeSend callbacks, and queues it on disk apart from other events, in posthog_ai_queue/. It is sent to /i/v1/ai/events with the same wire format, batching, retry rules and backoff as analytics events, and returns the event's uuid, or null when the event isn't queued: dropped by beforeSend, opted out, or over the size limit. - A serialized event over captureAiMaxEventBytes, capped at and by default 8 MiB plus 64 KiB, measured before compression, is dropped with a log line naming only the event and its size. - The queue keeps captureAiMaxQueueSize events (100 by default) and at most 50 MiB, dropping the oldest first, and flushes as soon as 5 MiB is queued. - Requests use captureAiCompression (gzip by default) and are bounded by captureAiTimeout (60 seconds by default). - Each endpoint keeps its own retry identity, timers, backoff and 413 batch size, so a failing AI request doesn't hold back other events. Co-Authored-By: Claude Opus 5.5 * docs: describe desktop captureAi, options and property order in changesets Co-Authored-By: Claude Opus 5.5 * fix(desktop): flush once 5 MiB of events are queued Like posthog-ios and posthog-android, a full capture v1 request's worth of queued bytes (captureV1MaxBatchBytes) now flushes as flushAt does, so a few large events go out before the queue starts dropping them. The file queue keeps each event's serialized size: measured when it is added, and read from the file sizes when a later process loads the queue. Co-Authored-By: Claude Opus 5.5 * fix(desktop): feed flags the person properties beforeSend keeps $set/$set_once were stored for flag evaluation while the event was prepared, before the beforeSend callbacks ran, so a redacted value or a dropped event still reached the next /flags request. They are now taken from the event as it is queued. Co-Authored-By: Claude Opus 5.5 * fix(desktop): keep properties beforeSend removes off the queued event The payload builder merged the common properties ($feature/, $active_feature_flags, $recording_status, $lib) under every event again, so a property the callbacks removed came back. Every core path already builds them into the event's properties, so the payload adds nothing. Co-Authored-By: Claude Opus 5.5 * perf(desktop): size the capture batch before reading queued events The flush peeked up to maxBatchSize events, decoding each one, before the 5 MiB batch cap picked the few it sends. With 8 MiB AI events queued that read far more than one request carries, on the UI isolate. The queue now applies the cap from its tracked per-event sizes before it reads an event, always keeping the first, so only the batch is decoded. Co-Authored-By: Claude Opus 5.5 * fix(desktop): release delivered payloads after each capture v1 batch A flush that kept finding queued events held every delivered payload until it ended. Emit flush per batch so multi-megabyte AI events are released as soon as they are sent. Co-Authored-By: Claude Opus 5.5 * fix(desktop): turn on person processing only for events beforeSend keeps Co-Authored-By: Claude Opus 5.5 * fix(desktop): give beforeSend a deep copy of the event properties Co-Authored-By: Claude Opus 5.5 * docs: limit the capture v1 migration note to native and desktop platforms Co-Authored-By: Claude Opus 5.5 * docs(desktop): note beforeSend cannot change $lib or $lib_version Co-Authored-By: Claude Opus 5.5 * fix(desktop): cap the response body read at 30 seconds A body that trickles in more often than the 10 s idle timeout reset it forever, holding the flush. The body now also fails after 30 s in total. Co-Authored-By: Claude Opus 5.5 * fix(desktop): warn when captureAiMaxEventBytes is over the ceiling Co-Authored-By: Claude Opus 5.5 * style: format the merged fetch attempt Co-Authored-By: Claude Opus 5.5 * ci: update SDK compliance harness to 1.26.0 (#680) * ci: update SDK compliance harness to 1.25.0 Co-Authored-By: Claude Opus 5.5 * chore(compliance): bump the test harness to 1.26.0 Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 * fix(desktop): check registered person processing before caching identify * fix(desktop): keep a legacy $set in properties for beforeSend to remove * fix(desktop): recompute person processing from the properties beforeSend keeps --------- Co-authored-by: Claude Opus 5.5 (1M context) --- .changeset/v6-capture-options-ai.md | 8 + .changeset/v6-desktop-capture-ai.md | 8 + .changeset/v6-desktop-capture-v1.md | 2 +- .changeset/v6-flags-loaded-result.md | 6 + .changeset/v6-posthog-android-4.md | 5 + .changeset/v6-posthog-ios-4.md | 8 + .github/workflows/sdk-compliance.yml | 4 +- api/posthog_flutter.api.json | 520 +++++++++++++++++- example/lib/main.dart | 7 +- posthog_flutter/android/build.gradle | 2 +- .../posthog/flutter/PosthogFlutterPlugin.kt | 78 ++- .../flutter/EventOptionsChannelTest.kt | 111 ++++ .../flutter/PosthogFlutterPluginTest.kt | 43 ++ .../darwin/posthog_flutter.podspec | 2 +- .../darwin/posthog_flutter/Package.swift | 2 +- .../PosthogFlutterPlugin.swift | 93 +++- posthog_flutter/lib/posthog_flutter.dart | 1 + posthog_flutter/lib/posthog_flutter_web.dart | 92 +++- posthog_flutter/lib/src/core/capture_v1.dart | 32 +- .../lib/src/core/file_storage.dart | 66 ++- .../lib/src/core/posthog_core.dart | 275 +++++++-- .../lib/src/core/posthog_core_stateless.dart | 415 +++++++++----- .../lib/src/feature_flags_loaded.dart | 53 ++ posthog_flutter/lib/src/posthog.dart | 171 +++++- posthog_flutter/lib/src/posthog_config.dart | 73 ++- .../lib/src/posthog_desktop_client.dart | 3 +- posthog_flutter/lib/src/posthog_event.dart | 19 +- .../lib/src/posthog_flutter_desktop.dart | 237 ++++++-- .../lib/src/posthog_flutter_io.dart | 100 +++- .../posthog_flutter_platform_interface.dart | 30 +- .../lib/src/posthog_flutter_web_handler.dart | 92 +++- .../lib/src/utils/channel_serialization.dart | 30 + .../lib/src/utils/event_options.dart | 46 ++ .../test/core/capture_ai_test.dart | 316 +++++++++++ .../test/core/capture_v1_test.dart | 35 -- .../test/core/context_properties_test.dart | 11 +- .../core/desktop_parity_regressions_test.dart | 16 +- .../test/core/feature_flags_test.dart | 1 - .../test/core/file_queue_test.dart | 45 ++ .../test/core/posthog_core_test.dart | 30 +- .../test/core/queue_flush_test.dart | 28 + posthog_flutter/test/core/test_client.dart | 6 + .../test/event_shape_snapshot_test.dart | 35 ++ posthog_flutter/test/posthog_api_fake.dart | 18 + .../test/posthog_flutter_desktop_test.dart | 482 +++++++++++++++- .../test/posthog_flutter_io_test.dart | 233 +++++--- ...sthog_flutter_platform_interface_fake.dart | 69 ++- .../posthog_flutter_web_handler_test.dart | 146 +++++ posthog_flutter/test/posthog_test.dart | 46 +- .../test/web_before_send_test.dart | 41 ++ pubspec.lock | 28 +- sdk_compliance_adapter/docker-compose.yml | 2 +- .../lib/adapter_server.dart | 1 + 53 files changed, 3690 insertions(+), 533 deletions(-) create mode 100644 .changeset/v6-capture-options-ai.md create mode 100644 .changeset/v6-desktop-capture-ai.md create mode 100644 .changeset/v6-flags-loaded-result.md create mode 100644 .changeset/v6-posthog-android-4.md create mode 100644 .changeset/v6-posthog-ios-4.md create mode 100644 posthog_flutter/android/src/test/kotlin/com/posthog/flutter/EventOptionsChannelTest.kt create mode 100644 posthog_flutter/lib/src/feature_flags_loaded.dart create mode 100644 posthog_flutter/lib/src/utils/event_options.dart create mode 100644 posthog_flutter/test/core/capture_ai_test.dart diff --git a/.changeset/v6-capture-options-ai.md b/.changeset/v6-capture-options-ai.md new file mode 100644 index 00000000..dc5602c9 --- /dev/null +++ b/.changeset/v6-capture-options-ai.md @@ -0,0 +1,8 @@ +--- +"posthog_flutter": minor +--- + +- Add an `options` parameter to `capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group` and `captureException`, and `PostHogEvent.options` for `beforeSend` callbacks. The known keys `process_person_profile`, `cookieless_mode`, `disable_skew_correction` and `product_tour_id` win over their legacy `$` properties. On iOS, macOS, Android, Windows and Linux other keys are sent as-is; on web the known keys are sent as their legacy `$` properties and other keys are dropped +- Add `captureAi` for AI observability events such as `$ai_generation`, sent to PostHog's AI endpoint on iOS, macOS, Android, Windows and Linux, returning the event's UUID, or `null` when the event isn't admitted (dropped by `beforeSend`, oversized, SDK disabled or opted out). On web `captureAi` is a no-op: it sends nothing and returns `null` +- Add `PostHogConfig.captureAiCompression`, `captureAiMaxQueueSize`, `captureAiTimeout` and `captureAiMaxEventBytes` for the `captureAi` queue and requests. Unset, they keep the SDK defaults. They have no effect on web +- On Windows and Linux, a `$process_person_profile` property or `process_person_profile` option passed with an event now applies to that event instead of being replaced by the SDK's value diff --git a/.changeset/v6-desktop-capture-ai.md b/.changeset/v6-desktop-capture-ai.md new file mode 100644 index 00000000..3795283f --- /dev/null +++ b/.changeset/v6-desktop-capture-ai.md @@ -0,0 +1,8 @@ +--- +"posthog_flutter": major +--- + +- **Breaking:** on Windows and Linux, an event's properties are now the ones the SDK sets (device and app context, `$lib`, feature flags, `$session_id`, `$is_identified`, the `$sdk_debug_*` keys), then registered properties, then the event's own, as in `posthog-ios` and `posthog-android` 4.0. A registered or event property with the same name as an SDK property now wins, for that event only. The Dart `beforeSend` callbacks run after that merge, so they see and can change every property and option the SDK adds, and the event is sent as they leave it, except `$lib` and `$lib_version`: PostHog always sets them from the SDK's `PostHog-Sdk-Info` header +- **Breaking:** on Windows and Linux, person processing is sent as the `process_person_profile: false` option only while it is off, instead of a `$process_person_profile` property on every event +- On Windows and Linux, `captureAi` queues AI events on disk apart from other events. The queue keeps up to `captureAiMaxQueueSize` events (100 by default) and 50 MiB, drops a serialized event over `captureAiMaxEventBytes` (8 MiB plus 64 KiB by default, measured before compression) and is sent like other events: same batching, retries and backoff, compressed with `captureAiCompression`, a request failing after `captureAiTimeout` (60 seconds by default) without progress +- On Windows and Linux, an event's timestamp is taken before the `beforeSend` callbacks run diff --git a/.changeset/v6-desktop-capture-v1.md b/.changeset/v6-desktop-capture-v1.md index 644d4aa4..00cf869e 100644 --- a/.changeset/v6-desktop-capture-v1.md +++ b/.changeset/v6-desktop-capture-v1.md @@ -2,7 +2,7 @@ "posthog_flutter": major --- -- **Breaking:** on every platform, events now go to capture v1 (`/i/v1/analytics/events`) instead of `/batch/`: iOS and macOS through `posthog-ios` 4.x, Android through `posthog-android` 4.x, and Windows and Linux in the Dart client. If you send events through your own reverse proxy, update it before you upgrade: forward `/i/v1/analytics/events` and `/i/v1/ai/events`, pass `Authorization` (the project token, sent as `Bearer `), every `PostHog-*` header, `Content-Type`, `Content-Encoding` and `User-Agent` through unchanged, and accept request bodies up to 20 MB. PostHog's managed reverse proxy already does this. See the [iOS](https://github.com/PostHog/posthog-ios/blob/main/docs/migration-3.x-to-4.0.md#hosts-without-capture-v1) and [Android](https://github.com/PostHog/posthog-android/blob/main/docs/migration-3.x-to-4.0.md#hosts-without-capture-v1) migration guides +- **Breaking:** on iOS, macOS, Android, Windows and Linux, events now go to capture v1 (`/i/v1/analytics/events`) instead of `/batch/`: iOS and macOS through `posthog-ios` 4.x, Android through `posthog-android` 4.x, and Windows and Linux in the Dart client. If you send events through your own reverse proxy, update it before you upgrade: forward `/i/v1/analytics/events` and `/i/v1/ai/events`, pass `Authorization` (the project token, sent as `Bearer `), every `PostHog-*` header, `Content-Type`, `Content-Encoding` and `User-Agent` through unchanged, and accept request bodies up to 20 MB. PostHog's managed reverse proxy already does this. See the [iOS](https://github.com/PostHog/posthog-ios/blob/main/docs/migration-3.x-to-4.0.md#hosts-without-capture-v1) and [Android](https://github.com/PostHog/posthog-android/blob/main/docs/migration-3.x-to-4.0.md#hosts-without-capture-v1) migration guides - **Breaking:** on Windows and Linux, a reverse proxy or self-hosted instance must serve the new path: a 404 is retried, the events stay queued, and the SDK prints a warning once, also without `debug`. Events queued before the upgrade are sent through the new endpoint - **Breaking:** on Windows and Linux, a redirect drops the batch instead of retrying it (only same-origin 307/308 redirects are followed, while a 404 or 429 is retried), and a `Retry-After` wait is capped at 30 seconds - On Windows and Linux, a failed batch, or one whose events the server asks to retry, is no longer resent within the same flush: the queue backs off like the iOS and Android SDKs, waiting 1 second and doubling up to 30 seconds with ±25% jitter, until a batch is delivered. A `Retry-After` is a floor under that wait rather than a replacement diff --git a/.changeset/v6-flags-loaded-result.md b/.changeset/v6-flags-loaded-result.md new file mode 100644 index 00000000..03501e51 --- /dev/null +++ b/.changeset/v6-flags-loaded-result.md @@ -0,0 +1,6 @@ +--- +"posthog_flutter": major +--- + +- **Breaking:** `PostHogConfig.onFeatureFlags` now receives a `PostHogFeatureFlagsLoaded` with the enabled flags, their values and whether loading failed. Update callbacks from `() { ... }` to `(loaded) { ... }` (or `(_) { ... }`) +- **Breaking:** `reloadFeatureFlags()` now returns a `Future` with the reloaded flags diff --git a/.changeset/v6-posthog-android-4.md b/.changeset/v6-posthog-android-4.md new file mode 100644 index 00000000..3ec91401 --- /dev/null +++ b/.changeset/v6-posthog-android-4.md @@ -0,0 +1,5 @@ +--- +"posthog_flutter": major +--- + +- **Breaking:** adopt `posthog-android` 4.x diff --git a/.changeset/v6-posthog-ios-4.md b/.changeset/v6-posthog-ios-4.md new file mode 100644 index 00000000..39b171fa --- /dev/null +++ b/.changeset/v6-posthog-ios-4.md @@ -0,0 +1,8 @@ +--- +"posthog_flutter": major +--- + +- **Breaking:** adopt `posthog-ios` 4.x, which requires Xcode 26 +- **Breaking:** return `null` instead of the raw string for a malformed, empty, or whitespace-only `getFeatureFlagResult()` payload on iOS and macOS +- **Breaking:** keep string payloads passed to `PostHogBootstrapConfig.featureFlagPayloads`, such as `"123"`, as strings on iOS and macOS instead of decoding them to numbers or booleans +- **Breaking:** stop sending the legacy `version` and `build` properties on `Application Installed`, `Application Updated` and `Application Opened` on iOS and macOS — use `$app_version` and `$app_build`. Android still sends them until `posthog-android` drops them diff --git a/.github/workflows/sdk-compliance.yml b/.github/workflows/sdk-compliance.yml index c96f5d77..8dd7ffe7 100644 --- a/.github/workflows/sdk-compliance.yml +++ b/.github/workflows/sdk-compliance.yml @@ -14,8 +14,8 @@ on: jobs: compliance: name: PostHog SDK compliance tests - uses: PostHog/posthog-sdk-test-harness/.github/workflows/test-sdk-action.yml@27806196fa5c5ac74e9e7500bc46b74db1869f3a # main @ 2026-07-27 + uses: PostHog/posthog-sdk-test-harness/.github/workflows/test-sdk-action.yml@c90b42dbe2235c89aad3b4dddf74f520a8c6c747 # 1.26.0 with: adapter-dockerfile: "sdk_compliance_adapter/Dockerfile" adapter-context: "." - test-harness-version: "0.9.0" + test-harness-version: "1.26.0" diff --git a/api/posthog_flutter.api.json b/api/posthog_flutter.api.json index d3767214..3b692ec9 100644 --- a/api/posthog_flutter.api.json +++ b/api/posthog_flutter.api.json @@ -236,6 +236,15 @@ "name": "userPropertiesSetOnce", "relativePath": "lib/src/posthog_flutter_platform_interface.dart", "typeName": "Map?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "options", + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "typeName": "Map?" } ], "relativePath": "lib/src/posthog_flutter_platform_interface.dart", @@ -267,6 +276,15 @@ "name": "userPropertiesToSetOnce", "relativePath": "lib/src/posthog_flutter_platform_interface.dart", "typeName": "Map?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "options", + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "typeName": "Map?" } ], "relativePath": "lib/src/posthog_flutter_platform_interface.dart", @@ -316,6 +334,15 @@ "name": "userPropertiesSetOnce", "relativePath": "lib/src/posthog_flutter_platform_interface.dart", "typeName": "Map?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "options", + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "typeName": "Map?" } ], "relativePath": "lib/src/posthog_flutter_platform_interface.dart", @@ -323,6 +350,64 @@ "type": "method", "typeParameterNames": [] }, + { + "entryPoints": [], + "isDeprecated": false, + "isExperimental": false, + "isStatic": false, + "name": "captureAi", + "parameters": [ + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": true, + "name": "eventName", + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "typeName": "String" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "properties", + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "typeName": "Map?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "userProperties", + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "typeName": "Map?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "userPropertiesSetOnce", + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "typeName": "Map?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "options", + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "typeName": "Map?" + } + ], + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "returnTypeName": "Future", + "type": "method", + "typeParameterNames": [] + }, { "entryPoints": [], "isDeprecated": false, @@ -347,6 +432,15 @@ "name": "properties", "relativePath": "lib/src/posthog_flutter_platform_interface.dart", "typeName": "Map?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "options", + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "typeName": "Map?" } ], "relativePath": "lib/src/posthog_flutter_platform_interface.dart", @@ -559,6 +653,15 @@ "name": "alias", "relativePath": "lib/src/posthog_flutter_platform_interface.dart", "typeName": "String" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "options", + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "typeName": "Map?" } ], "relativePath": "lib/src/posthog_flutter_platform_interface.dart", @@ -802,7 +905,7 @@ "name": "reloadFeatureFlags", "parameters": [], "relativePath": "lib/src/posthog_flutter_platform_interface.dart", - "returnTypeName": "Future", + "returnTypeName": "Future", "type": "method", "typeParameterNames": [] }, @@ -948,6 +1051,15 @@ "name": "groupProperties", "relativePath": "lib/src/posthog_flutter_platform_interface.dart", "typeName": "Map?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "options", + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "typeName": "Map?" } ], "relativePath": "lib/src/posthog_flutter_platform_interface.dart", @@ -1074,6 +1186,15 @@ "name": "properties", "relativePath": "lib/src/posthog_flutter_platform_interface.dart", "typeName": "Map?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "options", + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "typeName": "Map?" } ], "relativePath": "lib/src/posthog_flutter_platform_interface.dart", @@ -1289,6 +1410,15 @@ "name": "userPropertiesSetOnce", "relativePath": "lib/src/posthog_flutter_platform_interface.dart", "typeName": "Map?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "options", + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "typeName": "Map?" } ], "relativePath": "lib/src/posthog_flutter_platform_interface.dart", @@ -1320,6 +1450,15 @@ "name": "userPropertiesToSetOnce", "relativePath": "lib/src/posthog_flutter_platform_interface.dart", "typeName": "Map?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "options", + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "typeName": "Map?" } ], "relativePath": "lib/src/posthog_flutter_platform_interface.dart", @@ -1369,6 +1508,15 @@ "name": "userPropertiesSetOnce", "relativePath": "lib/src/posthog_flutter_platform_interface.dart", "typeName": "Map?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "options", + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "typeName": "Map?" } ], "relativePath": "lib/src/posthog_flutter_platform_interface.dart", @@ -1376,6 +1524,64 @@ "type": "method", "typeParameterNames": [] }, + { + "entryPoints": [], + "isDeprecated": false, + "isExperimental": false, + "isStatic": false, + "name": "captureAi", + "parameters": [ + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": true, + "name": "eventName", + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "typeName": "String" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "properties", + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "typeName": "Map?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "userProperties", + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "typeName": "Map?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "userPropertiesSetOnce", + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "typeName": "Map?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "options", + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "typeName": "Map?" + } + ], + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "returnTypeName": "Future", + "type": "method", + "typeParameterNames": [] + }, { "entryPoints": [], "isDeprecated": false, @@ -1400,6 +1606,15 @@ "name": "properties", "relativePath": "lib/src/posthog_flutter_platform_interface.dart", "typeName": "Map?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "options", + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "typeName": "Map?" } ], "relativePath": "lib/src/posthog_flutter_platform_interface.dart", @@ -1612,6 +1827,15 @@ "name": "alias", "relativePath": "lib/src/posthog_flutter_platform_interface.dart", "typeName": "String" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "options", + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "typeName": "Map?" } ], "relativePath": "lib/src/posthog_flutter_platform_interface.dart", @@ -1855,7 +2079,7 @@ "name": "reloadFeatureFlags", "parameters": [], "relativePath": "lib/src/posthog_flutter_platform_interface.dart", - "returnTypeName": "Future", + "returnTypeName": "Future", "type": "method", "typeParameterNames": [] }, @@ -2001,6 +2225,15 @@ "name": "groupProperties", "relativePath": "lib/src/posthog_flutter_platform_interface.dart", "typeName": "Map?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "options", + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "typeName": "Map?" } ], "relativePath": "lib/src/posthog_flutter_platform_interface.dart", @@ -2127,6 +2360,15 @@ "name": "properties", "relativePath": "lib/src/posthog_flutter_platform_interface.dart", "typeName": "Map?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "options", + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "typeName": "Map?" } ], "relativePath": "lib/src/posthog_flutter_platform_interface.dart", @@ -2301,7 +2543,7 @@ "isRequired": false, "name": "onFeatureFlags", "relativePath": "lib/src/posthog_config.dart", - "typeName": "void Function()?" + "typeName": "void Function(PostHogFeatureFlagsLoaded)?" }, { "isDeprecated": false, @@ -2485,6 +2727,50 @@ "relativePath": "lib/src/posthog_config.dart", "typeName": "PostHogCompression" }, + { + "entryPoints": [], + "isDeprecated": false, + "isExperimental": false, + "isReadable": true, + "isStatic": false, + "isWriteable": true, + "name": "captureAiCompression", + "relativePath": "lib/src/posthog_config.dart", + "typeName": "PostHogCompression?" + }, + { + "entryPoints": [], + "isDeprecated": false, + "isExperimental": false, + "isReadable": true, + "isStatic": false, + "isWriteable": true, + "name": "captureAiMaxQueueSize", + "relativePath": "lib/src/posthog_config.dart", + "typeName": "int?" + }, + { + "entryPoints": [], + "isDeprecated": false, + "isExperimental": false, + "isReadable": true, + "isStatic": false, + "isWriteable": true, + "name": "captureAiTimeout", + "relativePath": "lib/src/posthog_config.dart", + "typeName": "Duration?" + }, + { + "entryPoints": [], + "isDeprecated": false, + "isExperimental": false, + "isReadable": true, + "isStatic": false, + "isWriteable": true, + "name": "captureAiMaxEventBytes", + "relativePath": "lib/src/posthog_config.dart", + "typeName": "int?" + }, { "entryPoints": [], "isDeprecated": false, @@ -2582,7 +2868,7 @@ "isWriteable": true, "name": "onFeatureFlags", "relativePath": "lib/src/posthog_config.dart", - "typeName": "void Function()?" + "typeName": "void Function(PostHogFeatureFlagsLoaded)?" }, { "entryPoints": [], @@ -4141,6 +4427,15 @@ "name": "userPropertiesSetOnce", "relativePath": "lib/src/posthog.dart", "typeName": "Map?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "options", + "relativePath": "lib/src/posthog.dart", + "typeName": "Map?" } ], "relativePath": "lib/src/posthog.dart", @@ -4172,6 +4467,15 @@ "name": "userPropertiesToSetOnce", "relativePath": "lib/src/posthog.dart", "typeName": "Map?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "options", + "relativePath": "lib/src/posthog.dart", + "typeName": "Map?" } ], "relativePath": "lib/src/posthog.dart", @@ -4221,6 +4525,15 @@ "name": "userPropertiesSetOnce", "relativePath": "lib/src/posthog.dart", "typeName": "Map?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "options", + "relativePath": "lib/src/posthog.dart", + "typeName": "Map?" } ], "relativePath": "lib/src/posthog.dart", @@ -4228,6 +4541,64 @@ "type": "method", "typeParameterNames": [] }, + { + "entryPoints": [], + "isDeprecated": false, + "isExperimental": false, + "isStatic": false, + "name": "captureAi", + "parameters": [ + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": true, + "name": "eventName", + "relativePath": "lib/src/posthog.dart", + "typeName": "String" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "properties", + "relativePath": "lib/src/posthog.dart", + "typeName": "Map?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "userProperties", + "relativePath": "lib/src/posthog.dart", + "typeName": "Map?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "userPropertiesSetOnce", + "relativePath": "lib/src/posthog.dart", + "typeName": "Map?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "options", + "relativePath": "lib/src/posthog.dart", + "typeName": "Map?" + } + ], + "relativePath": "lib/src/posthog.dart", + "returnTypeName": "Future", + "type": "method", + "typeParameterNames": [] + }, { "entryPoints": [], "isDeprecated": false, @@ -4252,6 +4623,15 @@ "name": "properties", "relativePath": "lib/src/posthog.dart", "typeName": "Map?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "options", + "relativePath": "lib/src/posthog.dart", + "typeName": "Map?" } ], "relativePath": "lib/src/posthog.dart", @@ -4341,6 +4721,15 @@ "name": "alias", "relativePath": "lib/src/posthog.dart", "typeName": "String" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "options", + "relativePath": "lib/src/posthog.dart", + "typeName": "Map?" } ], "relativePath": "lib/src/posthog.dart", @@ -4522,7 +4911,7 @@ "name": "reloadFeatureFlags", "parameters": [], "relativePath": "lib/src/posthog.dart", - "returnTypeName": "Future", + "returnTypeName": "Future", "type": "method", "typeParameterNames": [] }, @@ -4683,6 +5072,15 @@ "name": "groupProperties", "relativePath": "lib/src/posthog.dart", "typeName": "Map?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "options", + "relativePath": "lib/src/posthog.dart", + "typeName": "Map?" } ], "relativePath": "lib/src/posthog.dart", @@ -4972,6 +5370,15 @@ "name": "properties", "relativePath": "lib/src/posthog.dart", "typeName": "Map?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "options", + "relativePath": "lib/src/posthog.dart", + "typeName": "Map?" } ], "relativePath": "lib/src/posthog.dart", @@ -5226,6 +5633,15 @@ "name": "userPropertiesSetOnce", "relativePath": "lib/src/posthog_event.dart", "typeName": "Map?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "options", + "relativePath": "lib/src/posthog_event.dart", + "typeName": "Map?" } ], "relativePath": "lib/src/posthog_event.dart", @@ -5278,6 +5694,17 @@ "name": "userPropertiesSetOnce", "relativePath": "lib/src/posthog_event.dart", "typeName": "Map?" + }, + { + "entryPoints": [], + "isDeprecated": false, + "isExperimental": false, + "isReadable": true, + "isStatic": false, + "isWriteable": true, + "name": "options", + "relativePath": "lib/src/posthog_event.dart", + "typeName": "Map?" } ], "isDeprecated": false, @@ -6026,6 +6453,89 @@ "Object" ], "typeParameterNames": [] + }, + { + "entryPoints": [ + "posthog_flutter.dart" + ], + "executableDeclarations": [ + { + "entryPoints": [], + "isDeprecated": false, + "isExperimental": false, + "isStatic": false, + "name": "new", + "parameters": [ + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": true, + "name": "variants", + "relativePath": "lib/src/feature_flags_loaded.dart", + "typeName": "Map" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": true, + "name": "errorsLoading", + "relativePath": "lib/src/feature_flags_loaded.dart", + "typeName": "bool" + } + ], + "relativePath": "lib/src/feature_flags_loaded.dart", + "returnTypeName": "PostHogFeatureFlagsLoaded", + "type": "constructor", + "typeParameterNames": [] + } + ], + "fieldDeclarations": [ + { + "entryPoints": [], + "isDeprecated": false, + "isExperimental": false, + "isReadable": true, + "isStatic": false, + "isWriteable": false, + "name": "flags", + "relativePath": "lib/src/feature_flags_loaded.dart", + "typeName": "List" + }, + { + "entryPoints": [], + "isDeprecated": false, + "isExperimental": false, + "isReadable": true, + "isStatic": false, + "isWriteable": false, + "name": "variants", + "relativePath": "lib/src/feature_flags_loaded.dart", + "typeName": "Map" + }, + { + "entryPoints": [], + "isDeprecated": false, + "isExperimental": false, + "isReadable": true, + "isStatic": false, + "isWriteable": false, + "name": "errorsLoading", + "relativePath": "lib/src/feature_flags_loaded.dart", + "typeName": "bool" + } + ], + "isDeprecated": false, + "isExperimental": false, + "isRequired": false, + "isSealed": false, + "name": "PostHogFeatureFlagsLoaded", + "relativePath": "lib/src/feature_flags_loaded.dart", + "superTypeNames": [ + "Object" + ], + "typeParameterNames": [] } ], "iosPlatformConstraints": null, diff --git a/example/lib/main.dart b/example/lib/main.dart index 378b7c3c..e4599572 100644 --- a/example/lib/main.dart +++ b/example/lib/main.dart @@ -21,8 +21,11 @@ Future main() async { final config = PostHogConfig( 'phc_6lqCaCDCBEWdIGieihq5R2dZpPVbAUFISA75vFZow06', ); - config.onFeatureFlags = () { - debugPrint('[PostHog] Feature flags loaded!'); + config.onFeatureFlags = (loaded) { + debugPrint( + '[PostHog] Feature flags loaded: ${loaded.variants}, ' + 'errorsLoading: ${loaded.errorsLoading}', + ); }; config.beforeSend = [ diff --git a/posthog_flutter/android/build.gradle b/posthog_flutter/android/build.gradle index 2ae6e792..fd123302 100644 --- a/posthog_flutter/android/build.gradle +++ b/posthog_flutter/android/build.gradle @@ -67,7 +67,7 @@ android { testImplementation 'org.robolectric:robolectric:4.14.1' testImplementation 'junit:junit:4.13.2' testRuntimeOnly 'org.junit.vintage:junit-vintage-engine:5.10.1' - implementation 'com.posthog:posthog-android:[3.71.0,4.0.0)' + implementation 'com.posthog:posthog-android:[4.0.0,5.0.0)' } testOptions { diff --git a/posthog_flutter/android/src/main/kotlin/com/posthog/flutter/PosthogFlutterPlugin.kt b/posthog_flutter/android/src/main/kotlin/com/posthog/flutter/PosthogFlutterPlugin.kt index f81e073c..62933ebd 100644 --- a/posthog_flutter/android/src/main/kotlin/com/posthog/flutter/PosthogFlutterPlugin.kt +++ b/posthog_flutter/android/src/main/kotlin/com/posthog/flutter/PosthogFlutterPlugin.kt @@ -27,7 +27,8 @@ import com.posthog.PostHogBeforeSend import com.posthog.PostHogBootstrapConfig import com.posthog.PostHogCompression import com.posthog.PostHogConfig -import com.posthog.PostHogOnFeatureFlags +import com.posthog.PostHogFeatureFlagsCallback +import com.posthog.PostHogFeatureFlagsLoaded import com.posthog.android.PostHogAndroid import com.posthog.android.PostHogAndroidConfig import com.posthog.android.internal.getApplicationInfo @@ -247,6 +248,10 @@ class PosthogFlutterPlugin : capture(call, result) } + "captureAi" -> { + captureAi(call, result) + } + "captureFeatureView" -> { captureFeatureView(call, result) } @@ -608,6 +613,21 @@ class PosthogFlutterPlugin : "none" -> compression = PostHogCompression.NONE } } + posthogConfig.getIfNotNull("captureAiCompression") { + when (it) { + "gzip" -> captureAiCompression = PostHogCompression.GZIP + "none" -> captureAiCompression = PostHogCompression.NONE + } + } + posthogConfig.getIfNotNull("captureAiMaxQueueSize") { + captureAiMaxQueueSize = it + } + posthogConfig.getIfNotNull("captureAiTimeoutSeconds") { + captureAiTimeout = it + } + posthogConfig.getIfNotNull("captureAiMaxEventBytes") { + captureAiMaxEventBytes = it + } posthogConfig.getIfNotNull("sessionReplay") { sessionReplay = it } @@ -814,9 +834,9 @@ class PosthogFlutterPlugin : } onFeatureFlags = - PostHogOnFeatureFlags { + PostHogFeatureFlagsCallback { loaded -> Log.i("PostHogFlutter", "Android onFeatureFlags triggered. Notifying Dart.") - invokeFlutterMethod("onFeatureFlagsCallback", emptyMap()) + invokeFlutterMethod("onFeatureFlagsCallback", loaded.toFlutterMap()) } } @@ -1730,7 +1750,8 @@ class PosthogFlutterPlugin : val userId: String = call.argument("userId")!! val userProperties: Map? = call.argument("userProperties") val userPropertiesSetOnce: Map? = call.argument("userPropertiesSetOnce") - PostHog.identify(userId, userProperties, userPropertiesSetOnce) + val options: Map? = call.argument("options") + PostHog.identify(userId, userProperties, userPropertiesSetOnce, options = options) result.success(null) } catch (e: Throwable) { result.error("PosthogFlutterException", e.localizedMessage, null) @@ -1744,7 +1765,8 @@ class PosthogFlutterPlugin : try { val userPropertiesToSet: Map? = call.argument("userPropertiesToSet") val userPropertiesToSetOnce: Map? = call.argument("userPropertiesToSetOnce") - PostHog.setPersonProperties(userPropertiesToSet, userPropertiesToSetOnce) + val options: Map? = call.argument("options") + PostHog.setPersonProperties(userPropertiesToSet, userPropertiesToSetOnce, options = options) result.success(null) } catch (e: Throwable) { result.error("PosthogFlutterException", e.localizedMessage, null) @@ -1760,11 +1782,13 @@ class PosthogFlutterPlugin : val properties: Map? = call.argument("properties") val userProperties: Map? = call.argument("userProperties") val userPropertiesSetOnce: Map? = call.argument("userPropertiesSetOnce") + val options: Map? = call.argument("options") PostHog.capture( eventName, properties = properties, userProperties = userProperties, userPropertiesSetOnce = userPropertiesSetOnce, + options = options, ) result.success(null) } catch (e: Throwable) { @@ -1772,6 +1796,30 @@ class PosthogFlutterPlugin : } } + private fun captureAi( + call: MethodCall, + result: Result, + ) { + try { + val eventName: String = call.argument("eventName")!! + val properties: Map? = call.argument("properties") + val userProperties: Map? = call.argument("userProperties") + val userPropertiesSetOnce: Map? = call.argument("userPropertiesSetOnce") + val options: Map? = call.argument("options") + val uuid = + PostHog.captureAi( + eventName, + properties = properties, + userProperties = userProperties, + userPropertiesSetOnce = userPropertiesSetOnce, + options = options, + ) + result.success(uuid?.toString()) + } catch (e: Throwable) { + result.error("PosthogFlutterException", e.localizedMessage, null) + } + } + private fun screen( call: MethodCall, result: Result, @@ -1779,7 +1827,8 @@ class PosthogFlutterPlugin : try { val screenName: String = call.argument("screenName")!! val properties: Map? = call.argument("properties") - PostHog.screen(screenName, properties) + val options: Map? = call.argument("options") + PostHog.screen(screenName, properties, options = options) result.success(null) } catch (e: Throwable) { result.error("PosthogFlutterException", e.localizedMessage, null) @@ -1820,7 +1869,8 @@ class PosthogFlutterPlugin : ) { try { val alias: String = call.argument("alias")!! - PostHog.alias(alias) + val options: Map? = call.argument("options") + PostHog.alias(alias, options = options) result.success(null) } catch (e: Throwable) { result.error("PosthogFlutterException", e.localizedMessage, null) @@ -1929,9 +1979,9 @@ class PosthogFlutterPlugin : // Resolve the Dart Future only once flags have actually finished // loading. The native callback fires on a background thread, so the // result must be posted back to the main thread for Flutter. - PostHog.reloadFeatureFlags { + PostHog.reloadFeatureFlags { loaded -> Handler(Looper.getMainLooper()).post { - result.success(null) + result.success(loaded.toFlutterMap()) } } } catch (e: Throwable) { @@ -1998,7 +2048,8 @@ class PosthogFlutterPlugin : val groupType: String = call.argument("groupType")!! val groupKey: String = call.argument("groupKey")!! val groupProperties: Map? = call.argument("groupProperties") - PostHog.group(groupType, groupKey, groupProperties) + val options: Map? = call.argument("options") + PostHog.group(groupType, groupKey, groupProperties, options = options) result.success(null) } catch (e: Throwable) { result.error("PosthogFlutterException", e.localizedMessage, null) @@ -2130,6 +2181,9 @@ class PosthogFlutterPlugin : val properties = arguments["properties"] as? Map val timestampMs = arguments["timestamp"] as? Long + @Suppress("UNCHECKED_CAST") + val options = arguments["options"] as? Map + // Extract timestamp from Flutter val timestamp: Date? = timestampMs?.let { @@ -2137,7 +2191,7 @@ class PosthogFlutterPlugin : Date(timestampMs) } - PostHog.capture("\$exception", properties = properties, timestamp = timestamp) + PostHog.capture("\$exception", properties = properties, timestamp = timestamp, options = options) result.success(null) } catch (e: Throwable) { result.error("CAPTURE_EXCEPTION_ERROR", "Failed to capture exception: ${e.message}", null) @@ -2232,6 +2286,8 @@ class PosthogFlutterPlugin : } } + private fun PostHogFeatureFlagsLoaded.toFlutterMap(): Map = mapOf("variants" to variants, "errorsLoading" to errorsLoading) + private fun invokeFlutterMethod( method: String, arguments: Any? = null, diff --git a/posthog_flutter/android/src/test/kotlin/com/posthog/flutter/EventOptionsChannelTest.kt b/posthog_flutter/android/src/test/kotlin/com/posthog/flutter/EventOptionsChannelTest.kt new file mode 100644 index 00000000..e20b016d --- /dev/null +++ b/posthog_flutter/android/src/test/kotlin/com/posthog/flutter/EventOptionsChannelTest.kt @@ -0,0 +1,111 @@ +package com.posthog.flutter + +import com.posthog.PostHog +import com.posthog.PostHogEvent +import com.posthog.android.PostHogAndroid +import com.posthog.android.PostHogAndroidConfig +import io.flutter.plugin.common.MethodCall +import io.flutter.plugin.common.MethodChannel +import org.junit.Test +import org.junit.runner.RunWith +import org.mockito.ArgumentCaptor +import org.mockito.Mockito +import org.robolectric.RobolectricTestRunner +import org.robolectric.RuntimeEnvironment +import org.robolectric.annotation.Config +import java.util.UUID +import kotlin.test.assertEquals +import kotlin.test.assertNotNull + +@RunWith(RobolectricTestRunner::class) +@Config(manifest = Config.NONE, sdk = [28]) +class EventOptionsChannelTest { + private val options = mapOf("process_person_profile" to true, "custom_key" to "kept") + + @Test + fun forwardsOptionsToEachNativeMethod() { + val events = mutableListOf() + val config = + PostHogAndroidConfig("event-options-test", "http://127.0.0.1:1").apply { + preloadFeatureFlags = false + captureApplicationLifecycleEvents = false + captureDeepLinks = false + captureScreenViews = false + addBeforeSend { event -> + events.add(event) + // Keep AI events so captureAi returns their uuid. + if (event.event.startsWith("\$ai_")) event else null + } + } + PostHogAndroid.setup(RuntimeEnvironment.getApplication(), config) + try { + val plugin = PosthogFlutterPlugin() + val calls = + listOf( + "capture" to mapOf("eventName" to "clicked"), + "screen" to mapOf("screenName" to "Home"), + "captureException" to mapOf("properties" to mapOf("\$exception_list" to emptyList())), + "alias" to mapOf("alias" to "alias-id"), + "identify" to mapOf("userId" to "user-id"), + "setPersonProperties" to mapOf("userPropertiesToSet" to mapOf("plan" to "pro")), + "group" to mapOf("groupType" to "company", "groupKey" to "acme"), + ) + for ((method, arguments) in calls) { + val result = Mockito.mock(MethodChannel.Result::class.java) + plugin.onMethodCall(MethodCall(method, arguments + ("options" to options)), result) + Mockito.verify(result).success(null) + } + + assertEquals( + listOf("clicked", "\$screen", "\$exception", "\$create_alias", "\$identify", "\$set", "\$groupidentify"), + events.map { it.event }, + ) + for (event in events) { + assertEquals?>(options, event.options, event.event) + } + } finally { + PostHog.close() + } + } + + @Test + fun captureAiReturnsTheQueuedEventUuid() { + val events = mutableListOf() + val config = + PostHogAndroidConfig("capture-ai-test", "http://127.0.0.1:1").apply { + preloadFeatureFlags = false + captureApplicationLifecycleEvents = false + captureDeepLinks = false + addBeforeSend { event -> + events.add(event) + event + } + } + PostHogAndroid.setup(RuntimeEnvironment.getApplication(), config) + try { + val result = Mockito.mock(MethodChannel.Result::class.java) + PosthogFlutterPlugin().onMethodCall( + MethodCall( + "captureAi", + mapOf( + "eventName" to "\$ai_generation", + "properties" to mapOf("\$ai_model" to "gpt-4o"), + "options" to options, + ), + ), + result, + ) + + val captor = ArgumentCaptor.forClass(Any::class.java) + Mockito.verify(result).success(captor.capture()) + val uuid = assertNotNull(captor.value as? String) + UUID.fromString(uuid) + val event = events.single() + assertEquals("\$ai_generation", event.event) + assertEquals("gpt-4o", event.properties?.get("\$ai_model")) + assertEquals?>(options, event.options) + } finally { + PostHog.close() + } + } +} diff --git a/posthog_flutter/android/src/test/kotlin/com/posthog/flutter/PosthogFlutterPluginTest.kt b/posthog_flutter/android/src/test/kotlin/com/posthog/flutter/PosthogFlutterPluginTest.kt index fc333ff8..a82b7734 100644 --- a/posthog_flutter/android/src/test/kotlin/com/posthog/flutter/PosthogFlutterPluginTest.kt +++ b/posthog_flutter/android/src/test/kotlin/com/posthog/flutter/PosthogFlutterPluginTest.kt @@ -6,6 +6,7 @@ import android.content.Intent import android.os.BadParcelableException import com.google.firebase.FirebaseApp import com.posthog.PostHogCompression +import com.posthog.PostHogConfig import com.posthog.PostHogEvent import com.posthog.android.replay.PostHogScreenshotColorMode import io.flutter.embedding.engine.plugins.FlutterPlugin @@ -225,6 +226,48 @@ internal class PosthogFlutterPluginTest { assertEquals(PostHogCompression.NONE, assertNotNull(plugin.lastBuiltConfig).compression) } + @Test + fun setup_captureAiSettings_forwardToNativeConfig() { + val plugin = PosthogFlutterPlugin() + attach(plugin, Mockito.mock(BinaryMessenger::class.java)) + + val call = + MethodCall( + "setup", + mapOf( + "projectToken" to "test-token", + "captureAiCompression" to "none", + "captureAiMaxQueueSize" to 7, + "captureAiTimeoutSeconds" to 90, + "captureAiMaxEventBytes" to 1024, + ), + ) + plugin.onMethodCall(call, Mockito.mock(MethodChannel.Result::class.java)) + + val config = assertNotNull(plugin.lastBuiltConfig) + assertEquals(PostHogCompression.NONE, config.captureAiCompression) + assertEquals(7, config.captureAiMaxQueueSize) + assertEquals(90, config.captureAiTimeout) + assertEquals(1024, config.captureAiMaxEventBytes) + } + + @Test + fun setup_captureAiSettings_unsetKeepNativeDefaults() { + val plugin = PosthogFlutterPlugin() + attach(plugin, Mockito.mock(BinaryMessenger::class.java)) + + plugin.onMethodCall( + MethodCall("setup", mapOf("projectToken" to "test-token")), + Mockito.mock(MethodChannel.Result::class.java), + ) + + val config = assertNotNull(plugin.lastBuiltConfig) + assertEquals(PostHogCompression.GZIP, config.captureAiCompression) + assertEquals(PostHogConfig.DEFAULT_CAPTURE_AI_MAX_QUEUE_SIZE, config.captureAiMaxQueueSize) + assertEquals(PostHogConfig.DEFAULT_CAPTURE_AI_TIMEOUT_SECONDS, config.captureAiTimeout) + assertEquals(PostHogConfig.DEFAULT_CAPTURE_AI_MAX_EVENT_BYTES, config.captureAiMaxEventBytes) + } + @Test fun setup_flutterVersion_addedOnlyToInstallAndUpdateEvents() { val plugin = PosthogFlutterPlugin() diff --git a/posthog_flutter/darwin/posthog_flutter.podspec b/posthog_flutter/darwin/posthog_flutter.podspec index 98e3a7cf..d50d58d6 100644 --- a/posthog_flutter/darwin/posthog_flutter.podspec +++ b/posthog_flutter/darwin/posthog_flutter.podspec @@ -21,7 +21,7 @@ Postog flutter plugin s.ios.dependency 'Flutter' s.osx.dependency 'FlutterMacOS' - s.dependency 'PostHog', '>= 3.84.0', '< 4.0.0' + s.dependency 'PostHog', '>= 4.0.0', '< 5.0.0' s.ios.deployment_target = '15.0' s.osx.deployment_target = '11.0' diff --git a/posthog_flutter/darwin/posthog_flutter/Package.swift b/posthog_flutter/darwin/posthog_flutter/Package.swift index 1cf4470c..5d2d9474 100644 --- a/posthog_flutter/darwin/posthog_flutter/Package.swift +++ b/posthog_flutter/darwin/posthog_flutter/Package.swift @@ -14,7 +14,7 @@ let package = Package( ], dependencies: [ .package(name: "FlutterFramework", path: "../FlutterFramework"), - .package(url: "https://github.com/PostHog/posthog-ios", "3.84.0" ..< "4.0.0"), + .package(url: "https://github.com/PostHog/posthog-ios", "4.0.0" ..< "5.0.0"), ], targets: [ .target( diff --git a/posthog_flutter/darwin/posthog_flutter/Sources/posthog_flutter/PosthogFlutterPlugin.swift b/posthog_flutter/darwin/posthog_flutter/Sources/posthog_flutter/PosthogFlutterPlugin.swift index 1fa099c4..c48f485e 100644 --- a/posthog_flutter/darwin/posthog_flutter/Sources/posthog_flutter/PosthogFlutterPlugin.swift +++ b/posthog_flutter/darwin/posthog_flutter/Sources/posthog_flutter/PosthogFlutterPlugin.swift @@ -43,6 +43,7 @@ public class PosthogFlutterPlugin: NSObject, FlutterPlugin { private static var instance: PosthogFlutterPlugin? private var channel: FlutterMethodChannel? + private var featureFlagsSubscription: PostHogFeatureFlagsSubscription? // Mint route for pushIdentityProvider, anchored to the engine whose setup() // installed the provider. A live owner is never displaced; provider-enabled @@ -61,15 +62,13 @@ public class PosthogFlutterPlugin: NSObject, FlutterPlugin { override init() { super.init() - NotificationCenter.default.addObserver( - self, - selector: #selector(featureFlagsDidUpdate), - name: PostHogSDK.didReceiveFeatureFlags, - object: nil - ) + featureFlagsSubscription = PostHogSDK.shared.onFeatureFlags { [weak self] loaded in + self?.featureFlagsDidUpdate(loaded) + } } deinit { + featureFlagsSubscription?.unsubscribe() NotificationCenter.default.removeObserver(self) } @@ -88,8 +87,12 @@ public class PosthogFlutterPlugin: NSObject, FlutterPlugin { registrar.addMethodCallDelegate(instance, channel: methodChannel) } - @objc func featureFlagsDidUpdate() { - invokeFlutterMethod("onFeatureFlagsCallback", arguments: [String: Any]()) + func featureFlagsDidUpdate(_ loaded: PostHogFeatureFlagsLoaded) { + invokeFlutterMethod("onFeatureFlagsCallback", arguments: Self.featureFlagsLoadedMap(loaded)) + } + + private static func featureFlagsLoadedMap(_ loaded: PostHogFeatureFlagsLoaded) -> [String: Any] { + ["variants": loaded.variants, "errorsLoading": loaded.errorsLoading] } private let dispatchQueue = DispatchQueue(label: "com.posthog.PosthogFlutterPlugin", @@ -240,6 +243,25 @@ public class PosthogFlutterPlugin: NSObject, FlutterPlugin { break } } + if let captureAiCompression = posthogConfig["captureAiCompression"] as? String { + switch captureAiCompression { + case "gzip": + config.captureAiCompression = .gzip + case "none": + config.captureAiCompression = .none + default: + break + } + } + if let captureAiMaxQueueSize = posthogConfig["captureAiMaxQueueSize"] as? Int { + config.captureAiMaxQueueSize = captureAiMaxQueueSize + } + if let captureAiTimeoutSeconds = posthogConfig["captureAiTimeoutSeconds"] as? Int { + config.captureAiTimeout = TimeInterval(captureAiTimeoutSeconds) + } + if let captureAiMaxEventBytes = posthogConfig["captureAiMaxEventBytes"] as? Int { + config.captureAiMaxEventBytes = captureAiMaxEventBytes + } if let dataMode = posthogConfig["dataMode"] as? String { switch dataMode { case "wifi": @@ -478,6 +500,8 @@ public class PosthogFlutterPlugin: NSObject, FlutterPlugin { setPersonProperties(call, result: result) case "capture": capture(call, result: result) + case "captureAi": + captureAi(call, result: result) case "screen": screen(call, result: result) case "captureLog": @@ -1424,11 +1448,13 @@ extension PosthogFlutterPlugin { { let userProperties = args["userProperties"] as? [String: Any] let userPropertiesSetOnce = args["userPropertiesSetOnce"] as? [String: Any] + let options = args["options"] as? [String: Any] PostHogSDK.shared.identify( userId, userProperties: userProperties, - userPropertiesSetOnce: userPropertiesSetOnce + userPropertiesSetOnce: userPropertiesSetOnce, + options: options ) result(nil) } else { @@ -1443,10 +1469,12 @@ extension PosthogFlutterPlugin { if let args = call.arguments as? [String: Any] { let userPropertiesToSet = args["userPropertiesToSet"] as? [String: Any] let userPropertiesToSetOnce = args["userPropertiesToSetOnce"] as? [String: Any] + let options = args["options"] as? [String: Any] PostHogSDK.shared.setPersonProperties( userPropertiesToSet: userPropertiesToSet, - userPropertiesToSetOnce: userPropertiesToSetOnce + userPropertiesToSetOnce: userPropertiesToSetOnce, + options: options ) result(nil) } else { @@ -1464,11 +1492,13 @@ extension PosthogFlutterPlugin { let properties = args["properties"] as? [String: Any] let userProperties = args["userProperties"] as? [String: Any] let userPropertiesSetOnce = args["userPropertiesSetOnce"] as? [String: Any] + let options = args["options"] as? [String: Any] PostHogSDK.shared.capture( eventName, properties: properties, userProperties: userProperties, - userPropertiesSetOnce: userPropertiesSetOnce + userPropertiesSetOnce: userPropertiesSetOnce, + options: options ) result(nil) } else { @@ -1476,6 +1506,30 @@ extension PosthogFlutterPlugin { } } + private func captureAi( + _ call: FlutterMethodCall, + result: @escaping FlutterResult + ) { + if let args = call.arguments as? [String: Any], + let eventName = args["eventName"] as? String + { + let properties = args["properties"] as? [String: Any] + let userProperties = args["userProperties"] as? [String: Any] + let userPropertiesSetOnce = args["userPropertiesSetOnce"] as? [String: Any] + let options = args["options"] as? [String: Any] + let uuid = PostHogSDK.shared.captureAi( + eventName, + properties: properties, + userProperties: userProperties, + userPropertiesSetOnce: userPropertiesSetOnce, + options: options + ) + result(uuid) + } else { + _badArgumentError(result) + } + } + private func screen( _ call: FlutterMethodCall, result: @escaping FlutterResult @@ -1484,9 +1538,11 @@ extension PosthogFlutterPlugin { let screenName = args["screenName"] as? String { let properties = args["properties"] as? [String: Any] + let options = args["options"] as? [String: Any] PostHogSDK.shared.screen( screenName, - properties: properties + properties: properties, + options: options ) result(nil) } else { @@ -1545,7 +1601,8 @@ extension PosthogFlutterPlugin { if let args = call.arguments as? [String: Any], let alias = args["alias"] as? String { - PostHogSDK.shared.alias(alias) + let options = args["options"] as? [String: Any] + PostHogSDK.shared.alias(alias, options: options) result(nil) } else { _badArgumentError(result) @@ -1622,9 +1679,9 @@ extension PosthogFlutterPlugin { private func reloadFeatureFlags(_ result: @escaping FlutterResult) { // Resolve the Dart Future only once flags have actually finished loading. // The native callback fires on a background thread, so hop to main for Flutter. - PostHogSDK.shared.reloadFeatureFlags { + PostHogSDK.shared.reloadFeatureFlags { loaded in DispatchQueue.main.async { - result(nil) + result(Self.featureFlagsLoadedMap(loaded)) } } } @@ -1687,7 +1744,8 @@ extension PosthogFlutterPlugin { let groupKey = args["groupKey"] as? String { let groupProperties = args["groupProperties"] as? [String: Any] - PostHogSDK.shared.group(type: groupType, key: groupKey, groupProperties: groupProperties) + let options = args["options"] as? [String: Any] + PostHogSDK.shared.group(type: groupType, key: groupKey, groupProperties: groupProperties, options: options) result(nil) } else { _badArgumentError(result) @@ -1791,6 +1849,7 @@ extension PosthogFlutterPlugin { } let properties = arguments["properties"] as? [String: Any] + let options = arguments["options"] as? [String: Any] // Extract timestamp from Flutter and convert to Date var timestamp: Date? = nil @@ -1799,7 +1858,7 @@ extension PosthogFlutterPlugin { } // Use capture method with timestamp to ensure Flutter timestamp is used - PostHogSDK.shared.capture("$exception", properties: properties, timestamp: timestamp) + PostHogSDK.shared.capture("$exception", properties: properties, timestamp: timestamp, options: options) result(nil) } diff --git a/posthog_flutter/lib/posthog_flutter.dart b/posthog_flutter/lib/posthog_flutter.dart index a95b37a5..13307a0e 100644 --- a/posthog_flutter/lib/posthog_flutter.dart +++ b/posthog_flutter/lib/posthog_flutter.dart @@ -2,6 +2,7 @@ library posthog_flutter; export 'src/feature_flag_result.dart'; +export 'src/feature_flags_loaded.dart'; export 'src/logs/posthog_log_record.dart'; export 'src/logs/posthog_log_severity.dart'; export 'src/logs/posthog_logger.dart' hide CaptureLog; diff --git a/posthog_flutter/lib/posthog_flutter_web.dart b/posthog_flutter/lib/posthog_flutter_web.dart index 88047d82..163dbac0 100644 --- a/posthog_flutter/lib/posthog_flutter_web.dart +++ b/posthog_flutter/lib/posthog_flutter_web.dart @@ -11,6 +11,7 @@ import 'package:posthog_flutter/src/utils/channel_serialization.dart'; import 'package:posthog_flutter/src/utils/property_normalizer.dart'; import 'src/feature_flag_result.dart'; +import 'src/feature_flags_loaded.dart'; import 'src/logs/posthog_log_severity.dart'; import 'src/posthog_config.dart'; import 'src/posthog_constants.dart'; @@ -20,6 +21,7 @@ import 'src/posthog_flutter_web_handler.dart'; import 'src/utils/before_send.dart'; import 'src/replay/web/web_canvas_mask_provider.dart'; import 'src/utils/capture_utils.dart'; +import 'src/utils/event_options.dart'; import 'src/utils/feature_event.dart'; /// A web implementation of the PosthogFlutterPlatform of the PosthogFlutter plugin. @@ -44,6 +46,7 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { Map? properties, { Map? userProperties, Map? userPropertiesSetOnce, + Map? options, }) { return applyBeforeSend( _beforeSendCallbacks, @@ -52,10 +55,22 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { properties: properties, userProperties: userProperties, userPropertiesSetOnce: userPropertiesSetOnce, + options: options == null ? null : {...options}, ), ); } + /// posthog-js sends these calls' events without event properties, so + /// options can't be attached. + static void _logUnsupportedOptions( + String method, + Map? options, + ) { + if (cleanEventOptions(options) == null) return; + printIfDebug('[PostHog] $method options are not supported on web and ' + 'were dropped.'); + } + static void registerWith(Registrar registrar) { final channel = MethodChannel( 'posthog_flutter', @@ -129,10 +144,12 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { final dartCallback = config.onFeatureFlags!; // JS SDK calls with: (flags: string[], variants: Record, context?: {errorsLoading}) - // We ignore the JS parameters and just invoke the void callback final jsCallback = (JSArray jsFlags, JSObject jsFlagVariants, [JSObject? jsContext]) { - dartCallback(); + dartCallback(featureFlagsLoadedFromMap({ + 'variants': jsFlagVariants.dartify(), + 'errorsLoading': (jsContext?.dartify() as Map?)?['errorsLoading'], + })); }.toJS; ph.onFeatureFlags(jsCallback); @@ -144,7 +161,9 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { required String userId, Map? userProperties, Map? userPropertiesSetOnce, + Map? options, }) async { + _logUnsupportedOptions('identify', options); return handleWebMethodCall( MethodCall('identify', { 'userId': userId, @@ -159,7 +178,9 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { Future setPersonProperties({ Map? userPropertiesToSet, Map? userPropertiesToSetOnce, + Map? options, }) async { + _logUnsupportedOptions('setPersonProperties', options); if ((userPropertiesToSet?.isEmpty ?? true) && (userPropertiesToSetOnce?.isEmpty ?? true)) { return; @@ -181,12 +202,14 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { Map? properties, Map? userProperties, Map? userPropertiesSetOnce, + Map? options, }) async { final processedEvent = await _runBeforeSend( eventName, properties, userProperties: userProperties, userPropertiesSetOnce: userPropertiesSetOnce, + options: options, ); if (processedEvent == null) { printIfDebug('[PostHog] Event dropped by beforeSend: $eventName'); @@ -199,7 +222,11 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { userPropertiesSetOnce: processedEvent.userPropertiesSetOnce, ); - final extractedProperties = extracted.properties; + final extractedProperties = _withOptionProperties( + extracted.properties, + processedEvent.options, + processedEvent.event, + ); final extractedUserProperties = extracted.userProperties; final extractedUserPropertiesSetOnce = extracted.userPropertiesSetOnce; @@ -226,6 +253,33 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { ); } + /// posthog-js has no AI capture, so AI events are not sent on web. + @override + Future captureAi({ + required String eventName, + Map? properties, + Map? userProperties, + Map? userPropertiesSetOnce, + Map? options, + }) async { + printIfDebug('[PostHog] captureAi is not supported on web. ' + 'The event "$eventName" was not sent.'); + return null; + } + + /// posthog-js has no options for these keys, so they are sent as their + /// legacy properties, winning over a legacy property set on the event. + static Map? _withOptionProperties( + Map? properties, + Map? options, + String eventName, + ) { + final optionProperties = + eventOptionsToLegacyProperties(options, method: eventName); + if (optionProperties.isEmpty) return properties; + return {...?properties, ...optionProperties}; + } + @override Future captureLog({ required String body, @@ -255,6 +309,7 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { Future screen({ required String screenName, Map? properties, + Map? options, }) async { // The screen name argument wins over a properties `$screen_name`. // beforeSend still runs after this and can change the name. @@ -266,6 +321,7 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { final processedEvent = await _runBeforeSend( PostHogEventName.screen, propsWithScreenName, + options: options, ); if (processedEvent == null) { printIfDebug('[PostHog] Screen event dropped by beforeSend: $screenName'); @@ -276,6 +332,7 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { await capture( eventName: processedEvent.event, properties: processedEvent.properties?.cast(), + options: processedEvent.options, ); return; } @@ -285,7 +342,11 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { screenName; _currentScreen = finalScreenName; processedEvent.properties?.remove(PostHogPropertyName.screenName); - final remaining = processedEvent.properties; + final remaining = _withOptionProperties( + processedEvent.properties, + processedEvent.options, + PostHogEventName.screen, + ); return handleWebMethodCall( MethodCall('screen', { @@ -296,7 +357,11 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { } @override - Future alias({required String alias}) async { + Future alias({ + required String alias, + Map? options, + }) async { + _logUnsupportedOptions('alias', options); return handleWebMethodCall(MethodCall('alias', {'alias': alias})); } @@ -393,8 +458,9 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { } @override - Future reloadFeatureFlags() async { - return handleWebMethodCall(const MethodCall('reloadFeatureFlags')); + Future reloadFeatureFlags() async { + return featureFlagsLoadedFromMap( + await handleWebMethodCall(const MethodCall('reloadFeatureFlags'))); } @override @@ -442,7 +508,9 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { required String groupType, required String groupKey, Map? groupProperties, + Map? options, }) async { + _logUnsupportedOptions('group', options); return handleWebMethodCall( MethodCall('group', { 'groupType': groupType, @@ -544,6 +612,7 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { required Object error, StackTrace? stackTrace, Map? properties, + Map? options, }) async { try { final exceptionData = DartExceptionProcessor.processException( @@ -558,6 +627,7 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { final processedEvent = await _runBeforeSend( PostHogEventName.exception, exceptionData.cast(), + options: options, ); if (processedEvent == null) { printIfDebug( @@ -570,12 +640,18 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { await capture( eventName: processedEvent.event, properties: processedEvent.properties?.cast(), + options: processedEvent.options, ); return; } final normalizedData = PropertyNormalizer.normalize( - processedEvent.properties?.cast() ?? {}, + _withOptionProperties( + processedEvent.properties?.cast(), + processedEvent.options, + PostHogEventName.exception, + ) ?? + {}, ); return await handleWebMethodCall( diff --git a/posthog_flutter/lib/src/core/capture_v1.dart b/posthog_flutter/lib/src/core/capture_v1.dart index 14e6d886..491f76f8 100644 --- a/posthog_flutter/lib/src/core/capture_v1.dart +++ b/posthog_flutter/lib/src/core/capture_v1.dart @@ -1,6 +1,5 @@ import 'dart:convert'; -import 'file_storage.dart'; import 'logger.dart'; /// The capture v1 endpoint for analytics events. @@ -10,21 +9,22 @@ const captureV1Path = '/i/v1/analytics/events'; /// stay under proxy and capture body limits. const captureV1MaxBatchBytes = 5 * 1024 * 1024; -/// The oldest events of [events] whose serialized size stays within -/// [maxBytes]. Each event is checked before it is added, so one that does -/// not fit starts the next batch, and the first event always goes, alone -/// when it is over the limit. -List takeCaptureV1Batch( - List events, { - int maxBytes = captureV1MaxBatchBytes, -}) { - var bytes = 0; - for (var i = 0; i < events.length; i++) { - bytes += utf8.encode(jsonEncode(events[i].event)).length; - if (i > 0 && bytes > maxBytes) return events.sublist(0, i); - } - return events; -} +/// The capture v1 endpoint for AI events. +const captureV1AiPath = '/i/v1/ai/events'; + +/// The default number of AI events kept queued. +const captureAiDefaultMaxQueueSize = 100; + +/// The default timeout of an AI request. +const captureAiDefaultTimeout = Duration(seconds: 60); + +/// The largest serialized AI event the SDK queues: PostHog's 8 MiB limit on +/// an AI event's properties, plus 64 KiB for the rest of the event. +const captureAiMaxEventBytes = 8 * 1024 * 1024 + 64 * 1024; + +/// The most AI event bytes kept queued; the oldest events are dropped +/// first. +const captureAiMaxQueueBytes = 50 * 1024 * 1024; /// Capture v1 statuses worth retrying. Everything else is terminal, /// including 3xx; 413 halves the batch instead. diff --git a/posthog_flutter/lib/src/core/file_storage.dart b/posthog_flutter/lib/src/core/file_storage.dart index 96175bfc..754d6a7f 100644 --- a/posthog_flutter/lib/src/core/file_storage.dart +++ b/posthog_flutter/lib/src/core/file_storage.dart @@ -9,9 +9,10 @@ import 'uuid.dart'; /// /// The persisted properties (identity, feature flags, consent, super /// properties) live in one JSON snapshot, `posthog_data.json`. Every queued -/// event is a file of its own in `posthog_queue/`, named after a UUIDv7 so -/// that the names sort in queueing order: queueing an event writes one small -/// file and leaves the others alone. +/// event is a file of its own in `posthog_queue/`, or `posthog_ai_queue/` +/// for AI events, named after a UUIDv7 so that the names sort in queueing +/// order: queueing an event writes one small file and leaves the others +/// alone. /// /// One storage at a time writes the snapshot of a directory: the first to /// use it locks `posthog.lock` until it is closed. Another storage on the @@ -42,11 +43,13 @@ class FileStorage { : _directory = '', _cache = {}, _role = _Role.secondary, - _queue = FileEventQueue._memory(); + _queue = FileEventQueue._memory(), + _aiQueue = FileEventQueue._memory(); static const _dataFileName = 'posthog_data.json'; static const _lockFileName = 'posthog.lock'; static const _queueDirectoryName = 'posthog_queue'; + static const _aiQueueDirectoryName = 'posthog_ai_queue'; /// The lock files held by storages of this isolate. A POSIX file lock /// belongs to the whole process and is released as soon as the process @@ -76,6 +79,7 @@ class FileStorage { RandomAccessFile? _lock; String? _lockPath; FileEventQueue? _queue; + FileEventQueue? _aiQueue; String _pathOf(String name) => '$_directory${Platform.pathSeparator}$name'; @@ -93,6 +97,11 @@ class FileStorage { _queue ??= FileEventQueue._(_pathOf(_queueDirectoryName), () => logger, includeExisting: _open() == _Role.primary); + /// The AI events waiting to be sent, apart from the other events. + FileEventQueue get aiQueue => _aiQueue ??= FileEventQueue._( + _pathOf(_aiQueueDirectoryName), () => logger, + includeExisting: _open() == _Role.primary); + /// Decides, on first use, whether this storage writes the snapshot. _Role _open() { final role = _role; @@ -367,19 +376,23 @@ class FileEventQueue { return _byteCount; } - /// Adds [event] at the end of the queue. - void add(Map event) { + /// Adds [event] at the end of the queue. [json] is the event already + /// encoded, and [bytes] its UTF-8 size, when the caller has them. + void add(Map event, {String? json, int? bytes}) { // Loaded before the new file exists, which would otherwise be listed // on top of being added. final ids = _ids; final id = generateUuidV7(); - String? encoded; - try { - encoded = jsonEncode(event); - } catch (_) { - // Reported below when it is written. + var encoded = json; + if (encoded == null) { + try { + encoded = jsonEncode(event); + } catch (_) { + // Reported below when it is written. + } } - ids.add(_track(id, encoded == null ? 0 : utf8.encode(encoded).length)); + ids.add(_track( + id, bytes ?? (encoded == null ? 0 : utf8.encode(encoded).length))); if (_directory.isEmpty) { _unwritten[id] = event; return; @@ -397,13 +410,25 @@ class FileEventQueue { /// Returns up to [count] events from the front of the queue, oldest /// first. - List peek(int count) { + /// + /// With [maxBytes], the events also stay within that serialized size. Each + /// event is checked before it is read, so one that does not fit is left + /// for the next peek, and the first event always comes, alone when it is + /// over the limit. + List peek(int count, {int? maxBytes}) { final events = []; final gone = {}; + var bytes = 0; for (final id in _ids) { if (events.length >= count) break; + final size = _sizes[id] ?? 0; + if (maxBytes != null && events.isNotEmpty && bytes + size > maxBytes) { + break; + } final event = _unwritten[id] ?? _read(id, gone); - if (event != null) events.add((id: id, event: event)); + if (event == null) continue; + events.add((id: id, event: event)); + bytes += size; } if (gone.isNotEmpty) { _ids.removeWhere(gone.contains); @@ -448,6 +473,19 @@ class FileEventQueue { oldest.forEach(_forget); } + /// Removes the oldest events until the queue holds at most [maxBytes], + /// always keeping the newest event. Returns how many were removed. + int removeOldestOver(int maxBytes) { + var total = byteCount; + var count = 0; + while (total > maxBytes && count < _ids.length - 1) { + total -= _sizes[_ids[count]] ?? 0; + count++; + } + removeOldest(count); + return count; + } + void _forget(String id) { _untrack(id); if (_unwritten.remove(id) == null && _directory.isNotEmpty) { diff --git a/posthog_flutter/lib/src/core/posthog_core.dart b/posthog_flutter/lib/src/core/posthog_core.dart index 43f7ab84..cbbf0c81 100644 --- a/posthog_flutter/lib/src/core/posthog_core.dart +++ b/posthog_flutter/lib/src/core/posthog_core.dart @@ -5,6 +5,7 @@ import 'dart:math'; import 'package:meta/meta.dart'; import '../feature_flag_result.dart'; +import '../feature_flags_loaded.dart'; import '../posthog_config.dart'; import 'feature_flag_utils.dart'; import 'feature_flags.dart'; @@ -14,6 +15,14 @@ import 'session_manager.dart'; import 'utils/utils.dart'; import 'uuid.dart'; +/// An event built by [PostHogCore.prepareEvent]: its properties, its +/// capture v1 options and the time it happened, as an ISO 8601 string. +typedef PostHogPreparedEvent = ({ + Map properties, + Map? options, + String timestamp, +}); + /// Stateful PostHog client with session management, identity, and feature flags. /// /// It extends [PostHogCoreStateless] with state management for sessions, @@ -142,28 +151,53 @@ abstract class PostHogCore extends PostHogCoreStateless { @protected String? getTimezone(); + /// The properties of an event: the ones the SDK sets, then the + /// registered ones, then the event's own [properties], each winning over + /// the ones before. A value set for an event changes that event only. + /// + /// Person processing is not a property: see [_personProcessingOptions]. Map _enrichProperties(Map? properties) { final now = DateTime.now().millisecondsSinceEpoch; // Resolved first: it may start a new session, which the debug // properties below then describe. final managedSessionId = _session.touch(now); - final callerSessionId = properties?[r'$session_id']; - final sessionId = callerSessionId is String && callerSessionId.isNotEmpty - ? callerSessionId - : managedSessionId; final timezone = getTimezone(); - return { - ...props, - ..._sessionProps, - ...?properties, + final enriched = { ...getContextProperties(), if (timezone != null) r'$timezone': timezone, ...getCommonEventProperties(), - r'$session_id': sessionId, - r'$process_person_profile': _hasPersonProcessing(), + r'$session_id': managedSessionId, r'$is_identified': _isIdentified(), ..._sessionDebugProperties(now), + ..._sessionProps, + ...props, + ...?properties, }; + // An empty or non-string session id would leave the event out of its + // session. + final sessionId = enriched[r'$session_id']; + if (sessionId is! String || sessionId.isEmpty) { + enriched[r'$session_id'] = managedSessionId; + } + return enriched; + } + + /// The [options] of an event with [properties], with + /// `process_person_profile: false` added when person processing is off, + /// the event is not [requested] to update the person, and neither an + /// option nor a `$process_person_profile` property says otherwise. + Map? _personProcessingOptions( + Map? options, + Map properties, { + required bool requested, + }) { + if (requested || + _hasPersonProcessing() || + properties[r'$process_person_profile'] != null || + options?['process_person_profile'] != null) { + return options; + } + return {...?options, 'process_person_profile': false}; } /// The state of the session and the queue, attached to every event to @@ -179,8 +213,8 @@ abstract class PostHogCore extends PostHogCoreStateless { } /// Adds [properties] to every later event until [reset], without - /// persisting them. They win over registered properties, and the event's - /// own properties win over them. + /// persisting them. Registered properties and the event's own win over + /// them. void registerForSession(Map properties) { wrap(() => _sessionProps.addAll(properties)); } @@ -292,10 +326,13 @@ abstract class PostHogCore extends PostHogCoreStateless { /// /// An empty [distinctId] is ignored, as are all calls while opted out or /// when `personProfiles` is `never`. + /// + /// The optional [options] are sent with the event this call sends. void identify( String distinctId, { Map? userProperties, Map? userPropertiesSetOnce, + Map? options, }) { wrap(() { if (distinctId.trim().isEmpty) { @@ -327,16 +364,19 @@ abstract class PostHogCore extends PostHogCoreStateless { _setPersonPropertiesForFlagsIfNeeded( userProperties, userPropertiesSetOnce); + final identifyProperties = _enrichProperties({ + 'distinct_id': distinctId, + r'$anon_distinct_id': previousDistinctId, + ...maybeAdd(r'$set', userProperties), + ...maybeAdd(r'$set_once', userPropertiesSetOnce), + }); identifyStateless( distinctId, - properties: _enrichProperties({ - 'distinct_id': distinctId, - r'$anon_distinct_id': previousDistinctId, - ...maybeAdd(r'$set', userProperties), - ...maybeAdd(r'$set_once', userPropertiesSetOnce), - }), + properties: identifyProperties, + options: options, ); - if (userProperties != null || userPropertiesSetOnce != null) { + if ((userProperties != null || userPropertiesSetOnce != null) && + !_isPersonless(identifyProperties, options)) { _cachedPersonProperties = _personPropertiesHash( distinctId, userProperties, userPropertiesSetOnce); } @@ -345,10 +385,12 @@ abstract class PostHogCore extends PostHogCoreStateless { // There is no anonymous history to link: the id already is the // anonymous one, so the transition is recorded with a $set. setPersistedProperty(PostHogPersistedProperty.personMode, 'identified'); - capture(r'$set', properties: { - r'$set': userProperties ?? {}, - r'$set_once': userPropertiesSetOnce ?? {}, - }); + capture(r'$set', + properties: { + r'$set': userProperties ?? {}, + r'$set_once': userPropertiesSetOnce ?? {}, + }, + options: options); if (hasUserProperties) _reloadFeatureFlags(); } else if (hasUserProperties) { // Person property changes are processed asynchronously by PostHog, @@ -356,6 +398,7 @@ abstract class PostHogCore extends PostHogCoreStateless { setPersonProperties( userPropertiesToSet: userProperties, userPropertiesToSetOnce: userPropertiesSetOnce, + options: options, ); } else { logger.info('identify was called with the current distinct id of an ' @@ -370,42 +413,123 @@ abstract class PostHogCore extends PostHogCoreStateless { /// for person processing even for an anonymous user. `$groups` in /// [properties] apply to this event only; use [group] to associate the /// user with a group. - void capture(String event, {Map? properties}) { + /// + /// The capture v1 [options] are sent with the event as they are. + void capture( + String event, { + Map? properties, + Map? options, + }) { wrap(() { - if (_ignoredWhileOptedOut('posthog.capture')) return; - - final userProperties = properties?[r'$set']; - final userPropertiesSetOnce = properties?[r'$set_once']; - if (_personProfiles != PostHogPersonProfiles.never && - (_isNonEmptyMap(userProperties) || - _isNonEmptyMap(userPropertiesSetOnce))) { - _enablePersonProcessing(); - } - _setPersonPropertiesForFlagsIfNeeded( - _asPropertyMap(userProperties), - _asPropertyMap(userPropertiesSetOnce), - ); + final prepared = + _prepareEvent(event, properties: properties, options: options); + if (prepared != null) _queuePrepared(event, prepared); + }); + } - final allProperties = _enrichProperties(properties); - // Once an event is person-processed, all later ones are too. - if (allProperties[r'$process_person_profile'] == true) { - _enablePersonProcessing(); - } + /// Builds the event [capture] would send, with every property and option + /// the SDK adds, so that it can still be changed before + /// [capturePrepared] queues it. Returns null when the client is closed + /// or opted out. + /// + /// Like [capture], person properties in [properties] ask for person + /// processing, and the event starts or extends the session. They feed + /// flag evaluation only as [capturePrepared] queues the event. + PostHogPreparedEvent? prepareEvent( + String event, { + Map? properties, + Map? options, + }) => + wrap( + () => _prepareEvent(event, properties: properties, options: options)); + + /// Queues an event built by [prepareEvent], possibly changed since. + /// Unlike [capture], it adds nothing to it. Its `$set` / `$set_once` + /// feed flag evaluation. + /// + /// With [ai], the event goes to PostHog's AI endpoint from a queue of its + /// own, which drops a serialized event over its size limit. + /// + /// Returns the event's uuid, or null when it is not queued: the client + /// is closed or opted out, or the AI event is over the size limit. + String? capturePrepared( + String event, + PostHogPreparedEvent prepared, { + bool ai = false, + }) => + wrap(() { + if (_ignoredWhileOptedOut('posthog.capture')) return null; + return _queuePrepared(event, prepared, ai: ai); + }); - captureStateless(getDistinctId(), event, properties: allProperties); - if (event == r'$set' || event == r'$identify') { - final set = allProperties[r'$set']; - final setOnce = allProperties[r'$set_once']; - if (set is Map || setOnce is Map) { - _cachedPersonProperties = - _personPropertiesHash(getDistinctId(), set, setOnce); - } + /// [options] with `process_person_profile: false` added when person + /// processing is off and [properties] neither ask for it nor set + /// `$process_person_profile`, as [prepareEvent] decides it. + Map? personProcessingOptions( + Map? options, + Map properties, + ) => + _personProcessingOptions(options, properties, + requested: _requestsPersonProcessing(properties)); + + PostHogPreparedEvent? _prepareEvent( + String event, { + Map? properties, + Map? options, + }) { + if (_ignoredWhileOptedOut('posthog.capture')) return null; + + final allProperties = _enrichProperties(properties); + // Once an event is person-processed, all later ones are too. A value + // passed for this event alone doesn't count. + if (_hasPersonProcessing()) { + _enablePersonProcessing(); + } + return ( + properties: allProperties, + options: _personProcessingOptions( + options, + allProperties, + requested: _requestsPersonProcessing(properties), + ), + timestamp: currentISOTime(), + ); + } + + String? _queuePrepared( + String event, + PostHogPreparedEvent prepared, { + bool ai = false, + }) { + final (:properties, :options, :timestamp) = prepared; + // Taken from the event as queued, after the beforeSend callbacks, so a + // value they removed or an event they dropped neither reaches /flags + // nor turns on person processing for later events. + if (_requestsPersonProcessing(properties)) _enablePersonProcessing(); + _setPersonPropertiesForFlagsIfNeeded( + _asPropertyMap(properties[r'$set']), + _asPropertyMap(properties[r'$set_once']), + ); + final uuid = captureStateless(getDistinctId(), event, + properties: properties, options: options, timestamp: timestamp, ai: ai); + // PostHog drops an AI event that is not an `$ai_*` event, so it never + // updates the person. + if (!ai && (event == r'$set' || event == r'$identify')) { + final set = properties[r'$set']; + final setOnce = properties[r'$set_once']; + if ((set is Map || setOnce is Map) && + !_isPersonless(properties, options)) { + _cachedPersonProperties = + _personPropertiesHash(getDistinctId(), set, setOnce); } - }); + } + return uuid; } /// Creates an alias for a user. An empty [alias] is ignored. - void alias(String alias) { + /// + /// The optional [options] are sent with the `$create_alias` event. + void alias(String alias, {Map? options}) { wrap(() { if (alias.trim().isEmpty) { logger.warn('alias was called with an empty alias. ' @@ -415,7 +539,8 @@ abstract class PostHogCore extends PostHogCoreStateless { if (_ignoredWhileOptedOut('posthog.alias')) return; if (!_requirePersonProcessing('posthog.alias')) return; - aliasStateless(alias, getDistinctId(), properties: _enrichProperties({})); + aliasStateless(alias, getDistinctId(), + properties: _enrichProperties(null), options: options); }); } @@ -440,10 +565,13 @@ abstract class PostHogCore extends PostHogCoreStateless { /// key changes, the properties stored for the previous key are dropped and /// flags are reloaded. A call with an empty [groupType] /// or [groupKey] is ignored. + /// + /// The optional [options] are sent with the `$groupidentify` event. void group( String groupType, String groupKey, { Map? groupProperties, + Map? options, }) { wrap(() { if (groupType.trim().isEmpty || groupKey.trim().isEmpty) { @@ -468,8 +596,9 @@ abstract class PostHogCore extends PostHogCoreStateless { groupType, groupKey, distinctId: getDistinctId(), - eventProperties: _enrichProperties({}), + eventProperties: _enrichProperties(null), groupProperties: groupProperties, + options: options, ); }); } @@ -923,6 +1052,12 @@ abstract class PostHogCore extends PostHogCoreStateless { await wrap(_flagsAsync); } + /// The enabled flags currently served, and whether the latest load failed. + PostHogFeatureFlagsLoaded featureFlagsLoaded() => PostHogFeatureFlagsLoaded( + variants: _getFeatureFlags() ?? const {}, + errorsLoading: _getStoredFlagDetails()?.requestError != null, + ); + /// Registers a callback for when feature flags are loaded. A callback /// registered right after the client is created also hears about the flags /// it starts with, bootstrapped or cached. Returns an unsubscribe function. @@ -943,6 +1078,11 @@ abstract class PostHogCore extends PostHogCoreStateless { }; } + bool _requestsPersonProcessing(Map? properties) => + _personProfiles != PostHogPersonProfiles.never && + (_isNonEmptyMap(properties?[r'$set']) || + _isNonEmptyMap(properties?[r'$set_once'])); + bool _hasPersonProcessing() { if (_personProfiles == PostHogPersonProfiles.always) return true; if (_personProfiles == PostHogPersonProfiles.never) return false; @@ -989,9 +1129,12 @@ abstract class PostHogCore extends PostHogCoreStateless { /// Sets properties on the person profile. They also feed feature flag /// evaluation from the next flags reload on. + /// + /// The optional [options] are sent with the `$set` event. void setPersonProperties({ Map? userPropertiesToSet, Map? userPropertiesToSetOnce, + Map? options, }) { wrap(() { final isSetEmpty = @@ -1006,7 +1149,9 @@ abstract class PostHogCore extends PostHogCoreStateless { final hash = _personPropertiesHash( getDistinctId(), userPropertiesToSet, userPropertiesToSetOnce); - if (_cachedPersonProperties == hash) { + // A personless `$set` doesn't update the person, so it is never a + // duplicate. + if (_cachedPersonProperties == hash && !_isPersonless(null, options)) { logger.info( 'A duplicate setPersonProperties call was made. It has been ignored.'); return; @@ -1018,10 +1163,12 @@ abstract class PostHogCore extends PostHogCoreStateless { }; setPersonPropertiesForFlags(mergedProperties); - capture(r'$set', properties: { - r'$set': userPropertiesToSet ?? {}, - r'$set_once': userPropertiesToSetOnce ?? {}, - }); + capture(r'$set', + properties: { + r'$set': userPropertiesToSet ?? {}, + r'$set_once': userPropertiesToSetOnce ?? {}, + }, + options: options); }); } @@ -1042,6 +1189,16 @@ abstract class PostHogCore extends PostHogCoreStateless { static bool _isNonEmptyMap(Object? value) => value is Map && value.isNotEmpty; + /// Whether [options], or else [properties], turn person processing off + /// for their event. An option wins over the property. + static bool _isPersonless( + Map? properties, + Map? options, + ) => + (options?['process_person_profile'] ?? + properties?[r'$process_person_profile']) == + false; + static Map? _asPropertyMap(Object? value) { if (value is! Map) return null; return { diff --git a/posthog_flutter/lib/src/core/posthog_core_stateless.dart b/posthog_flutter/lib/src/core/posthog_core_stateless.dart index ee30b2df..2cd81cb7 100644 --- a/posthog_flutter/lib/src/core/posthog_core_stateless.dart +++ b/posthog_flutter/lib/src/core/posthog_core_stateless.dart @@ -87,12 +87,15 @@ Duration captureRetryDelay({ abstract class PostHogCoreStateless { final String _apiKey; final String _host; - int _flushAt; - int _maxBatchSize; - final int _maxQueueSize; final Duration _flushInterval; final PostHogCompression _compression; + /// Analytics events, sent to [captureV1Path]. + late final _CaptureLane _analytics; + + /// AI events, sent to [captureV1AiPath] from a queue of their own. + late final _CaptureLane _ai; + final bool _defaultOptIn; /// How long a request may go without progress: connecting, a chunk of @@ -112,30 +115,17 @@ abstract class PostHogCoreStateless { static const _flagsRetryCount = 1; static const _flagsRetryDelay = Duration(milliseconds: 300); - /// The [_failedFlushes] at which the backoff reaches its 30 second cap. + /// The [_CaptureLane.failedFlushes] at which the backoff reaches its 30 + /// second cap. static const _maxBackoffStep = 6; /// How many same-origin 307/308 redirects a capture request follows. static const _maxCaptureRedirects = 5; - /// The identity of the last capture request whose events are still to be - /// retried. Kept in memory: after a restart the retry is a new request. - CaptureV1Identity? _pendingCaptureIdentity; - - /// Flushes in a row whose batch failed with a transient error or had - /// events the server asked to retry. Each one pauses the queue for longer, - /// see [captureRetryDelay], so a failure that lasts, like a missing - /// capture route, doesn't resend the batch with every capture. A delivered - /// or dropped batch resets it. - int _failedFlushes = 0; - /// The source of the backoff jitter: a uniform value in `[0, 1)`. @visibleForTesting double Function() jitterUnit = Random().nextDouble; - /// Whether this client already warned that capture returned a 404. - bool _warnedCaptureNotFound = false; - /// The latest consent decision made through this client. It wins over the /// stored one: [clearPersistedOptOut] removes the stored decision while /// this client keeps honoring it, and a decision the storage cannot @@ -144,9 +134,6 @@ abstract class PostHogCoreStateless { @protected late final SimpleEventEmitter events; - Timer? _flushTimer; - Timer? _retryAfterTimer; - Future? _flushFuture; /// Set by [close]: later calls are ignored, the periodic flush stops, and /// a failed request is not retried. @@ -167,9 +154,6 @@ abstract class PostHogCoreStateless { required this.storage, }) : _apiKey = config.projectToken, _host = removeTrailingSlash(config.host), - _flushAt = config.flushAt < 1 ? 1 : config.flushAt, - _maxBatchSize = config.maxBatchSize < 1 ? 1 : config.maxBatchSize, - _maxQueueSize = config.maxQueueSize < 1 ? 1 : config.maxQueueSize, _flushInterval = config.flushInterval, _compression = config.compression, _defaultOptIn = !config.optOut { @@ -181,16 +165,54 @@ abstract class PostHogCoreStateless { debug(true); } - final queue = storage.queue; - final overflow = queue.length - _maxQueueSize; - if (overflow > 0) { - queue.removeOldest(overflow); + final flushAt = config.flushAt < 1 ? 1 : config.flushAt; + final maxBatchSize = config.maxBatchSize < 1 ? 1 : config.maxBatchSize; + _analytics = _CaptureLane( + path: captureV1Path, + queue: storage.queue, + flushAt: flushAt, + maxBatchSize: maxBatchSize, + maxQueueSize: config.maxQueueSize < 1 ? 1 : config.maxQueueSize, + compression: config.compression, + timeout: _requestTimeout, + ); + final aiMaxQueueSize = config.captureAiMaxQueueSize ?? 0; + final aiTimeout = config.captureAiTimeout ?? Duration.zero; + final aiMaxEventBytes = config.captureAiMaxEventBytes ?? 0; + if (aiMaxEventBytes > captureAiMaxEventBytes) { + logger.warn('captureAiMaxEventBytes $aiMaxEventBytes is over the ' + '$captureAiMaxEventBytes byte ceiling, using the ceiling.'); } + _ai = _CaptureLane( + path: captureV1AiPath, + queue: storage.aiQueue, + flushAt: flushAt, + maxBatchSize: maxBatchSize, + maxQueueSize: + aiMaxQueueSize > 0 ? aiMaxQueueSize : captureAiDefaultMaxQueueSize, + compression: config.captureAiCompression ?? PostHogCompression.gzip, + timeout: aiTimeout > Duration.zero ? aiTimeout : captureAiDefaultTimeout, + maxEventBytes: + aiMaxEventBytes > 0 && aiMaxEventBytes < captureAiMaxEventBytes + ? aiMaxEventBytes + : captureAiMaxEventBytes, + maxQueueBytes: captureAiMaxQueueBytes, + ); + + for (final lane in [_analytics, _ai]) { + final queue = lane.queue; + final overflow = queue.length - lane.maxQueueSize; + if (overflow > 0) { + queue.removeOldest(overflow); + } + final maxQueueBytes = lane.maxQueueBytes; + if (maxQueueBytes != null) queue.removeOldestOver(maxQueueBytes); - // Events left over from a previous run go out with the first periodic - // flush instead of waiting for the next capture. - if (queue.length > 0) { - _scheduleFlush(); + // Events left over from a previous run go out with the first periodic + // flush instead of waiting for the next capture. + if (queue.length > 0) { + _scheduleFlush(lane); + } } } @@ -279,11 +301,9 @@ abstract class PostHogCoreStateless { required String event, required Map properties, }) { - var eventProperties = { - ...properties, - ...getCommonEventProperties(), - }; - // Minimized once all SDK properties are in. + // The properties come complete, the SDK's included: nothing is added + // here, so a property the beforeSend callbacks removed stays removed. + var eventProperties = {...properties}; if (event == r'$feature_flag_called' && eventProperties[r'$feature_flag_has_experiment'] == false && isMinimalFlagCalledEventsEnabled()) { @@ -308,25 +328,34 @@ abstract class PostHogCoreStateless { void identifyStateless( String distinctId, { required Map properties, + Map? options, }) { _enqueue( + _analytics, 'identify', _buildPayload( distinctId: distinctId, event: r'$identify', properties: properties, ), + options: options, ); } + /// Queues [event] and returns its uuid, or null when it is not queued. + /// With [ai], the event goes to the AI queue, which drops an event over + /// its size limit. @protected - void captureStateless( + String? captureStateless( String distinctId, String event, { required Map properties, Map? options, + String? timestamp, + bool ai = false, }) { - _enqueue( + return _enqueue( + ai ? _ai : _analytics, 'capture', _buildPayload( distinctId: distinctId, @@ -334,6 +363,7 @@ abstract class PostHogCoreStateless { properties: properties, ), options: options, + timestamp: timestamp, ); } @@ -342,8 +372,10 @@ abstract class PostHogCoreStateless { String alias, String distinctId, { required Map properties, + Map? options, }) { _enqueue( + _analytics, 'alias', _buildPayload( distinctId: distinctId, @@ -354,6 +386,7 @@ abstract class PostHogCoreStateless { 'alias': alias, }, ), + options: options, ); } @@ -364,8 +397,10 @@ abstract class PostHogCoreStateless { required String distinctId, required Map eventProperties, Map? groupProperties, + Map? options, }) { _enqueue( + _analytics, 'capture', _buildPayload( distinctId: distinctId, @@ -377,6 +412,7 @@ abstract class PostHogCoreStateless { ...eventProperties, }, ), + options: options, ); } @@ -459,13 +495,16 @@ abstract class PostHogCoreStateless { }); } - /// Queues [message]. Its capture v1 [options] are queued with it; the - /// legacy option properties are converted only when the request is built, - /// see [captureV1Event]. - void _enqueue( + /// Queues [message] on [lane] and returns its uuid, or null when it is + /// over the lane's event size limit. Its capture v1 [options] are queued + /// with it; the legacy option properties are converted only when the + /// request is built, see [captureV1Event]. + String? _enqueue( + _CaptureLane lane, String type, Map message, { Map? options, + String? timestamp, }) { final prepared = { ...message, @@ -476,26 +515,49 @@ abstract class PostHogCoreStateless { 'type': type, 'library': postHogFlutterSdkName, 'library_version': postHogFlutterVersion, - 'timestamp': currentISOTime(), + 'timestamp': timestamp ?? currentISOTime(), 'uuid': generateUuidV7(), }; - final queue = storage.queue; - final overflow = queue.length - _maxQueueSize + 1; + + // Measured as queued, before compression. + String? json; + int? bytes; + final maxEventBytes = lane.maxEventBytes; + if (maxEventBytes != null) { + json = jsonEncode(prepared); + bytes = utf8.encode(json).length; + if (bytes > maxEventBytes) { + // Name and size only: AI properties can hold prompts and media. + logger.warn('Dropping AI event ${message['event']} of $bytes bytes, ' + 'over the $maxEventBytes byte limit.'); + return null; + } + } + + final queue = lane.queue; + final overflow = queue.length - lane.maxQueueSize + 1; if (overflow > 0) { queue.removeOldest(overflow); logger.warn('Queue is full, the oldest event is dropped.'); } - queue.add(prepared); + queue.add(prepared, json: json, bytes: bytes); + final maxQueueBytes = lane.maxQueueBytes; + if (maxQueueBytes != null && queue.removeOldestOver(maxQueueBytes) > 0) { + logger.warn('Queue is over $maxQueueBytes bytes, the oldest events are ' + 'dropped.'); + } events.emit(type, prepared); // A full request's worth of bytes flushes like flushAt does, so large // events go out before the queue starts dropping them. - if (queue.length >= _flushAt || queue.byteCount >= captureV1MaxBatchBytes) { - _flushBackground(); + if (queue.length >= lane.flushAt || + queue.byteCount >= captureV1MaxBatchBytes) { + _flushBackground(lane); } - _scheduleFlush(); + _scheduleFlush(lane); + return prepared['uuid'] as String; } /// The event properties as they are queued and sent: values JSON cannot @@ -512,107 +574,104 @@ abstract class PostHogCoreStateless { '$key': converted, }; - void _scheduleFlush() { + void _scheduleFlush(_CaptureLane lane) { if (!_closed && - _retryAfterTimer == null && + lane.retryAfterTimer == null && _flushInterval > Duration.zero && - _flushTimer == null) { - _flushTimer = Timer(_flushInterval, () { + lane.flushTimer == null) { + lane.flushTimer = Timer(_flushInterval, () { // Cleared first: a timer firing during a flush in flight only joins // that flush, and a stale reference would block every later re-arm. - _flushTimer = null; - _flushBackground(); + lane.flushTimer = null; + _flushBackground(lane); }); } } - void _clearFlushTimer() { - _flushTimer?.cancel(); - _flushTimer = null; - } - - /// Counts one more failed flush and stops sending events for the backoff - /// it calls for, at least the server's [retryAfter]. - void _backOff(Duration? retryAfter) { - if (_failedFlushes < _maxBackoffStep) _failedFlushes++; - _pauseFlush(captureRetryDelay( - attempt: _failedFlushes, - jitterUnit: jitterUnit(), - retryAfter: retryAfter, - )); + /// Counts one more failed flush of [lane] and stops sending its events + /// for the backoff it calls for, at least the server's [retryAfter]. + void _backOff(_CaptureLane lane, Duration? retryAfter) { + if (lane.failedFlushes < _maxBackoffStep) lane.failedFlushes++; + _pauseFlush( + lane, + captureRetryDelay( + attempt: lane.failedFlushes, + jitterUnit: jitterUnit(), + retryAfter: retryAfter, + )); } - /// Stops sending events for [delay]. - void _pauseFlush(Duration delay) { - _clearFlushTimer(); - _retryAfterTimer?.cancel(); - _retryAfterTimer = Timer(delay, () { - _retryAfterTimer = null; - if (!_closed && - _flushInterval > Duration.zero && - storage.queue.length > 0) { - _flushBackground(); + /// Stops sending the events of [lane] for [delay]. + void _pauseFlush(_CaptureLane lane, Duration delay) { + lane.clearFlushTimer(); + lane.retryAfterTimer?.cancel(); + lane.retryAfterTimer = Timer(delay, () { + lane.retryAfterTimer = null; + if (!_closed && _flushInterval > Duration.zero && lane.queue.length > 0) { + _flushBackground(lane); } }); } - void _flushBackground() { - flush().catchError((e) { + void _flushBackground(_CaptureLane lane) { + _flushLane(lane).catchError((e) { logger.error('Error while flushing PostHog', e); }); } - /// Flushes the queue of pending events. + /// Flushes the queues of pending events and AI events. /// If a flush is already in progress, returns the existing future to avoid /// concurrent flushes sending duplicate events. - Future flush() { - if (_flushFuture != null) return _flushFuture!; - if (_retryAfterTimer != null) return Future.value(); - _flushFuture = _doFlush().whenComplete(() => _flushFuture = null); - return _flushFuture!; + Future flush() async { + await Future.wait([_flushLane(_analytics), _flushLane(_ai)]); } - Future _doFlush() async { - _clearFlushTimer(); + Future _flushLane(_CaptureLane lane) { + final inFlight = lane.flushFuture; + if (inFlight != null) return inFlight; + if (lane.retryAfterTimer != null) return Future.value(); + final flush = _doFlush(lane).whenComplete(() => lane.flushFuture = null); + lane.flushFuture = flush; + return flush; + } - final queue = storage.queue; - final sentMessages = >[]; + Future _doFlush(_CaptureLane lane) async { + lane.clearFlushTimer(); - try { - while (!_closed) { - // Peeked again after every request, so events queued in the meantime - // go out with the same flush. - final batch = takeCaptureV1Batch(queue.peek(_maxBatchSize)); - if (batch.isEmpty) { - if (queue.length > 0) _scheduleFlush(); - break; - } - if (!await _sendBatch(batch, sentMessages)) break; - } - } finally { - if (sentMessages.isNotEmpty) { - events.emit('flush', sentMessages); + final queue = lane.queue; + + while (!_closed) { + // Peeked again after every request, so events queued in the meantime + // go out with the same flush. The queue sizes the batch before + // reading it, so events past the batch are not decoded. + final batch = + queue.peek(lane.maxBatchSize, maxBytes: captureV1MaxBatchBytes); + if (batch.isEmpty) { + if (queue.length > 0) _scheduleFlush(lane); + break; } + if (!await _sendBatch(lane, batch)) break; } } /// Sends [batch] to capture v1 and removes from the queue the events that - /// are done: delivered, or dropped for good. Adds the delivered ones to - /// [sent]. + /// are done: delivered, or dropped for good. Emits `flush` with the + /// delivered ones right away, so a long flush doesn't hold on to the + /// payloads of every batch it sent. /// /// Returns whether the flush goes on with the rest of the queue. It stops /// while events of [batch] wait for a later retry: the queue backs off, /// and sends them again once the pause is over. It also stops after a 413 /// halves the batch size. Future _sendBatch( + _CaptureLane lane, List batch, - List> sent, ) async { - final queue = storage.queue; + final queue = lane.queue; final Set retryUuids; final Duration? retryAfter; try { - (:retryUuids, :retryAfter) = await _postCaptureV1(batch); + (:retryUuids, :retryAfter) = await _postCaptureV1(lane, batch); } catch (e) { if (_closed) rethrow; if (e is PostHogFetchHttpError && @@ -620,33 +679,34 @@ abstract class PostHogCoreStateless { batch.length > 1) { // flushAt stays within the batch size, so the queue doesn't pile up // more events than one batch can carry. - _maxBatchSize = (batch.length ~/ 2).clamp(1, _maxBatchSize); - _flushAt = (_flushAt ~/ 2).clamp(1, _maxBatchSize); - logger.warn('Received 413, reducing batch size to $_maxBatchSize'); + lane.maxBatchSize = (batch.length ~/ 2).clamp(1, lane.maxBatchSize); + lane.flushAt = (lane.flushAt ~/ 2).clamp(1, lane.maxBatchSize); + logger + .warn('Received 413, reducing batch size to ${lane.maxBatchSize}'); // The smaller batches go out with the next flush, not right away. - _scheduleFlush(); + _scheduleFlush(lane); return false; } if (e is PostHogFetchHttpError && e.status == HttpStatus.notFound && - !_warnedCaptureNotFound) { - _warnedCaptureNotFound = true; + !lane.warnedNotFound) { + lane.warnedNotFound = true; // Printed even without debug: the events stay queued, and nothing // else tells the app that the route is missing. - debugPrint('[PostHog] [WARN] $captureV1Path returned 404. ' + debugPrint('[PostHog] [WARN] ${lane.path} returned 404. ' 'Events stay queued and are retried. If you use a reverse ' 'proxy or self-host PostHog, make sure it serves ' - '$captureV1Path.'); + '${lane.path}.'); } // The pause re-arms the periodic flush: otherwise queued events sit // until the next capture (forever in an idle app after an offline // failure). if (_isTransientCaptureError(e)) { - _backOff(e is PostHogFetchHttpError ? e.retryAfter : null); + _backOff(lane, e is PostHogFetchHttpError ? e.retryAfter : null); } else { queue.remove([for (final queued in batch) queued.id]); - _failedFlushes = 0; - _scheduleFlush(); + lane.failedFlushes = 0; + _scheduleFlush(lane); } events.emit('error', e); rethrow; @@ -659,16 +719,18 @@ abstract class PostHogCoreStateless { // Removed by id: the queue may have changed while the batch was in // flight, e.g. its oldest events dropped to make room. queue.remove([for (final queued in delivered) queued.id]); - sent.addAll([for (final queued in delivered) queued.event]); + if (delivered.isNotEmpty) { + events.emit('flush', [for (final queued in delivered) queued.event]); + } if (delivered.length == batch.length) { - _failedFlushes = 0; + lane.failedFlushes = 0; return true; } // Counts only: uuids and server details can identify users. logger.info('Capture asked to retry ${batch.length - delivered.length} ' 'of ${batch.length} events.'); - _backOff(retryAfter); + _backOff(lane, retryAfter); return false; } @@ -683,13 +745,14 @@ abstract class PostHogCoreStateless { /// Throws [PostHogFetchHttpError] for a non-2xx status and /// [PostHogFetchNetworkError] for a transport failure. Future<({Set retryUuids, Duration? retryAfter})> _postCaptureV1( + _CaptureLane lane, List batch, ) async { final uuids = { for (final queued in batch) if (queued.event['uuid'] case final String uuid) uuid, }; - final pending = _pendingCaptureIdentity; + final pending = lane.pendingIdentity; final identity = pending != null && sameUuids(pending.uuids, uuids) ? pending.next() : CaptureV1Identity( @@ -697,7 +760,7 @@ abstract class PostHogCoreStateless { requestId: generateUuidV7(), createdAt: currentISOTime(), ); - _pendingCaptureIdentity = identity; + lane.pendingIdentity = identity; final body = jsonEncode({ 'created_at': identity.createdAt, @@ -714,11 +777,11 @@ abstract class PostHogCoreStateless { }; // A transport failure keeps the identity, so the resend reuses it. - final response = await _fetchCaptureV1(body, headers); + final response = await _fetchCaptureV1(lane, body, headers); if (response.status < 200 || response.status >= 300) { if (!isRetriableCaptureV1Status(response.status)) { - _pendingCaptureIdentity = null; + lane.pendingIdentity = null; } throw PostHogFetchHttpError( response.status, @@ -737,7 +800,7 @@ abstract class PostHogCoreStateless { 'events for good.'); } final retryUuids = results?.retry ?? const {}; - _pendingCaptureIdentity = + lane.pendingIdentity = retryUuids.isEmpty ? null : identity.withUuids(retryUuids); return (retryUuids: retryUuids, retryAfter: response.retryAfter); } @@ -748,14 +811,18 @@ abstract class PostHogCoreStateless { /// is, and is terminal. Future<({int status, String? body, Duration? retryAfter, String? location})> _fetchCaptureV1( + _CaptureLane lane, String body, Map headers, ) async { final origin = Uri.parse(_host); - var url = Uri.parse('$_host$captureV1Path'); + var url = Uri.parse('$_host${lane.path}'); for (var redirects = 0;; redirects++) { final response = await _fetchOnce(url, body, - headers: headers, deliveredOnBodyFailure: true); + headers: headers, + deliveredOnBodyFailure: true, + timeout: lane.timeout, + compression: lane.compression); if (response.status != 307 && response.status != 308) return response; final location = response.location; final target = location == null ? null : url.resolve(location); @@ -799,8 +866,9 @@ abstract class PostHogCoreStateless { ); } - /// Sends one request, aborted once it makes no progress for - /// [_requestTimeout]. A transport failure is thrown as + /// Sends one request, aborted once it makes no progress for [timeout], + /// [_requestTimeout] by default, and compressed with [compression], the + /// configured one by default. A transport failure is thrown as /// [PostHogFetchNetworkError], except, with [deliveredOnBodyFailure], one /// that happens after a 2xx status arrived: the response is then returned /// without a body. @@ -815,10 +883,14 @@ abstract class PostHogCoreStateless { String body, { Map headers = const {}, bool deliveredOnBodyFailure = false, + Duration timeout = _requestTimeout, + PostHogCompression? compression, }) async { - final attempt = _FetchAttempt(_requestTimeout, _responseBodyTimeout); + final attempt = _FetchAttempt(timeout, + timeout > _responseBodyTimeout ? timeout : _responseBodyTimeout); try { - return await attempt.guard(_fetch(url, body, attempt, headers)); + return await attempt.guard( + _fetch(url, body, attempt, headers, compression ?? _compression)); } catch (e) { final status = attempt.status; if (deliveredOnBodyFailure && @@ -863,6 +935,7 @@ abstract class PostHogCoreStateless { String body, _FetchAttempt attempt, Map headers, + PostHogCompression compression, ) async { final request = await _httpClient.postUrl(url); attempt.attachRequest(request); @@ -879,7 +952,7 @@ abstract class PostHogCoreStateless { headers.forEach(request.headers.set); final bytes = utf8.encode(body); final List payload; - if (_compression == PostHogCompression.gzip) { + if (compression == PostHogCompression.gzip) { request.headers.set(HttpHeaders.contentEncodingHeader, 'gzip'); payload = gzip.encode(bytes); } else { @@ -918,14 +991,76 @@ abstract class PostHogCoreStateless { /// storage loses them. void close() { _closed = true; - _clearFlushTimer(); - _retryAfterTimer?.cancel(); - _retryAfterTimer = null; + for (final lane in [_analytics, _ai]) { + lane.clearFlushTimer(); + lane.retryAfterTimer?.cancel(); + lane.retryAfterTimer = null; + } _httpClient.close(force: true); storage.close(); } } +/// A queue of events and the state of sending it to one capture v1 +/// endpoint. +class _CaptureLane { + _CaptureLane({ + required this.path, + required this.queue, + required this.flushAt, + required this.maxBatchSize, + required this.maxQueueSize, + required this.compression, + required this.timeout, + this.maxEventBytes, + this.maxQueueBytes, + }); + + final String path; + final FileEventQueue queue; + + /// Lowered with [maxBatchSize] by a 413, and kept within it. + int flushAt; + + /// Lowered by a 413. + int maxBatchSize; + final int maxQueueSize; + final PostHogCompression compression; + + /// How long a request may go without progress. Connecting is also bounded + /// by the HTTP client's connection timeout, shared by every endpoint. + final Duration timeout; + + /// The largest serialized event queued; null for no limit. + final int? maxEventBytes; + + /// The most serialized event bytes kept queued; null for no limit. + final int? maxQueueBytes; + + /// The identity of the last request whose events are still to be + /// retried. Kept in memory: after a restart the retry is a new request. + CaptureV1Identity? pendingIdentity; + + /// Flushes in a row whose batch failed with a transient error or had + /// events the server asked to retry. Each one pauses the queue for longer, + /// see [captureRetryDelay], so a failure that lasts, like a missing + /// capture route, doesn't resend the batch with every capture. A delivered + /// or dropped batch resets it. + int failedFlushes = 0; + + /// Whether this client already warned that [path] returned a 404. + bool warnedNotFound = false; + + Timer? flushTimer; + Timer? retryAfterTimer; + Future? flushFuture; + + void clearFlushTimer() { + flushTimer?.cancel(); + flushTimer = null; + } +} + class _FetchAttempt { _FetchAttempt(this._idleTimeout, this._bodyTimeout); diff --git a/posthog_flutter/lib/src/feature_flags_loaded.dart b/posthog_flutter/lib/src/feature_flags_loaded.dart new file mode 100644 index 00000000..0a8c196b --- /dev/null +++ b/posthog_flutter/lib/src/feature_flags_loaded.dart @@ -0,0 +1,53 @@ +/// The feature flags passed to [PostHogConfig.onFeatureFlags] and returned by +/// [Posthog.reloadFeatureFlags]. +/// +/// Only enabled flags are included. When the latest load failed, +/// [errorsLoading] is `true` and the flags are the last known values, which +/// can be empty. +/// +/// **Example:** +/// ```dart +/// final config = PostHogConfig('') +/// ..onFeatureFlags = (loaded) { +/// if (loaded.errorsLoading) { +/// // The values are the last known (cached) flags. +/// } +/// if (loaded.variants['new-checkout'] == 'test') { +/// // Show the test variant. +/// } +/// }; +/// ``` +class PostHogFeatureFlagsLoaded { + /// The keys of the enabled feature flags. + List get flags => List.unmodifiable(variants.keys); + + /// The values of the enabled feature flags, keyed by flag key. + /// + /// A value is `true` for an enabled boolean flag, or the variant [String] + /// for a multivariate flag. Disabled flags are not included. + final Map variants; + + /// Whether the latest attempt to load feature flags failed. + /// + /// When it did, [flags] and [variants] hold the last known values. + /// + /// **Flutter web:** when [PostHogConfig.onFeatureFlags] is first set, it is + /// called right away with the current flags and `false`, even if + /// posthog-js's last load before that failed. + final bool errorsLoading; + + /// Creates the loaded feature flags from [variants], keeping only enabled + /// flags: `true`, or a non-empty variant string. + PostHogFeatureFlagsLoaded({ + required Map variants, + required this.errorsLoading, + }) : variants = Map.unmodifiable({ + for (final MapEntry(:key, :value) in variants.entries) + if (value == true || (value is String && value.isNotEmpty)) + key: value!, + }); + + @override + String toString() => + 'PostHogFeatureFlagsLoaded(variants: $variants, errorsLoading: $errorsLoading)'; +} diff --git a/posthog_flutter/lib/src/posthog.dart b/posthog_flutter/lib/src/posthog.dart index 2c134fe6..51520dff 100644 --- a/posthog_flutter/lib/src/posthog.dart +++ b/posthog_flutter/lib/src/posthog.dart @@ -5,6 +5,7 @@ import 'package:meta/meta.dart'; import 'package:posthog_flutter/src/error_tracking/posthog_error_tracking_autocapture_integration.dart'; import 'package:posthog_flutter/src/error_tracking/posthog_exception.dart'; import 'feature_flag_result.dart'; +import 'feature_flags_loaded.dart'; import 'logs/posthog_log_record.dart'; import 'logs/posthog_log_severity.dart'; import 'logs/posthog_logger.dart'; @@ -58,7 +59,7 @@ class Posthog { /// ```dart /// final config = PostHogConfig('YOUR_PROJECT_TOKEN'); /// config.host = 'YOUR_POSTHOG_HOST'; - /// config.onFeatureFlags = () { + /// config.onFeatureFlags = (loaded) { /// // Feature flags are now loaded, you can read flag values here /// }; /// await Posthog().setup(config); @@ -139,6 +140,9 @@ class Posthog { /// The optional [userPropertiesSetOnce] are person properties set with /// `$set_once`. /// + /// The optional [options] tell PostHog how to process the `$identify` or + /// `$set` event this call sends, as described on [capture]. + /// /// Returns a [Future] that completes when the identify call has been queued. /// /// Note that identifying a user reloads feature flags, which issues a @@ -156,11 +160,13 @@ class Posthog { required String userId, Map? userProperties, Map? userPropertiesSetOnce, + Map? options, }) => _posthog.identify( userId: userId, userProperties: userProperties, userPropertiesSetOnce: userPropertiesSetOnce, + options: options, ); /// Sets person properties for the current user without requiring identify. @@ -174,6 +180,9 @@ class Posthog { /// The optional [userPropertiesToSetOnce] values are set with `$set_once` and /// do not overwrite existing values. /// + /// The optional [options] tell PostHog how to process the `$set` event this + /// call sends, as described on [capture]. + /// /// Returns a [Future] that completes when the update has been queued. /// If both property maps are null or empty, no event is queued. /// @@ -187,10 +196,12 @@ class Posthog { Future setPersonProperties({ Map? userPropertiesToSet, Map? userPropertiesToSetOnce, + Map? options, }) => _posthog.setPersonProperties( userPropertiesToSet: userPropertiesToSet, userPropertiesToSetOnce: userPropertiesToSetOnce, + options: options, ); /// Captures a custom event. @@ -209,6 +220,29 @@ class Posthog { /// The optional [userPropertiesSetOnce] are person properties set with /// `$set_once`. /// + /// The optional [options] tell PostHog how to process this event and are + /// sent apart from its properties. Known keys: + /// - `process_person_profile` (`bool`): whether PostHog creates or updates a + /// person profile for this event. + /// - `cookieless_mode` (`bool`): whether PostHog processes this event in + /// cookieless mode. + /// - `disable_skew_correction` (`bool`): whether PostHog keeps the event + /// timestamp as sent instead of correcting it for device clock skew. + /// - `product_tour_id` (`String`): the product tour the event belongs to. + /// + /// These replace the `$process_person_profile`, `$cookieless_mode`, + /// `$ignore_sent_at` and `$product_tour_id` properties, and an option wins + /// over its property. A null value means unset. [PostHogConfig.beforeSend] + /// can change them through [PostHogEvent.options]. + /// + /// On iOS, macOS, Android, Windows and Linux, other keys are sent + /// unchanged. On web, the known keys are sent as their legacy properties + /// and other keys are dropped. On web, posthog-js sets + /// `$process_person_profile` itself, so `process_person_profile` has no + /// effect there, and the options of [identify], [setPersonProperties], + /// [alias] and [group] are dropped because posthog-js sends those events + /// without event properties. + /// /// Returns a [Future] that completes when the event has been queued. /// /// **Example** @@ -226,7 +260,67 @@ class Posthog { Map? properties, Map? userProperties, Map? userPropertiesSetOnce, + Map? options, + }) { + return _posthog.capture( + eventName: eventName, + properties: _withCurrentScreen(properties), + userProperties: userProperties, + userPropertiesSetOnce: userPropertiesSetOnce, + options: options, + ); + } + + /// Captures an AI observability event, such as `$ai_generation`, + /// `$ai_span`, `$ai_trace` or `$ai_embedding`, and sends it to PostHog's AI + /// endpoint, which accepts much larger events than [capture]. + /// + /// Takes the same arguments as [capture] and goes through the same + /// [PostHogConfig.beforeSend] callbacks. The event is queued separately from + /// other events and sent unchanged: the SDK doesn't redact or truncate + /// prompts, outputs or media. PostHog drops an event sent here whose name + /// doesn't start with `$ai_`. [capture] never sends events here, even ones + /// named `$ai_*`. + /// + /// Returns the event's UUID once the SDK has admitted it to the AI queue. + /// `null` means the event was not admitted and will not be sent: + /// - a [PostHogConfig.beforeSend] callback dropped it, + /// - it is over [PostHogConfig.captureAiMaxEventBytes], + /// - the SDK is disabled, not set up or opted out, or + /// - the platform is web (see below). + /// + /// **Platforms:** supported on iOS, macOS, Android, Windows and Linux. On + /// web, `captureAi` is a no-op: it sends nothing, logs a debug message and + /// returns `null`. + /// + /// **Example** + /// ```dart + /// await Posthog().captureAi( + /// eventName: r'$ai_generation', + /// properties: { + /// r'$ai_trace_id': traceId, + /// r'$ai_model': 'gpt-4o', + /// r'$ai_provider': 'openai', + /// }, + /// ); + /// ``` + Future captureAi({ + required String eventName, + Map? properties, + Map? userProperties, + Map? userPropertiesSetOnce, + Map? options, }) { + return _posthog.captureAi( + eventName: eventName, + properties: _withCurrentScreen(properties), + userProperties: userProperties, + userPropertiesSetOnce: userPropertiesSetOnce, + options: options, + ); + } + + Map? _withCurrentScreen(Map? properties) { final propertiesCopy = properties == null ? null : {...properties}; final currentScreen = _currentScreen; @@ -235,12 +329,7 @@ class Posthog { currentScreen != null) { propertiesCopy['\$screen_name'] = currentScreen; } - return _posthog.capture( - eventName: eventName, - properties: propertiesCopy, - userProperties: userProperties, - userPropertiesSetOnce: userPropertiesSetOnce, - ); + return propertiesCopy; } /// Captures a screen view event. @@ -249,13 +338,20 @@ class Posthog { /// /// The optional [properties] are additional screen event properties. /// + /// The optional [options] tell PostHog how to process the `$screen` event, as described on [capture]. + /// /// Returns a [Future] that completes when the screen event has been queued. Future screen({ required String screenName, Map? properties, + Map? options, }) { _currentScreen = screenName; - return _posthog.screen(screenName: screenName, properties: properties); + return _posthog.screen( + screenName: screenName, + properties: properties, + options: options, + ); } /// Captures a structured log record. @@ -371,8 +467,12 @@ class Posthog { /// /// The [alias] is the additional distinct ID to associate with the user. /// + /// The optional [options] tell PostHog how to process the `$create_alias` + /// event, as described on [capture]. + /// /// Returns a [Future] that completes when the alias call has been queued. - Future alias({required String alias}) => _posthog.alias(alias: alias); + Future alias({required String alias, Map? options}) => + _posthog.alias(alias: alias, options: options); /// Returns the registered `distinctId` property. /// @@ -489,8 +589,30 @@ class Posthog { /// Reloads feature flags for the current user. /// - /// Returns a [Future] that completes when the reload request has been queued. - Future reloadFeatureFlags() => _posthog.reloadFeatureFlags(); + /// Returns a [Future] that completes when the reload finishes, with the + /// enabled flags and whether loading failed. When it failed, + /// [PostHogFeatureFlagsLoaded.errorsLoading] is `true` and the flags are the + /// last known values. + /// + /// **Flutter web:** with posthog-js 1.438.2 or later, completes once this + /// reload's request settles; if posthog-js skips it (flags disabled, + /// reloading paused, or after repeated network failures), it completes right + /// away with the current flags and `errorsLoading: true`. Older posthog-js + /// completes with the next flags it reports, and when it skips the request, + /// with `errorsLoading: true` once every request attempt posthog-js may + /// make could have timed out: `feature_flag_request_max_retries + 2` times + /// its `feature_flag_request_timeout_ms`, plus 500 ms per retry (9.5 s with + /// the defaults; right away when flags are disabled). + /// + /// **Example:** + /// ```dart + /// final loaded = await Posthog().reloadFeatureFlags(); + /// if (!loaded.errorsLoading && loaded.flags.contains('new-checkout')) { + /// // The flag is enabled. + /// } + /// ``` + Future reloadFeatureFlags() => + _posthog.reloadFeatureFlags(); /// Sets person properties that are used only for feature flag evaluation. /// @@ -506,9 +628,9 @@ class Posthog { /// /// Set [reloadFeatureFlags] to `false` to skip reloading flags after updating /// the properties (defaults to `true`). When `true`, the returned [Future] - /// awaits the reload before completing; on iOS and Android this means flags - /// have finished loading, so the next [getFeatureFlag] / [getFeatureFlagResult] - /// reflects the updated properties. On web the reload is best-effort. + /// awaits the reload before completing, so the next [getFeatureFlag] / + /// [getFeatureFlagResult] reflects the updated properties. On web, see + /// [Posthog.reloadFeatureFlags] for which posthog-js versions wait for it. /// /// **Example:** /// ```dart @@ -536,8 +658,8 @@ class Posthog { /// /// Set [reloadFeatureFlags] to `false` to skip reloading flags after clearing /// the properties (defaults to `true`). When `true`, the returned [Future] - /// awaits the reload before completing (on iOS/Android, after flags finish - /// loading; on web, best-effort). + /// awaits the reload before completing. On web, see + /// [Posthog.reloadFeatureFlags] for which posthog-js versions wait for it. Future resetPersonPropertiesForFlags({ bool reloadFeatureFlags = true, }) async { @@ -560,8 +682,8 @@ class Posthog { /// /// Set [reloadFeatureFlags] to `false` to skip reloading flags after updating /// the properties (defaults to `true`). When `true`, the returned [Future] - /// awaits the reload before completing (on iOS/Android, after flags finish - /// loading; on web, best-effort). + /// awaits the reload before completing. On web, see + /// [Posthog.reloadFeatureFlags] for which posthog-js versions wait for it. /// /// **Example:** /// ```dart @@ -592,8 +714,8 @@ class Posthog { /// /// Set [reloadFeatureFlags] to `false` to skip reloading flags after clearing /// the properties (defaults to `true`). When `true`, the returned [Future] - /// awaits the reload before completing (on iOS/Android, after flags finish - /// loading; on web, best-effort). + /// awaits the reload before completing. On web, see + /// [Posthog.reloadFeatureFlags] for which posthog-js versions wait for it. Future resetGroupPropertiesForFlags({ String? groupType, bool reloadFeatureFlags = true, @@ -614,6 +736,9 @@ class Posthog { /// /// The optional [groupProperties] are group properties set with `$group_set`. /// + /// The optional [options] tell PostHog how to process the `$groupidentify` + /// event, as described on [capture]. + /// /// Returns a [Future] that completes when the group call has been queued. /// /// Note that setting a group reloads feature flags, which issues a `/flags` @@ -632,11 +757,13 @@ class Posthog { required String groupType, required String groupKey, Map? groupProperties, + Map? options, }) => _posthog.group( groupType: groupType, groupKey: groupKey, groupProperties: groupProperties, + options: options, ); /// Registers this device's push token so PostHog Workflows can target it. @@ -886,16 +1013,20 @@ class Posthog { /// /// The optional [properties] are added to the `$exception` event. /// + /// The optional [options] tell PostHog how to process the `$exception` event, as described on [capture]. + /// /// Returns a [Future] that completes when the exception event has been queued. Future captureException({ required Object error, StackTrace? stackTrace, Map? properties, + Map? options, }) => _posthog.captureException( error: error, stackTrace: stackTrace, properties: properties, + options: options, ); /// Captures a `runZonedGuarded` error with optional custom properties. diff --git a/posthog_flutter/lib/src/posthog_config.dart b/posthog_flutter/lib/src/posthog_config.dart index fcbd806f..368067b6 100644 --- a/posthog_flutter/lib/src/posthog_config.dart +++ b/posthog_flutter/lib/src/posthog_config.dart @@ -196,6 +196,55 @@ class PostHogConfig { /// Defaults to [PostHogCompression.gzip]. var compression = PostHogCompression.gzip; + /// How [Posthog.captureAi] request bodies are compressed, separately from + /// [compression]. + /// + /// Not applied on web, where [Posthog.captureAi] sends nothing. + /// + /// Defaults to `null`, which keeps the SDK default (gzip). + PostHogCompression? captureAiCompression; + + /// Maximum number of [Posthog.captureAi] events kept in their on-disk queue + /// before the oldest are dropped. + /// + /// AI events can be megabytes, so the default (100) is lower than + /// [maxQueueSize]. The queue also keeps at most 50 MiB of AI events, + /// whatever this is set to. A value of `0` or less uses the default. + /// + /// Not applied on web, where [Posthog.captureAi] sends nothing. + /// + /// Defaults to `null`, which keeps the SDK default. + int? captureAiMaxQueueSize; + + /// Timeout of a [Posthog.captureAi] request: how long it may go without + /// network activity. On iOS, macOS and Android it is sent to the native SDK + /// in whole seconds (a positive value under one second is sent as one + /// second). + /// + /// AI requests can carry several MB, so the default (60 seconds) is + /// longer than for other requests. [Duration.zero] or less uses the + /// default. + /// + /// Not applied on web, where [Posthog.captureAi] sends nothing. + /// + /// Defaults to `null`, which keeps the SDK default. + Duration? captureAiTimeout; + + /// Maximum size, in bytes, of a [Posthog.captureAi] event. The SDK drops a + /// larger event and [Posthog.captureAi] returns `null`. + /// + /// Use it to lower the limit. PostHog drops AI events whose properties are + /// over 8 MiB, so a larger value, or a value of `0` or less, uses the + /// default. By default the SDK drops a serialized event over 8 MiB plus + /// 64 KiB for the rest of the event, measured before compression. A set + /// value limits the properties on Android, plus 64 KiB for the rest of the + /// event, and the whole serialized event on the other platforms. + /// + /// Not applied on web, where [Posthog.captureAi] sends nothing. + /// + /// Defaults to `null`, which keeps the SDK default. + int? captureAiMaxEventBytes; + /// Whether the SDK is enabled on Windows and Linux. /// /// Windows and Linux support is experimental. Defaults to `true`. @@ -264,8 +313,24 @@ class PostHogConfig { /// Callback to be invoked when feature flags are loaded. /// - /// Use [Posthog.getFeatureFlag] or [Posthog.isFeatureEnabled] within this - /// callback to access the loaded flag values. + /// It receives the enabled flags and whether loading failed. It runs after + /// the flags load at startup, after [Posthog.reloadFeatureFlags], and after + /// calls that reload flags such as `identify()` or `group()`. When a load + /// fails, [PostHogFeatureFlagsLoaded.errorsLoading] is `true` and the flags + /// are the last known values. Defaults to `null`. + /// + /// **Android:** not called after [Posthog.reloadFeatureFlags]. Use the + /// flags that call returns instead. + /// + /// **Example:** + /// ```dart + /// final config = PostHogConfig('') + /// ..onFeatureFlags = (loaded) { + /// if (loaded.variants['new-checkout'] == 'test') { + /// // Show the test variant. + /// } + /// }; + /// ``` OnFeatureFlagsCallback? onFeatureFlags; /// Whether to automatically register this device's push token with PostHog. @@ -390,7 +455,9 @@ class PostHogConfig { /// - Survey events (`survey shown`, etc.) when `config.surveys` is enabled /// - Only user-provided properties are available; system properties (like /// `$device_type`, `$session_id`) are added by the native SDK at a later - /// stage. + /// stage. On Windows and Linux, the callbacks see the system properties + /// and the options the SDK adds, and can change them for that event, + /// except `$lib` and `$lib_version`, which PostHog sets from the SDK. /// /// **Note:** /// - Callbacks can be synchronous or asynchronous (via diff --git a/posthog_flutter/lib/src/posthog_desktop_client.dart b/posthog_flutter/lib/src/posthog_desktop_client.dart index a29b27f1..299e50b4 100644 --- a/posthog_flutter/lib/src/posthog_desktop_client.dart +++ b/posthog_flutter/lib/src/posthog_desktop_client.dart @@ -33,8 +33,7 @@ class DesktopPostHog extends PostHogCore { }; } - // Session replay is not available on desktop. Common properties are merged - // over the event's own, so an event cannot change it. + // Session replay is not available on desktop. @override Map getCommonEventProperties() => { ...super.getCommonEventProperties(), diff --git a/posthog_flutter/lib/src/posthog_event.dart b/posthog_flutter/lib/src/posthog_event.dart index 1484986b..7063dd89 100644 --- a/posthog_flutter/lib/src/posthog_event.dart +++ b/posthog_flutter/lib/src/posthog_event.dart @@ -8,8 +8,11 @@ class PostHogEvent { /// User-provided properties for this event. /// - /// Note: System properties (like $device_type, $session_id, etc.) are added - /// by the native SDK at a later stage and are not available in this map. + /// On iOS, macOS, Android and web, system properties (like $device_type, + /// $session_id, etc.) are added by the native SDK at a later stage and are + /// not available in this map. On Windows and Linux, the map already holds + /// them, then the registered properties, then the event's own, and the + /// event is sent as the callbacks leave it. Map? properties; /// User properties to set on the user profile ($set). @@ -22,6 +25,13 @@ class PostHogEvent { /// These properties will only be set if they don't already exist on the user profile. Map? userPropertiesSetOnce; + /// Settings that tell PostHog how to process this event, sent apart from + /// its properties. See `Posthog.capture` for the known keys. + /// + /// A callback can read, add, change or remove them. A null value means + /// unset. + Map? options; + /// Creates an event passed to a before-send callback. /// /// The [event] is the event name to capture. @@ -33,15 +43,18 @@ class PostHogEvent { /// /// The optional [userPropertiesSetOnce] are person properties to set with /// `$set_once`. + /// + /// The optional [options] are the event's per-event options. PostHogEvent({ required this.event, this.properties, this.userProperties, this.userPropertiesSetOnce, + this.options, }); @override String toString() { - return 'PostHogEvent(event: $event, properties: $properties, userProperties: $userProperties, userPropertiesSetOnce: $userPropertiesSetOnce)'; + return 'PostHogEvent(event: $event, properties: $properties, userProperties: $userProperties, userPropertiesSetOnce: $userPropertiesSetOnce, options: $options)'; } } diff --git a/posthog_flutter/lib/src/posthog_flutter_desktop.dart b/posthog_flutter/lib/src/posthog_flutter_desktop.dart index 7b7df894..26a7e094 100644 --- a/posthog_flutter/lib/src/posthog_flutter_desktop.dart +++ b/posthog_flutter/lib/src/posthog_flutter_desktop.dart @@ -6,6 +6,7 @@ import 'core/file_storage.dart'; import 'core/utils/utils.dart'; import 'error_tracking/dart_exception_processor.dart'; import 'feature_flag_result.dart'; +import 'feature_flags_loaded.dart'; import 'logs/posthog_log_severity.dart'; import 'posthog_config.dart'; import 'posthog_constants.dart'; @@ -20,6 +21,7 @@ import 'posthog_flutter_platform_interface.dart'; import 'util/logging.dart'; import 'utils/before_send.dart'; import 'utils/capture_utils.dart'; +import 'utils/event_options.dart'; import 'utils/feature_event.dart'; import 'utils/property_normalizer.dart'; @@ -175,8 +177,8 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { projectToken: config.projectToken, host: removeTrailingSlash(config.host), ); - _featureFlagsUnsubscribe = - client.onFeatureFlags(() => _config?.onFeatureFlags?.call()); + _featureFlagsUnsubscribe = client.onFeatureFlags( + () => _config?.onFeatureFlags?.call(client.featureFlagsLoaded())); final stepsConfig = config.errorTrackingConfig.exceptionSteps; _exceptionSteps = stepsConfig.enabled @@ -217,12 +219,14 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { required String userId, Map? userProperties, Map? userPropertiesSetOnce, + Map? options, }) => _guard('identify', (client) { client.identify( userId, userProperties: _normalize(userProperties), userPropertiesSetOnce: _normalize(userPropertiesSetOnce), + options: cleanEventOptions(options), ); }); @@ -230,11 +234,13 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { Future setPersonProperties({ Map? userPropertiesToSet, Map? userPropertiesToSetOnce, + Map? options, }) => _guard('setPersonProperties', (client) { client.setPersonProperties( userPropertiesToSet: _normalize(userPropertiesToSet), userPropertiesToSetOnce: _normalize(userPropertiesToSetOnce), + options: cleanEventOptions(options), ); }); @@ -244,6 +250,7 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { Map? properties, Map? userProperties, Map? userPropertiesSetOnce, + Map? options, }) => _guard('capture', (client) async { if (client.optedOut) return; @@ -253,12 +260,16 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { final distinctId = client.getDistinctId(); final exceptionSteps = _exceptionSteps; - final hooked = _runBeforeSend( + final prepared = _prepare( + client, eventName, properties, userProperties: userProperties, userPropertiesSetOnce: userPropertiesSetOnce, + options: options, ); + if (prepared == null) return; + final hooked = _runBeforeSend(prepared.event); final processed = hooked is Future ? await hooked : hooked; if (processed == null) { @@ -268,13 +279,58 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { final current = _clientForContinuation('capture', scope, distinctId); if (current == null) return; - _captureProcessed(current, processed, exceptionSteps); + _captureProcessed(current, processed, exceptionSteps, prepared); + }); + + @override + Future captureAi({ + required String eventName, + Map? properties, + Map? userProperties, + Map? userPropertiesSetOnce, + Map? options, + }) => + _guardWith('captureAi', null, (client) async { + if (!eventName.startsWith(r'$ai_')) { + printIfDebug('[PostHog] captureAi event $eventName does not start ' + r'with $ai_, so PostHog will drop it. Use capture for non-AI ' + 'events.'); + } + if (client.optedOut) return null; + if (!_hasName(eventName)) return null; + final scope = _clientScope; + if (scope == null) return null; + final distinctId = client.getDistinctId(); + final exceptionSteps = _exceptionSteps; + + final prepared = _prepare( + client, + eventName, + properties, + userProperties: userProperties, + userPropertiesSetOnce: userPropertiesSetOnce, + options: options, + ); + if (prepared == null) return null; + final hooked = _runBeforeSend(prepared.event); + final processed = + hooked is Future ? await hooked : hooked; + if (processed == null) { + printIfDebug('[PostHog] Event dropped by beforeSend: $eventName'); + return null; + } + + final current = _clientForContinuation('captureAi', scope, distinctId); + if (current == null) return null; + return _captureProcessed(current, processed, exceptionSteps, prepared, + ai: true); }); @override Future screen({ required String screenName, Map? properties, + Map? options, }) => _guard('screen', (client) async { // Opted out, nothing happens: no callback runs, and the screen does @@ -285,13 +341,17 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { final distinctId = client.getDistinctId(); final exceptionSteps = _exceptionSteps; - final hooked = _runBeforeSend( + final prepared = _prepare( + client, PostHogEventName.screen, { ...?properties, PostHogPropertyName.screenName: screenName, }, + options: options, ); + if (prepared == null) return; + final hooked = _runBeforeSend(prepared.event); final processed = hooked is Future ? await hooked : hooked; if (processed == null) { @@ -305,7 +365,7 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { // A renamed event is no longer a screen view. if (processed.event != PostHogEventName.screen) { - _captureProcessed(current, processed, exceptionSteps); + _captureProcessed(current, processed, exceptionSteps, prepared); return; } @@ -326,7 +386,7 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { ...?processed.properties, PostHogPropertyName.screenName: finalScreenName, }; - _captureProcessed(current, processed, exceptionSteps); + _captureProcessed(current, processed, exceptionSteps, prepared); }); /// Structured logs are not supported on the desktop implementation. @@ -365,8 +425,14 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { } @override - Future alias({required String alias}) => - _guard('alias', (client) => client.alias(alias)); + Future alias({required String alias, Map? options}) => + _guard( + 'alias', + (client) => client.alias( + alias, + options: cleanEventOptions(options), + ), + ); @override Future captureFeatureView({ @@ -451,8 +517,13 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { false); @override - Future reloadFeatureFlags() => _guard( - 'reloadFeatureFlags', (client) => client.reloadFeatureFlagsAsync()); + Future reloadFeatureFlags() => _guardWith( + 'reloadFeatureFlags', + PostHogFeatureFlagsLoaded(variants: const {}, errorsLoading: true), + (client) async { + await client.reloadFeatureFlagsAsync(); + return client.featureFlagsLoaded(); + }); @override Future setPersonPropertiesForFlags( @@ -489,12 +560,14 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { required String groupType, required String groupKey, Map? groupProperties, + Map? options, }) => _guard('group', (client) { client.group( groupType, groupKey, groupProperties: _normalize(groupProperties), + options: cleanEventOptions(options), ); }); @@ -534,6 +607,7 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { required Object error, StackTrace? stackTrace, Map? properties, + Map? options, }) => _guard('captureException', (client) async { if (client.optedOut) return; @@ -551,10 +625,14 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { inAppByDefault: _config?.errorTrackingConfig.inAppByDefault ?? true, ); - final hooked = _runBeforeSend( + final prepared = _prepare( + client, PostHogEventName.exception, exceptionProps.cast(), + options: options, ); + if (prepared == null) return; + final hooked = _runBeforeSend(prepared.event); final processed = hooked is Future ? await hooked : hooked; if (processed == null) { @@ -567,7 +645,7 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { final current = _clientForContinuation('captureException', scope, distinctId); if (current == null) return; - _captureProcessed(current, processed, exceptionSteps); + _captureProcessed(current, processed, exceptionSteps, prepared); }); @override @@ -644,10 +722,71 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { @override Future isSessionReplayActive() async => false; + /// Builds [eventName] on [client] as it would be sent, with the + /// properties and options the SDK adds, for the beforeSend callbacks. + /// The SDK's properties come first, then the registered ones, then the + /// event's own. Returns null when the client is closed or opted out. + /// + /// [userProperties] and [userPropertiesSetOnce] are handed to the + /// callbacks as [PostHogEvent.userProperties] and + /// [PostHogEvent.userPropertiesSetOnce]. Legacy `$set` and `$set_once` + /// maps in [properties] stay in [PostHogEvent.properties], so a callback + /// that removes them there still keeps them off the event. + /// The event's time is taken now, before the callbacks run. + _PreparedEvent? _prepare( + DesktopPostHog client, + String eventName, + Map? properties, { + Map? userProperties, + Map? userPropertiesSetOnce, + Map? options, + }) { + final prepared = client.prepareEvent( + eventName, + properties: + _mergeUserProps(properties, userProperties, userPropertiesSetOnce), + options: cleanEventOptions(options), + ); + if (prepared == null) return null; + final eventProperties = _nonNull(prepared.properties)!; + for (final (key, explicit) in [ + (r'$set', userProperties), + (r'$set_once', userPropertiesSetOnce), + ]) { + final legacy = _nonNull(properties?[key]); + if (legacy != null) { + eventProperties[key] = legacy; + } else if (explicit != null) { + eventProperties.remove(key); + } + } + final preparedOptions = prepared.options; + return ( + event: PostHogEvent( + event: eventName, + properties: eventProperties, + userProperties: _nonNull(userProperties), + userPropertiesSetOnce: _nonNull(userPropertiesSetOnce), + options: preparedOptions == null ? null : {...preparedOptions}, + ), + timestamp: prepared.timestamp, + implicitPersonProcessing: + preparedOptions?['process_person_profile'] == null, + ); + } + + /// A deep copy of [map] without its null values, or null when it is not a + /// map. Registered properties share their nested maps and lists with + /// storage, so a callback editing them in place would change later events. + static Map? _nonNull(Object? map) => map is Map + ? Map.from(PropertyNormalizer.normalize({ + for (final MapEntry(:key, :value) in map.entries) '$key': value, + })) + : null; + /// Applies the beforeSend callbacks to an event in order. Running them here /// rather than in the client keeps SDK-internal events ($identify, - /// $feature_flag_called, ...) and the properties the SDK adds out of the - /// callbacks' sight. + /// $feature_flag_called, ...) out of the callbacks' sight. /// /// Returns the possibly modified event, or null if any callback drops it /// or throws. @@ -656,18 +795,7 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { /// must not await it: an identify(), reset() or opt-out made right after /// an unawaited capture would otherwise run first, and the event would be /// dropped as belonging to another user. - FutureOr _runBeforeSend( - String eventName, - Map? properties, { - Map? userProperties, - Map? userPropertiesSetOnce, - }) { - final event = PostHogEvent( - event: eventName, - properties: properties, - userProperties: userProperties, - userPropertiesSetOnce: userPropertiesSetOnce, - ); + FutureOr _runBeforeSend(PostHogEvent event) { final callbacks = _config?.beforeSend ?? const []; return callbacks.isEmpty ? event : _applyCallbacks(callbacks, event); } @@ -685,24 +813,45 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { return processed; } - void _captureProcessed( + /// Queues [event] as the beforeSend callbacks left it, on the AI queue + /// with [ai], and returns its uuid, or null when it is not queued. The + /// client adds nothing to it; an `$exception` event gets the exception + /// steps recorded up to now. + String? _captureProcessed( DesktopPostHog client, PostHogEvent event, ExceptionStepsBuffer? exceptionSteps, - ) { - if (!_hasName(event.event)) return; - client.capture( - event.event, - properties: _withExceptionSteps( + _PreparedEvent prepared, { + bool ai = false, + }) { + if (!_hasName(event.event)) return null; + final properties = _withExceptionSteps( + event.event, + exceptionSteps, + _mergeUserProps( + event.properties, + event.userProperties, + event.userPropertiesSetOnce, + ), + ) ?? + const {}; + // Options are sent as they are, unknown keys included. An option wins + // over its legacy property on the event. + Map? options = cleanEventOptions(event.options); + // Person properties the callbacks removed no longer ask for person + // processing, unless a callback set the option itself. + if (prepared.implicitPersonProcessing && + options?['process_person_profile'] == null) { + options = client.personProcessingOptions(options, properties); + } + return client.capturePrepared( event.event, - exceptionSteps, - _mergeUserProps( - event.properties, - event.userProperties, - event.userPropertiesSetOnce, + ( + properties: properties, + options: options, + timestamp: prepared.timestamp, ), - ), - ); + ai: ai); } /// Whether [event] has a name; an event without one is dropped. @@ -756,3 +905,11 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { return Map.from(PropertyNormalizer.normalize(properties)); } } + +/// An event built for the beforeSend callbacks, with the time it happened +/// and whether its person processing was left to its properties. +typedef _PreparedEvent = ({ + PostHogEvent event, + String timestamp, + bool implicitPersonProcessing, +}); diff --git a/posthog_flutter/lib/src/posthog_flutter_io.dart b/posthog_flutter/lib/src/posthog_flutter_io.dart index f5a1b2ad..1e9a4bdf 100644 --- a/posthog_flutter/lib/src/posthog_flutter_io.dart +++ b/posthog_flutter/lib/src/posthog_flutter_io.dart @@ -13,10 +13,12 @@ import 'error_tracking/dart_exception_processor.dart'; import 'utils/before_send.dart'; import 'utils/capture_utils.dart'; import 'utils/channel_serialization.dart'; +import 'utils/event_options.dart'; import 'utils/flutter_version.dart'; import 'utils/property_normalizer.dart'; import 'feature_flag_result.dart'; +import 'feature_flags_loaded.dart'; import 'logs/posthog_log_severity.dart'; import 'posthog_config.dart'; import 'posthog_constants.dart'; @@ -50,6 +52,7 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { Map? properties, { Map? userProperties, Map? userPropertiesSetOnce, + Map? options, }) { return applyBeforeSend( _beforeSendCallbacks, @@ -58,6 +61,7 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { properties: properties, userProperties: userProperties, userPropertiesSetOnce: userPropertiesSetOnce, + options: options == null ? null : {...options}, ), ); } @@ -73,7 +77,8 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { await cleanupSurveys(); return null; case 'onFeatureFlagsCallback': - _onFeatureFlagsCallback?.call(); + _onFeatureFlagsCallback + ?.call(featureFlagsLoadedFromMap(call.arguments)); break; case 'pushIdentityProvider': // Returning a value here is the reply the native SDK awaits. @@ -235,12 +240,14 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { required String userId, Map? userProperties, Map? userPropertiesSetOnce, + Map? options, }) async { if (!isSupportedPlatform()) { return; } try { + final cleanedOptions = cleanEventOptions(options); final normalizedUserProperties = userProperties != null ? PropertyNormalizer.normalize(userProperties) : null; @@ -254,6 +261,7 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { 'userProperties': normalizedUserProperties, if (normalizedUserPropertiesSetOnce != null) 'userPropertiesSetOnce': normalizedUserPropertiesSetOnce, + if (cleanedOptions != null) 'options': cleanedOptions, }); } on PlatformException catch (exception) { printIfDebug('Exeption on identify: $exception'); @@ -264,12 +272,14 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { Future setPersonProperties({ Map? userPropertiesToSet, Map? userPropertiesToSetOnce, + Map? options, }) async { if (!isSupportedPlatform()) { return; } try { + final cleanedOptions = cleanEventOptions(options); final normalizedUserPropertiesToSet = userPropertiesToSet != null ? PropertyNormalizer.normalize(userPropertiesToSet) : null; @@ -282,6 +292,7 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { 'userPropertiesToSet': normalizedUserPropertiesToSet, if (normalizedUserPropertiesToSetOnce != null) 'userPropertiesToSetOnce': normalizedUserPropertiesToSetOnce, + if (cleanedOptions != null) 'options': cleanedOptions, }); } on PlatformException catch (exception) { printIfDebug('Exception on setPersonProperties: $exception'); @@ -294,9 +305,50 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { Map? properties, Map? userProperties, Map? userPropertiesSetOnce, + Map? options, + }) async { + await _captureEvent( + 'capture', + eventName: eventName, + properties: properties, + userProperties: userProperties, + userPropertiesSetOnce: userPropertiesSetOnce, + options: options, + ); + } + + @override + Future captureAi({ + required String eventName, + Map? properties, + Map? userProperties, + Map? userPropertiesSetOnce, + Map? options, + }) async { + final uuid = await _captureEvent( + 'captureAi', + eventName: eventName, + properties: properties, + userProperties: userProperties, + userPropertiesSetOnce: userPropertiesSetOnce, + options: options, + ); + return uuid is String ? uuid : null; + } + + /// Runs beforeSend and sends the event through [method], `capture` or + /// `captureAi`. Returns what the native SDK returned, or null when the + /// event was dropped. + Future _captureEvent( + String method, { + required String eventName, + Map? properties, + Map? userProperties, + Map? userPropertiesSetOnce, + Map? options, }) async { if (!isSupportedPlatform()) { - return; + return null; } // Apply beforeSend callback @@ -305,11 +357,12 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { properties, userProperties: userProperties, userPropertiesSetOnce: userPropertiesSetOnce, + options: options, ); if (processedEvent == null) { printIfDebug('[PostHog] Event dropped by beforeSend: $eventName'); - return; + return null; } try { @@ -334,17 +387,20 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { extractedUserPropertiesSetOnce != null ? PropertyNormalizer.normalize(extractedUserPropertiesSetOnce) : null; + final cleanedOptions = cleanEventOptions(processedEvent.options); - await _methodChannel.invokeMethod('capture', { + return await _methodChannel.invokeMethod(method, { 'eventName': processedEvent.event, if (normalizedProperties != null) 'properties': normalizedProperties, if (normalizedUserProperties != null) 'userProperties': normalizedUserProperties, if (normalizedUserPropertiesSetOnce != null) 'userPropertiesSetOnce': normalizedUserPropertiesSetOnce, + if (cleanedOptions != null) 'options': cleanedOptions, }); } on PlatformException catch (exception) { - printIfDebug('Exeption on capture: $exception'); + printIfDebug('Exeption on $method: $exception'); + return null; } } @@ -352,6 +408,7 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { Future screen({ required String screenName, Map? properties, + Map? options, }) async { if (!isSupportedPlatform()) { return; @@ -368,6 +425,7 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { final processedEvent = await _runBeforeSend( PostHogEventName.screen, propsWithScreenName, + options: options, ); if (processedEvent == null) { printIfDebug('[PostHog] Screen event dropped by beforeSend: $screenName'); @@ -379,6 +437,7 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { await capture( eventName: processedEvent.event, properties: processedEvent.properties?.cast(), + options: processedEvent.options, ); return; } @@ -397,9 +456,12 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { ) : null; + final cleanedOptions = cleanEventOptions(processedEvent.options); + await _methodChannel.invokeMethod('screen', { 'screenName': finalScreenName, if (normalizedProperties != null) 'properties': normalizedProperties, + if (cleanedOptions != null) 'options': cleanedOptions, }); } on PlatformException catch (exception) { printIfDebug('Exeption on screen: $exception'); @@ -440,13 +502,20 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { } @override - Future alias({required String alias}) async { + Future alias({ + required String alias, + Map? options, + }) async { if (!isSupportedPlatform()) { return; } try { - await _methodChannel.invokeMethod('alias', {'alias': alias}); + final cleanedOptions = cleanEventOptions(options); + await _methodChannel.invokeMethod('alias', { + 'alias': alias, + if (cleanedOptions != null) 'options': cleanedOptions, + }); } on PlatformException catch (exception) { printIfDebug('Exeption on alias: $exception'); } @@ -585,15 +654,17 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { } @override - Future reloadFeatureFlags() async { + Future reloadFeatureFlags() async { if (!isSupportedPlatform()) { - return; + return featureFlagsLoadedFromMap(null); } try { - await _methodChannel.invokeMethod('reloadFeatureFlags'); + return featureFlagsLoadedFromMap( + await _methodChannel.invokeMethod('reloadFeatureFlags')); } on PlatformException catch (exception) { printIfDebug('Exeption on reloadFeatureFlags: $exception'); + return featureFlagsLoadedFromMap(null); } } @@ -672,12 +743,14 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { required String groupType, required String groupKey, Map? groupProperties, + Map? options, }) async { if (!isSupportedPlatform()) { return; } try { + final cleanedOptions = cleanEventOptions(options); final normalizedGroupProperties = groupProperties != null ? PropertyNormalizer.normalize(groupProperties) : null; @@ -687,6 +760,7 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { 'groupKey': groupKey, if (normalizedGroupProperties != null) 'groupProperties': normalizedGroupProperties, + if (cleanedOptions != null) 'options': cleanedOptions, }); } on PlatformException catch (exception) { printIfDebug('Exeption on group: $exception'); @@ -802,6 +876,7 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { required Object error, StackTrace? stackTrace, Map? properties, + Map? options, }) async { if (!isSupportedPlatform()) { return; @@ -821,6 +896,7 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { final processedEvent = await _runBeforeSend( PostHogEventName.exception, exceptionProps.cast(), + options: options, ); if (processedEvent == null) { printIfDebug( @@ -834,6 +910,7 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { await capture( eventName: processedEvent.event, properties: processedEvent.properties?.cast(), + options: processedEvent.options, ); return; } @@ -846,9 +923,12 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { ) : {}; + final cleanedOptions = cleanEventOptions(processedEvent.options); + await _methodChannel.invokeMethod('captureException', { 'timestamp': timestamp, 'properties': normalizedData, + if (cleanedOptions != null) 'options': cleanedOptions, }); } on PlatformException catch (exception) { printIfDebug('Exception in captureException: $exception'); diff --git a/posthog_flutter/lib/src/posthog_flutter_platform_interface.dart b/posthog_flutter/lib/src/posthog_flutter_platform_interface.dart index 993ac9a3..2dba870e 100644 --- a/posthog_flutter/lib/src/posthog_flutter_platform_interface.dart +++ b/posthog_flutter/lib/src/posthog_flutter_platform_interface.dart @@ -1,15 +1,17 @@ import 'package:plugin_platform_interface/plugin_platform_interface.dart'; import 'feature_flag_result.dart'; +import 'feature_flags_loaded.dart'; import 'logs/posthog_log_severity.dart'; import 'posthog_config.dart'; import 'posthog_flutter_io.dart'; /// Defines the callback signature for when feature flags are loaded. /// -/// Use [Posthog.getFeatureFlag] or [Posthog.isFeatureEnabled] within this -/// callback to access the loaded flag values. -typedef OnFeatureFlagsCallback = void Function(); +/// The callback receives the enabled flags and whether loading failed. See +/// [PostHogFeatureFlagsLoaded]. +typedef OnFeatureFlagsCallback = void Function( + PostHogFeatureFlagsLoaded loaded); abstract class PosthogFlutterPlatformInterface extends PlatformInterface { /// Constructs a PosthogFlutterPlatform. @@ -47,6 +49,7 @@ abstract class PosthogFlutterPlatformInterface extends PlatformInterface { required String userId, Map? userProperties, Map? userPropertiesSetOnce, + Map? options, }) { throw UnimplementedError('identify() has not been implemented.'); } @@ -54,6 +57,7 @@ abstract class PosthogFlutterPlatformInterface extends PlatformInterface { Future setPersonProperties({ Map? userPropertiesToSet, Map? userPropertiesToSetOnce, + Map? options, }) { throw UnimplementedError('setPersonProperties() has not been implemented.'); } @@ -63,13 +67,27 @@ abstract class PosthogFlutterPlatformInterface extends PlatformInterface { Map? properties, Map? userProperties, Map? userPropertiesSetOnce, + Map? options, }) { throw UnimplementedError('capture() has not been implemented.'); } + /// Captures an AI observability event on the AI lane. Returns the event's + /// UUID, or null when the event was not queued. + Future captureAi({ + required String eventName, + Map? properties, + Map? userProperties, + Map? userPropertiesSetOnce, + Map? options, + }) { + throw UnimplementedError('captureAi() has not been implemented.'); + } + Future screen({ required String screenName, Map? properties, + Map? options, }) { throw UnimplementedError('screen() has not been implemented.'); } @@ -117,7 +135,7 @@ abstract class PosthogFlutterPlatformInterface extends PlatformInterface { ); } - Future alias({required String alias}) { + Future alias({required String alias, Map? options}) { throw UnimplementedError('alias() has not been implemented.'); } @@ -173,7 +191,7 @@ abstract class PosthogFlutterPlatformInterface extends PlatformInterface { throw UnimplementedError('isFeatureEnabled() has not been implemented.'); } - Future reloadFeatureFlags() { + Future reloadFeatureFlags() { throw UnimplementedError('reloadFeatureFlags() has not been implemented.'); } @@ -212,6 +230,7 @@ abstract class PosthogFlutterPlatformInterface extends PlatformInterface { required String groupType, required String groupKey, Map? groupProperties, + Map? options, }) { throw UnimplementedError('group() has not been implemented.'); } @@ -244,6 +263,7 @@ abstract class PosthogFlutterPlatformInterface extends PlatformInterface { required Object error, StackTrace? stackTrace, Map? properties, + Map? options, }) { throw UnimplementedError('captureException() has not been implemented.'); } diff --git a/posthog_flutter/lib/src/posthog_flutter_web_handler.dart b/posthog_flutter/lib/src/posthog_flutter_web_handler.dart index 1e822330..fd482daa 100644 --- a/posthog_flutter/lib/src/posthog_flutter_web_handler.dart +++ b/posthog_flutter/lib/src/posthog_flutter_web_handler.dart @@ -1,6 +1,9 @@ // ignore_for_file: avoid_dynamic_calls, avoid_annotating_with_dynamic +import 'dart:async'; import 'dart:js_interop'; +import 'dart:js_interop_unsafe'; +import 'dart:math' show max; import 'package:flutter/foundation.dart' show visibleForTesting; import 'package:flutter/services.dart'; @@ -64,7 +67,7 @@ extension PostHogExtension on PostHog { external void unregister(JSAny key); // ignore: non_constant_identifier_names external JSAny? get_session_id(); - external void onFeatureFlags(JSFunction callback); + external JSFunction onFeatureFlags(JSFunction callback); external void startSessionRecording(); external void stopSessionRecording(); external bool sessionRecordingStarted(); @@ -72,10 +75,20 @@ extension PostHogExtension on PostHog { external void set_config(JSAny config); external JSObject? get config; external SessionManager? get sessionManager; + external FeatureFlags? get featureFlags; // ignore: non_constant_identifier_names external void _overrideSDKInfo(JSAny sdkName, JSAny sdkVersion); } +// Feature flags JS interop +@JS() +@staticInterop +class FeatureFlags {} + +extension FeatureFlagsExtension on FeatureFlags { + external JSObject getFlagVariants(); +} + // SessionManager JS interop @JS() @staticInterop @@ -200,6 +213,80 @@ String _exceptionMessage(Map properties) { return 'Exception'; } +/// posthog-js's pause between `/flags` retries. +const _flagsRetryDelayMs = 500; + +/// Reloads feature flags and completes with the flags that reload loaded. +/// +/// posthog-js 1.438.2+ has `reloadFeatureFlagsAsync()`, which settles after +/// this reload's own request, even when another request is already in flight. +/// Anything but a successful load reports the current flags with +/// `errorsLoading` set. +/// +/// Older posthog-js completes with the next flags posthog-js reports. It skips +/// the request without calling back when flags are disabled (completes right +/// away), and while reloading is paused or after repeated network failures +/// (completes once every request attempt posthog-js may make, including its +/// retries, would have timed out, plus one more request timeout). +Future> _reloadFeatureFlags(PostHog? ph) async { + final featureFlags = ph?.featureFlags; + if (ph == null || featureFlags == null) { + return {'variants': null, 'errorsLoading': true}; + } + Map currentFlags({required bool errorsLoading}) => { + 'variants': featureFlags.getFlagVariants().dartify(), + 'errorsLoading': errorsLoading + }; + + final flagsObject = featureFlags as JSObject; + if (flagsObject.has('reloadFeatureFlagsAsync')) { + final result = await flagsObject + .callMethod>('reloadFeatureFlagsAsync'.toJS) + .toDart; + final status = result?.getProperty('status'.toJS)?.toDart; + return currentFlags(errorsLoading: status != 'loaded'); + } + + final config = ph.config; + if (config + ?.getProperty('advanced_disable_feature_flags'.toJS) + ?.dartify() == + true) { + return currentFlags(errorsLoading: true); + } + + final reloaded = Completer>(); + var subscribed = false; + final unsubscribe = ph + .onFeatureFlags((JSArray flags, JSObject variants, [JSObject? context]) { + // onFeatureFlags replays the current flags synchronously: skip them. + if (!subscribed || reloaded.isCompleted) return; + reloaded.complete({ + 'variants': variants.dartify(), + 'errorsLoading': (context?.dartify() as Map?)?['errorsLoading'] == true, + }); + }.toJS); + subscribed = true; + ph.reloadFeatureFlags(); + + int? configInt(String key) => + (config?.getProperty(key.toJS)?.dartify() as num?)?.toInt(); + final requestTimeoutMs = configInt('feature_flag_request_timeout_ms') ?? 3000; + // posthog-js retries a timed-out /flags request within the same reload, + // 500 ms apart, so a successful retry can land well after one timeout. + final retries = max(0, configInt('feature_flag_request_max_retries') ?? 1); + try { + return await reloaded.future.timeout( + Duration( + milliseconds: + (retries + 2) * requestTimeoutMs + retries * _flagsRetryDelayMs), + onTimeout: () => currentFlags(errorsLoading: true), + ); + } finally { + unsubscribe.callAsFunction(); + } +} + Future handleWebMethodCall(MethodCall call) async { _maybeOverrideSDKInfo(); @@ -334,8 +421,7 @@ Future handleWebMethodCall(MethodCall call) async { ); break; case 'reloadFeatureFlags': - posthog?.reloadFeatureFlags(); - break; + return _reloadFeatureFlags(posthog); case 'setPersonPropertiesForFlags': final userProperties = safeMapConversion(args['userProperties']); // reload is orchestrated by the Dart layer, so disable it here. diff --git a/posthog_flutter/lib/src/utils/channel_serialization.dart b/posthog_flutter/lib/src/utils/channel_serialization.dart index 8fc7f2ec..34e00c25 100644 --- a/posthog_flutter/lib/src/utils/channel_serialization.dart +++ b/posthog_flutter/lib/src/utils/channel_serialization.dart @@ -1,4 +1,5 @@ import '../feature_flag_result.dart'; +import '../feature_flags_loaded.dart'; import '../posthog_config.dart'; import '../util/logging.dart'; @@ -21,6 +22,15 @@ extension PostHogConfigSerialization on PostHogConfig { 'surveys': surveys, 'personProfiles': personProfiles.name, 'compression': compression.name, + // Unset AI lane settings are omitted so the native defaults apply. + if (captureAiCompression != null) + 'captureAiCompression': captureAiCompression!.name, + if (captureAiMaxQueueSize != null) + 'captureAiMaxQueueSize': captureAiMaxQueueSize, + if (captureAiTimeout != null) + 'captureAiTimeoutSeconds': _captureAiTimeoutSeconds(captureAiTimeout!), + if (captureAiMaxEventBytes != null) + 'captureAiMaxEventBytes': captureAiMaxEventBytes, 'sessionReplay': sessionReplay, 'dataMode': dataMode.name, 'sessionReplayConfig': sessionReplayConfig.toMap(), @@ -36,6 +46,11 @@ extension PostHogConfigSerialization on PostHogConfig { if (bootstrap != null) 'bootstrap': bootstrap!.toMap(), }; } + + /// Android takes whole seconds. A positive sub-second timeout is sent as 1s + /// instead of 0, which the native SDKs read as "use the default". + static int _captureAiTimeoutSeconds(Duration timeout) => + timeout > Duration.zero && timeout.inSeconds < 1 ? 1 : timeout.inSeconds; } extension PostHogBootstrapConfigSerialization on PostHogBootstrapConfig { @@ -170,3 +185,18 @@ PostHogFeatureFlagResult? featureFlagResultFromMap( payload: result['payload'], ); } + +/// Reads a `{variants, errorsLoading}` map sent over the platform channel. +/// A missing or malformed map reads as empty flags with `errorsLoading` set. +PostHogFeatureFlagsLoaded featureFlagsLoadedFromMap(Object? map) { + if (map is! Map) { + return PostHogFeatureFlagsLoaded(variants: const {}, errorsLoading: true); + } + final variants = map['variants']; + return PostHogFeatureFlagsLoaded( + variants: variants is Map + ? {for (final e in variants.entries) '${e.key}': e.value} + : const {}, + errorsLoading: map['errorsLoading'] as bool? ?? false, + ); +} diff --git a/posthog_flutter/lib/src/utils/event_options.dart b/posthog_flutter/lib/src/utils/event_options.dart new file mode 100644 index 00000000..8f33f24c --- /dev/null +++ b/posthog_flutter/lib/src/utils/event_options.dart @@ -0,0 +1,46 @@ +import '../util/logging.dart'; +import 'property_normalizer.dart'; + +/// The known per-event option keys and the legacy event property each one +/// replaces. +const Map _legacyPropertyForOption = { + 'process_person_profile': r'$process_person_profile', + 'cookieless_mode': r'$cookieless_mode', + 'disable_skew_correction': r'$ignore_sent_at', + 'product_tour_id': r'$product_tour_id', +}; + +/// Returns a copy of [options] without null values, normalized for the +/// platform channel, or null when nothing is left. A null value means unset. +Map? cleanEventOptions(Map? options) { + if (options == null) return null; + final cleaned = PropertyNormalizer.normalize(options); + if (cleaned.isEmpty) return null; + return Map.from(cleaned); +} + +/// Converts [options] to the legacy event properties for posthog-js, which +/// has no options field. +/// +/// Known keys become their `$` property. Other keys have no legacy property, +/// so they are dropped with a debug log naming [method]. +Map eventOptionsToLegacyProperties( + Map? options, { + required String method, +}) { + final cleaned = cleanEventOptions(options); + if (cleaned == null) return const {}; + final properties = {}; + for (final entry in cleaned.entries) { + final legacyKey = _legacyPropertyForOption[entry.key]; + if (legacyKey != null) { + properties[legacyKey] = entry.value; + } else { + printIfDebug( + '[PostHog] $method option "${entry.key}" is not supported on this ' + 'platform and was dropped.', + ); + } + } + return properties; +} diff --git a/posthog_flutter/test/core/capture_ai_test.dart b/posthog_flutter/test/core/capture_ai_test.dart new file mode 100644 index 00000000..d63c33fa --- /dev/null +++ b/posthog_flutter/test/core/capture_ai_test.dart @@ -0,0 +1,316 @@ +import 'dart:convert'; +import 'dart:io'; + +import 'package:fake_async/fake_async.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:posthog_flutter/src/core/file_storage.dart'; +import 'package:posthog_flutter/src/core/posthog_core_stateless.dart'; +import 'package:posthog_flutter/src/posthog_config.dart'; +import 'package:posthog_flutter/src/posthog_desktop_client.dart'; + +import '../posthog_api_fake.dart'; +import 'test_client.dart'; + +/// Captures an AI event the way the desktop platform does, without +/// beforeSend callbacks. +String? captureAi( + DesktopPostHog client, + String event, { + Map? properties, +}) { + final prepared = client.prepareEvent(event, properties: properties); + return prepared == null + ? null + : client.capturePrepared(event, prepared, ai: true); +} + +/// The queued AI events, oldest first. +List> aiQueue(FileStorage storage) => [ + for (final queued in storage.aiQueue.peek(storage.aiQueue.length)) + queued.event, + ]; + +/// A string property that makes an event about [bytes] bytes long. +String filler(int bytes) => 'x' * bytes; + +void main() { + group('captureAi', () { + late LocalPostHogServer server; + + setUp(() async { + server = await LocalPostHogServer.start(); + }); + + test('sends to the AI endpoint only, and returns the event uuid', () async { + final client = testClient(server); + + final uuid = captureAi(client, r'$ai_generation', + properties: {r'$ai_model': 'gpt-5'}); + client.capture(r'$ai_generation'); + await client.flush(); + + final request = server.aiRequests.single; + final event = request.events.single; + expect(event['uuid'], uuid); + expect(event['event'], r'$ai_generation'); + expect((event['properties']! as Map)[r'$ai_model'], 'gpt-5'); + expect(event['session_id'], isA()); + expect(request.body['created_at'], isA()); + expect(request.headers['authorization'], 'Bearer k'); + expect( + request.headers['posthog-sdk-info'], startsWith('posthog-flutter/')); + expect(request.headers['posthog-attempt'], '1'); + expect(request.headers['content-encoding'], 'gzip'); + expect(server.batchRequests.single.eventNames, [r'$ai_generation'], + reason: 'capture never sends to the AI endpoint'); + }); + + test('compresses with captureAiCompression, apart from compression', + () async { + final client = testClient(server, + config: testConfig()..captureAiCompression = PostHogCompression.none); + + captureAi(client, r'$ai_generation'); + client.capture('event'); + await client.flush(); + + expect(server.aiRequests.single.headers, + isNot(contains('content-encoding'))); + expect(server.batchRequests.single.headers['content-encoding'], 'gzip'); + }); + + test('returns null and queues nothing while opted out', () { + final storage = tempStorage(); + final client = testClient(server, + config: testConfig(optOut: true), storage: storage); + + expect(captureAi(client, r'$ai_generation'), isNull); + expect(aiQueue(storage), isEmpty); + }); + + test('drops a serialized event over the limit, logging name and size only', + () { + final storage = tempStorage(); + final client = testClient(server, + config: testConfig(debug: true)..captureAiMaxEventBytes = 10000, + storage: storage); + + late String? fits; + final lines = printedLines(() { + fits = + captureAi(client, r'$ai_span', properties: {'input': filler(1000)}); + }); + expect(fits, isNotNull); + final size = utf8.encode(jsonEncode(aiQueue(storage).single)).length; + + final secret = 'secret-${filler(10000)}'; + String? oversized = 'not called'; + final dropLines = printedLines(() { + oversized = + captureAi(client, r'$ai_generation', properties: {'input': secret}); + }); + + expect(oversized, isNull); + expect(aiQueue(storage), hasLength(1)); + expect(size, lessThan(10000)); + expect(lines, isNot(contains(contains('Dropping')))); + final drop = dropLines.singleWhere((line) => line.contains('Dropping')); + expect(drop, contains(r'$ai_generation')); + expect(drop, contains('over the 10000 byte limit')); + expect(dropLines.join(), isNot(contains('secret'))); + }); + + test('caps captureAiMaxEventBytes at 8 MiB plus 64 KiB, with a warning', + () { + final storage = tempStorage(); + late DesktopPostHog client; + final lines = printedLines(() { + client = testClient(server, + config: testConfig(debug: true) + ..captureAiMaxEventBytes = 100 * 1024 * 1024, + storage: storage); + }); + + expect( + lines.where((line) => line.contains('byte ceiling')), hasLength(1)); + + expect( + captureAi(client, r'$ai_generation', + properties: {'input': filler(8 * 1024 * 1024 + 64 * 1024)}), + isNull, + ); + expect( + captureAi(client, r'$ai_generation', + properties: {'input': filler(8 * 1024 * 1024)}), + isNotNull, + ); + }); + + test('keeps captureAiMaxQueueSize AI events, apart from maxQueueSize', () { + final storage = tempStorage(); + final client = testClient(server, + config: testConfig(maxQueueSize: 1)..captureAiMaxQueueSize = 3, + storage: storage); + + for (var i = 0; i < 5; i++) { + captureAi(client, r'$ai_span', properties: {'i': i}); + } + client.capture('a'); + client.capture('b'); + + expect([ + for (final event in aiQueue(storage)) (event['properties']! as Map)['i'] + ], [ + 2, + 3, + 4 + ]); + expect(queuedEvents(storage), ['b']); + }); + + test('keeps at most 50 MiB of AI events, always the newest', () { + final storage = tempStorage(); + final client = testClient(server, storage: storage); + + for (var i = 0; i < 7; i++) { + captureAi(client, r'$ai_span', + properties: {'i': i, 'input': filler(8 * 1024 * 1024)}); + } + + expect([ + for (final event in aiQueue(storage)) (event['properties']! as Map)['i'] + ], [ + 1, + 2, + 3, + 4, + 5, + 6 + ]); + expect(storage.aiQueue.byteCount, lessThanOrEqualTo(50 * 1024 * 1024)); + }); + + test('flushes once 5 MiB of AI events are queued, below flushAt', () async { + final client = testClient(server); + + captureAi(client, r'$ai_span', properties: {'input': filler(3 << 20)}); + expect(server.aiRequests, isEmpty); + captureAi(client, r'$ai_span', properties: {'input': filler(3 << 20)}); + + await server.waitForAiEvent(r'$ai_span'); + }); + + test('AI events of a previous run are sent by the next client', () async { + final dir = tempDirectory(); + final first = testClient(server, storage: FileStorage(dir.path)); + final uuid = captureAi(first, r'$ai_trace'); + first.close(); + final next = testClient(server, storage: FileStorage(dir.path)); + + await next.flush(); + + expect(server.aiEvents.single['uuid'], uuid); + expect(Directory('${dir.path}/posthog_ai_queue').listSync(), isEmpty); + }); + + test('a 400 drops the AI batch without a retry', () async { + final storage = tempStorage(); + final client = testClient(server, storage: storage); + server.respond = (request) => request.isAi + ? const PostHogResponse(HttpStatus.badRequest) + : const PostHogResponse(HttpStatus.ok); + + captureAi(client, r'$ai_generation'); + client.capture('event'); + await expectLater(client.flush(), throwsA(isA())); + + expect(server.aiRequests, hasLength(1)); + expect(aiQueue(storage), isEmpty); + expect(server.eventNames, ['event'], + reason: 'an AI failure does not hold back the other events'); + }); + + test('a per-event retry keeps only that AI event queued', () async { + final storage = tempStorage(); + final client = testClient(server, storage: storage); + server.respond = (request) => request.isAi + ? PostHogResponse.results( + request, (name) => name == r'$ai_span' ? 'retry' : null) + : const PostHogResponse(HttpStatus.ok); + + captureAi(client, r'$ai_generation'); + captureAi(client, r'$ai_span'); + await client.flush(); + + expect([for (final event in aiQueue(storage)) event['event']], + [r'$ai_span']); + }); + + test( + 'a transient failure keeps the AI batch queued, retried under its own ' + 'request identity', () { + final api = InProcessPostHogApi() + ..respond = (request) => request.isAi + ? const PostHogResponse(HttpStatus.serviceUnavailable) + : const PostHogResponse(HttpStatus.ok); + final storage = tempStorage(); + fakeAsync((async) { + final client = testClient(api, storage: storage); + + captureAi(client, r'$ai_generation'); + client.flush().catchError((Object _) {}); + async.elapse(const Duration(seconds: 1)); + client.capture('event'); + client.flush().catchError((Object _) {}); + async.elapse(const Duration(seconds: 9)); + + expect(aiQueue(storage), hasLength(1)); + final attempts = [ + for (final request in api.aiRequests) + request.headers['posthog-attempt'], + ]; + expect(attempts, ['1', '2', '3', '4']); + expect( + {for (final r in api.aiRequests) r.headers['posthog-request-id']}, + hasLength(1)); + expect(api.batchRequests.single.headers['posthog-attempt'], '1'); + }); + }); + + test('the AI and analytics endpoints back off independently', () { + var batchStatus = HttpStatus.serviceUnavailable; + final api = InProcessPostHogApi() + ..respond = (request) => PostHogResponse( + request.isAi ? HttpStatus.serviceUnavailable : batchStatus); + final storage = tempStorage(); + fakeAsync((async) { + final client = testClient(api, storage: storage); + + // AI fails at 0, 1 and 3 s: its next retry is 4 s later, at 7 s. + captureAi(client, r'$ai_generation'); + client.flush().catchError((Object _) {}); + async.elapse(const Duration(milliseconds: 3500)); + expect(api.aiRequests, hasLength(3)); + + // Analytics starts its own backoff at 1 s, not at AI's 8 s. + client.capture('event'); + client.flush().catchError((Object _) {}); + async.flushMicrotasks(); + expect(api.batchRequests, hasLength(1)); + batchStatus = HttpStatus.ok; + async.elapse(const Duration(milliseconds: 900)); + expect(api.batchRequests, hasLength(1)); + async.elapse(const Duration(milliseconds: 200)); + expect(api.batchRequests, hasLength(2)); + expect(storage.queue.length, 0); + + // The delivered analytics batch leaves AI's backoff where it was. + async.elapse(const Duration(milliseconds: 2300)); // 6.9 s + expect(api.aiRequests, hasLength(3)); + async.elapse(const Duration(milliseconds: 200)); // 7.1 s + expect(api.aiRequests, hasLength(4)); + expect(aiQueue(storage), hasLength(1)); + }); + }); + }); +} diff --git a/posthog_flutter/test/core/capture_v1_test.dart b/posthog_flutter/test/core/capture_v1_test.dart index 65b35069..b5340483 100644 --- a/posthog_flutter/test/core/capture_v1_test.dart +++ b/posthog_flutter/test/core/capture_v1_test.dart @@ -95,41 +95,6 @@ void main() { }); }); - group('takeCaptureV1Batch', () { - PostHogQueuedEvent queued(String id, String padding) => - (id: id, event: {'p': padding}); - - test('closes the batch before the event that would pass the limit', () { - // Each event serializes to `{"p":""}`, 18 bytes here. - final events = [ - queued('a', 'x' * 10), - queued('b', 'x' * 10), - queued('c', 'x' * 10), - ]; - - final batch = takeCaptureV1Batch(events, maxBytes: 18 * 2); - - expect(batch.map((e) => e.id), ['a', 'b']); - }); - - test('sends an event over the limit alone', () { - final events = [queued('a', 'x' * 100), queued('b', 'x')]; - - final batch = takeCaptureV1Batch(events, maxBytes: 50); - - expect(batch.map((e) => e.id), ['a']); - }); - - test('counts UTF-8 bytes, not characters', () { - // Each event serializes to 18 characters but 28 bytes. - final events = [queued('a', 'é' * 10), queued('b', 'é' * 10)]; - - final batch = takeCaptureV1Batch(events, maxBytes: 18 * 2); - - expect(batch.map((e) => e.id), ['a']); - }); - }); - group('captureV1Event', () { final logger = CoreLogger((_) {}); diff --git a/posthog_flutter/test/core/context_properties_test.dart b/posthog_flutter/test/core/context_properties_test.dart index 2586102f..01994098 100644 --- a/posthog_flutter/test/core/context_properties_test.dart +++ b/posthog_flutter/test/core/context_properties_test.dart @@ -1,5 +1,4 @@ import 'package:flutter_test/flutter_test.dart'; -import 'package:posthog_flutter/src/posthog_flutter_version.dart'; import '../posthog_api_fake.dart'; import 'test_client.dart'; @@ -24,7 +23,7 @@ void main() { expect(props['foo'], 'bar'); }); - test('win over super properties and event properties', () { + test('lose to super properties and event properties', () { final storage = tempStorage(); final client = testClient(server, storage: storage, context: _context, timezone: 'Europe/Berlin'); @@ -37,10 +36,10 @@ void main() { }); final props = queuedProps(storage, 0); - expect(props[r'$os_name'], 'TestOS'); - expect(props[r'$app_version'], '1.0.0'); - expect(props[r'$timezone'], 'Europe/Berlin'); - expect(props[r'$lib'], postHogFlutterSdkName); + expect(props[r'$os_name'], 'FromSuperProps'); + expect(props[r'$app_version'], '2.0.0'); + expect(props[r'$timezone'], 'UTC'); + expect(props[r'$lib'], 'custom'); }); test('absent by default', () { diff --git a/posthog_flutter/test/core/desktop_parity_regressions_test.dart b/posthog_flutter/test/core/desktop_parity_regressions_test.dart index 05a79ac4..9d9d5f04 100644 --- a/posthog_flutter/test/core/desktop_parity_regressions_test.dart +++ b/posthog_flutter/test/core/desktop_parity_regressions_test.dart @@ -53,7 +53,7 @@ void main() { client.capture('purchase'); await client.reloadFeatureFlagsAsync(); - expect(queuedProps(storage, 0)[r'$process_person_profile'], isTrue); + expect(queuedOptions(storage, 0)['process_person_profile'], isNull); expect(server.flagsRequests.last.body['groups'], {'company': 'acme'}); }); @@ -121,6 +121,16 @@ void main() { expect(queuedEvents(storage), [r'$set']); }); + test('a personless identify does not update the marker', () { + final storage = tempStorage(); + final client = testClient(server, storage: storage); + client.register({r'$process_person_profile': false}); + client.identify('user', userProperties: {'plan': 'A'}); + client.unregister(r'$process_person_profile'); + client.setPersonProperties(userPropertiesToSet: {'plan': 'A'}); + expect(queuedEvents(storage), [r'$identify', r'$set']); + }); + test('opt-out does not update the marker for the latest person update', () { final storage = tempStorage(); final client = testClient(server, storage: storage); @@ -151,7 +161,7 @@ void main() { }); test( - 'session properties take precedence after caller properties and before registered properties', + 'session properties lose to registered properties and to caller properties', () { final storage = tempStorage(); final client = testClient(server, storage: storage); @@ -159,6 +169,6 @@ void main() { client.registerForSession({'plan': 'session', 'screen': 'Checkout'}); client.capture('purchase', properties: {'plan': 'event'}); expect(queuedProps(storage, 0)['plan'], 'event'); - expect(queuedProps(storage, 0)['screen'], 'Checkout'); + expect(queuedProps(storage, 0)['screen'], 'registered'); }); } diff --git a/posthog_flutter/test/core/feature_flags_test.dart b/posthog_flutter/test/core/feature_flags_test.dart index 7ae6601a..3ee7c794 100644 --- a/posthog_flutter/test/core/feature_flags_test.dart +++ b/posthog_flutter/test/core/feature_flags_test.dart @@ -687,7 +687,6 @@ void main() { r'$feature_flag', r'$feature_flag_response', r'$feature_flag_has_experiment', - r'$process_person_profile', r'$session_id', r'$lib', r'$lib_version', diff --git a/posthog_flutter/test/core/file_queue_test.dart b/posthog_flutter/test/core/file_queue_test.dart index 75dfad4b..61ddcb43 100644 --- a/posthog_flutter/test/core/file_queue_test.dart +++ b/posthog_flutter/test/core/file_queue_test.dart @@ -70,6 +70,51 @@ void main() { expect(restored.byteCount, size(third)); }); + group('peek with maxBytes', () { + // Each event serializes to `{"p":""}`, 18 bytes here. + FileEventQueue queueOf(List paddings) { + final storage = FileStorage(dir.path); + addTearDown(storage.close); + final queue = storage.queue; + for (final padding in paddings) { + queue.add({'p': padding}); + } + return queue; + } + + List paddingsOf(List events) => + [for (final queued in events) queued.event['p']]; + + test('stops before the event that would pass the limit', () { + final queue = queueOf(['a' * 10, 'b' * 10, 'c' * 10]); + + expect( + paddingsOf(queue.peek(10, maxBytes: 18 * 2)), ['a' * 10, 'b' * 10]); + }); + + test('returns an event over the limit alone', () { + final queue = queueOf(['a' * 100, 'b']); + + expect(paddingsOf(queue.peek(10, maxBytes: 50)), ['a' * 100]); + }); + + test('counts UTF-8 bytes, not characters', () { + // 18 characters but 28 bytes each. + final queue = queueOf(['é' * 10, 'è' * 10]); + + expect(paddingsOf(queue.peek(10, maxBytes: 18 * 2)), ['é' * 10]); + }); + + test('does not read the events past the limit', () { + final queue = queueOf(['a' * 10, 'b' * 10]); + // Unreadable: a peek that read it would delete it. + final second = _queueFiles(dir).last..writeAsStringSync('not json'); + + expect(paddingsOf(queue.peek(10, maxBytes: 18)), ['a' * 10]); + expect(second.existsSync(), isTrue); + }); + }); + test('keeps the queue order across a restart', () async { final before = client(); for (var i = 0; i < 50; i++) { diff --git a/posthog_flutter/test/core/posthog_core_test.dart b/posthog_flutter/test/core/posthog_core_test.dart index dae2cb47..51b5f47c 100644 --- a/posthog_flutter/test/core/posthog_core_test.dart +++ b/posthog_flutter/test/core/posthog_core_test.dart @@ -40,7 +40,7 @@ void main() { test('keeps an anonymous user personless', () { client.capture('test_event'); - expect(queuedProps(storage, 0)[r'$process_person_profile'], isFalse); + expect(queuedOptions(storage, 0)['process_person_profile'], isFalse); expect(queuedProps(storage, 0)[r'$is_identified'], isFalse); }); @@ -52,9 +52,9 @@ void main() { }); client.capture('next_event'); - expect(queuedProps(storage, 0)[r'$process_person_profile'], isTrue, + expect(queuedOptions(storage, 0)['process_person_profile'], isNull, reason: 'sending person properties asks for a person profile'); - expect(queuedProps(storage, 1)[r'$process_person_profile'], isTrue); + expect(queuedOptions(storage, 1)['process_person_profile'], isNull); }); } @@ -68,7 +68,7 @@ void main() { r'$set': {'plan': 'pro'}, }); - expect(queuedProps(storage, 0)[r'$process_person_profile'], isFalse); + expect(queuedOptions(storage, 0)['process_person_profile'], isFalse); }); test(r'$groups apply to that event only', () async { @@ -81,7 +81,7 @@ void main() { expect(queuedProps(storage, 0)[r'$groups'], {'company': 'acme'}); expect(queuedProps(storage, 1).containsKey(r'$groups'), isFalse); - expect(queuedProps(storage, 1)[r'$process_person_profile'], isFalse); + expect(queuedOptions(storage, 1)['process_person_profile'], isFalse); expect(reloads, 0, reason: 'an event-level group is not a group change'); }); @@ -103,8 +103,9 @@ void main() { expect(first[r'$sdk_debug_current_session_duration'], greaterThanOrEqualTo(10)); expect(first[r'$sdk_debug_pending_queue_size'], 0); - expect(queuedProps(storage, 1)[r'$sdk_debug_pending_queue_size'], 1, - reason: 'SDK debug values win over a registered super property'); + expect(queuedProps(storage, 1)[r'$sdk_debug_pending_queue_size'], + 'registered', + reason: 'a registered super property wins over SDK values'); }); }); @@ -187,7 +188,7 @@ void main() { expect(queuedEvents(storage), [r'$set'], reason: r'there is no anonymous history to link, so no $identify'); expect(queuedProps(storage, 0)[r'$is_identified'], isTrue); - expect(queuedProps(storage, 0)[r'$process_person_profile'], isTrue); + expect(queuedOptions(storage, 0)['process_person_profile'], isNull); expect(reloads, 0, reason: 'the identified state alone does not affect flags'); }); @@ -253,7 +254,10 @@ void main() { for (final event in [r'$identify', r'$create_alias', r'$groupidentify']) { final props = queuedPropsOf(storage, event); - expect(props[r'$process_person_profile'], isTrue, reason: event); + final message = getQueue(storage) + .singleWhere((message) => message['event'] == event); + expect(message, isNot(contains('options')), + reason: '$event: person-processed events omit the option'); expect(props[r'$is_identified'], isTrue, reason: event); expect(props, contains(r'$sdk_debug_session_start'), reason: event); } @@ -367,14 +371,14 @@ void main() { client = testClient(server, storage: storage); }); - test("win over registered properties, not over the event's own", () { - client.register({'screen': 'registered', 'plan': 'free'}); + test("lose to registered properties and to the event's own", () { + client.register({'screen': 'registered'}); client.registerForSession({'screen': 'Checkout', 'plan': 'trial'}); client.capture('first'); client.capture('second', properties: {'plan': 'pro'}); - expect(queuedProps(storage, 0)['screen'], 'Checkout'); + expect(queuedProps(storage, 0)['screen'], 'registered'); expect(queuedProps(storage, 0)['plan'], 'trial'); expect(queuedProps(storage, 1)['plan'], 'pro'); }); @@ -425,7 +429,7 @@ void main() { client.capture('next_event'); expect(queuedEvents(storage), ['next_event']); - expect(queuedProps(storage, 0)[r'$process_person_profile'], isFalse, + expect(queuedOptions(storage, 0)['process_person_profile'], isFalse, reason: 'an ignored alias does not turn on person processing'); expect(lines, contains(contains('empty alias'))); }); diff --git a/posthog_flutter/test/core/queue_flush_test.dart b/posthog_flutter/test/core/queue_flush_test.dart index f5483cc5..d839fa77 100644 --- a/posthog_flutter/test/core/queue_flush_test.dart +++ b/posthog_flutter/test/core/queue_flush_test.dart @@ -31,6 +31,34 @@ void main() { expect(getQueue(storage), isEmpty); }); + test('emits each delivered batch as soon as it is sent', () async { + final client = testClient(server, + config: testConfig(maxBatchSize: 2), storage: tempStorage()); + final emitted = >[]; + final requestsAtEmit = []; + // ignore: invalid_use_of_protected_member + client.events.on('flush', (payload) { + emitted.add([ + for (final event in payload! as List>) + event['event'], + ]); + requestsAtEmit.add(server.batchRequests.length); + }); + + client.capture('a'); + client.capture('b'); + client.capture('c'); + await client.flush(); + + expect(emitted, [ + ['a', 'b'], + ['c'], + ]); + // Emitted before the next request, so a long flush doesn't keep the + // payloads of every batch it sent. + expect(requestsAtEmit, [1, 2]); + }); + test('removes sent events by identity when the queue head shifts', () async { final storage = tempStorage(); diff --git a/posthog_flutter/test/core/test_client.dart b/posthog_flutter/test/core/test_client.dart index 5af59e7f..de35e5fd 100644 --- a/posthog_flutter/test/core/test_client.dart +++ b/posthog_flutter/test/core/test_client.dart @@ -100,6 +100,12 @@ Map queuedProps(FileStorage storage, int index) { return queuedMessage(storage, index)['properties'] as Map; } +/// The capture v1 options of the queued event message at [index], empty +/// when it has none. +Map queuedOptions(FileStorage storage, int index) => + Map.from( + (queuedMessage(storage, index)['options'] ?? const {}) as Map); + /// The names of the queued events, oldest first. List queuedEvents(FileStorage storage) => [for (final message in getQueue(storage)) message['event']]; diff --git a/posthog_flutter/test/event_shape_snapshot_test.dart b/posthog_flutter/test/event_shape_snapshot_test.dart index d06a6711..0320d7e0 100644 --- a/posthog_flutter/test/event_shape_snapshot_test.dart +++ b/posthog_flutter/test/event_shape_snapshot_test.dart @@ -90,6 +90,41 @@ void main() { expect(arguments['compression'], 'none'); }); + test('captureAi settings are omitted when unset', () async { + await Posthog().setup(PostHogConfig('snapshot_project_token')); + + final arguments = calls.single.arguments as Map; + expect( + arguments.keys.where((key) => '$key'.startsWith('captureAi')), + isEmpty, + ); + }); + + test('captureAi settings are sent to native setup when set', () async { + final config = PostHogConfig('snapshot_project_token') + ..captureAiCompression = PostHogCompression.none + ..captureAiMaxQueueSize = 7 + ..captureAiTimeout = const Duration(seconds: 90) + ..captureAiMaxEventBytes = 1024; + + await Posthog().setup(config); + + final arguments = calls.single.arguments as Map; + expect(arguments['captureAiCompression'], 'none'); + expect(arguments['captureAiMaxQueueSize'], 7); + expect(arguments['captureAiTimeoutSeconds'], 90); + expect(arguments['captureAiMaxEventBytes'], 1024); + }); + + test('a sub-second captureAi timeout is sent as one second', () async { + final config = PostHogConfig('snapshot_project_token') + ..captureAiTimeout = const Duration(milliseconds: 500); + + await Posthog().setup(config); + + expect((calls.single.arguments as Map)['captureAiTimeoutSeconds'], 1); + }); + test('snapshots event and identity channel shapes', () async { final config = PostHogConfig( 'snapshot_project_token', diff --git a/posthog_flutter/test/posthog_api_fake.dart b/posthog_flutter/test/posthog_api_fake.dart index b2c7646c..d3b52fd2 100644 --- a/posthog_flutter/test/posthog_api_fake.dart +++ b/posthog_flutter/test/posthog_api_fake.dart @@ -37,6 +37,9 @@ class PostHogRequest { /// Whether this is a capture v1 request for analytics events. bool get isBatch => path == '/i/v1/analytics/events'; + /// Whether this is a capture v1 request for AI events. + bool get isAi => path == '/i/v1/ai/events'; + bool get isFlags => path == '/flags/'; /// The events of a capture request, oldest first. @@ -120,6 +123,21 @@ abstract class PostHogApiFake { if (request.isBatch) request ]; + List get aiRequests => [ + for (final request in requests) + if (request.isAi) request + ]; + + /// Every AI event received, oldest first. + List> get aiEvents => + [for (final request in aiRequests) ...request.events]; + + /// Completes with the first AI event named [name] once it has arrived. + Future> waitForAiEvent(String name) async { + await _waitUntil(() => aiEvents.any((event) => event['event'] == name)); + return aiEvents.firstWhere((event) => event['event'] == name); + } + List get flagsRequests => [ for (final request in requests) if (request.isFlags) request diff --git a/posthog_flutter/test/posthog_flutter_desktop_test.dart b/posthog_flutter/test/posthog_flutter_desktop_test.dart index 79b1f7c7..69f09164 100644 --- a/posthog_flutter/test/posthog_flutter_desktop_test.dart +++ b/posthog_flutter/test/posthog_flutter_desktop_test.dart @@ -5,8 +5,10 @@ import 'dart:ui'; import 'package:flutter_test/flutter_test.dart'; import 'package:posthog_flutter/src/error_tracking/posthog_error_tracking_autocapture_integration.dart'; import 'package:posthog_flutter/src/feature_flag_result.dart'; +import 'package:posthog_flutter/src/feature_flags_loaded.dart'; import 'package:posthog_flutter/src/posthog_config.dart'; import 'package:posthog_flutter/src/posthog_desktop_app_info.dart'; +import 'package:posthog_flutter/src/posthog_event.dart'; import 'package:posthog_flutter/src/posthog_flutter_desktop.dart'; import 'package:posthog_flutter/src/posthog_flutter_version.dart'; @@ -218,6 +220,26 @@ void main() { expect(_propertiesOf(event)[r'$set'], {'plan': 'pro', 'team': 'core'}); }); + test(r'a beforeSend that removes a legacy $set keeps it off the event', + () async { + final server = await LocalPostHogServer.start(); + final config = configFor(server) + ..beforeSend = [ + (event) => event..properties?.remove(r'$set'), + ]; + final platform = await setUpPlatform(config); + + await platform.capture( + eventName: 'redacted', + properties: { + r'$set': {'email': 'a@b.c'}, + }, + ); + + final event = await server.waitForEvent('redacted'); + expect(_propertiesOf(event), isNot(contains(r'$set'))); + }); + test(r'reports the platform language as $locale', () async { final server = await LocalPostHogServer.start(); final platform = await setUpPlatform(configFor(server)); @@ -282,7 +304,8 @@ void main() { expect(flags, isNot(contains('timezone'))); }); - test(r'reports $recording_status disabled on every event', () async { + test(r'reports $recording_status disabled unless the event sets it', + () async { final server = await LocalPostHogServer.start(); final platform = await setUpPlatform(configFor(server)); @@ -295,7 +318,7 @@ void main() { final identify = await server.waitForEvent(r'$identify'); expect(_propertiesOf(identify)[r'$recording_status'], 'disabled'); final captured = await server.waitForEvent('replay event'); - expect(_propertiesOf(captured)[r'$recording_status'], 'disabled'); + expect(_propertiesOf(captured)[r'$recording_status'], 'active'); }); }); @@ -526,6 +549,31 @@ void main() { expect(server.eventNames, isNot(contains('original event'))); }); + test('a callback editing a registered nested map leaves later events alone', + () async { + final server = await LocalPostHogServer.start(); + final config = configFor(server) + ..beforeSend = [ + (event) { + if (event.event == 'mutate') { + final metadata = event.properties?['metadata']; + if (metadata is Map) metadata['plan'] = 'pro'; + } + return event; + }, + ]; + final platform = await setUpPlatform(config); + await platform.register('metadata', {'plan': 'free'}); + + await platform.capture(eventName: 'mutate'); + await platform.capture(eventName: 'after'); + + final mutated = _propertiesOf(await server.waitForEvent('mutate')); + final after = _propertiesOf(await server.waitForEvent('after')); + expect(mutated['metadata'], {'plan': 'pro'}); + expect(after['metadata'], {'plan': 'free'}); + }); + test('a callback can rewrite the person properties', () async { final server = await LocalPostHogServer.start(); final config = configFor(server) @@ -543,6 +591,94 @@ void main() { expect(_propertiesOf(event)[r'$set'], {'plan': 'enterprise'}); }); + test('flag evaluation gets the person properties the callbacks keep', + () async { + final server = await LocalPostHogServer.start(); + final config = configFor(server) + ..preloadFeatureFlags = false + ..beforeSend = [ + (event) { + if (event.event == 'dropped') return null; + return event + ..userProperties = {'email': 'redacted'} + ..userPropertiesSetOnce = null; + }, + ]; + final platform = await setUpPlatform(config); + + await platform.capture( + eventName: 'redacted', + userProperties: {'email': 'user@example.com'}, + userPropertiesSetOnce: {'first_seen': 'secret'}, + ); + await platform.capture( + eventName: 'dropped', + userProperties: {'dropped': 'secret'}, + ); + await platform.reloadFeatureFlags(); + + final personProperties = Map.from( + server.flagsRequests.single.body['person_properties']! as Map, + ); + expect(personProperties, containsPair('email', 'redacted')); + expect(personProperties, isNot(contains('first_seen'))); + expect(personProperties, isNot(contains('dropped'))); + }); + + test('a dropped person update does not turn on person processing', + () async { + final server = await LocalPostHogServer.start(); + final config = configFor(server) + ..beforeSend = [ + (event) => event.event == 'dropped' ? null : event, + ]; + final platform = await setUpPlatform(config); + + await platform.capture( + eventName: 'dropped', + userProperties: {'email': 'user@example.com'}, + ); + await platform.capture(eventName: 'after drop'); + + final event = await server.waitForEvent('after drop'); + expect(_optionsOf(event)['process_person_profile'], isFalse); + }); + + test('an event whose person properties are removed is personless', + () async { + final server = await LocalPostHogServer.start(); + final config = configFor(server) + ..beforeSend = [(event) => event..userProperties = null]; + final platform = await setUpPlatform(config); + + await platform.capture( + eventName: 'redacted', + userProperties: {'email': 'user@example.com'}, + ); + + final event = await server.waitForEvent('redacted'); + expect(_optionsOf(event)['process_person_profile'], isFalse); + }); + + test('a callback can turn person processing back on', () async { + final server = await LocalPostHogServer.start(); + final config = configFor(server) + ..beforeSend = [ + (event) => event + ..userProperties = null + ..options = {'process_person_profile': true}, + ]; + final platform = await setUpPlatform(config); + + await platform.capture( + eventName: 'redacted', + userProperties: {'email': 'user@example.com'}, + ); + + final event = await server.waitForEvent('redacted'); + expect(_optionsOf(event)['process_person_profile'], isTrue); + }); + test('a throwing callback drops the event and stops the chain', () async { final server = await LocalPostHogServer.start(); final callOrder = []; @@ -576,17 +712,28 @@ void main() { expect(callOrder, ['transform', 'throw']); }); - test('callbacks see user-provided properties only', () async { + test('callbacks see and change the properties and options the SDK adds', + () async { final server = await LocalPostHogServer.start(); - Map? seenProperties; + PostHogEvent? seen; final config = configFor(server) ..beforeSend = [ (event) { - seenProperties = event.properties; + seen = PostHogEvent( + event: event.event, + properties: {...?event.properties}, + options: {...?event.options}, + ); + event.properties = { + ...?event.properties, + r'$device_type': 'Kiosk', + }..remove(r'$os_name'); + event.options = null; return event; }, ]; final platform = await setUpPlatform(config); + await platform.register('plan', 'free'); await platform.capture( eventName: 'context event', @@ -594,22 +741,84 @@ void main() { ); final event = await server.waitForEvent('context event'); - // The whole map: no $session_id, $lib or other SDK enrichment is - // visible to the hook... - expect(seenProperties, {'plan': 'pro'}); - // ...while the delivered event is still enriched after the hook ran. + final seenProperties = seen!.properties!; + expect(seenProperties, containsPair('plan', 'pro'), + reason: 'the event wins over a registered property'); + expect(seenProperties, containsPair(r'$device_type', 'Desktop')); + expect(seenProperties, contains(r'$os_name')); + expect(seenProperties, contains(r'$session_id')); + expect(seenProperties, contains(r'$lib')); + expect(seen!.options, {'process_person_profile': false}); + // The SDK adds nothing back after the hook ran. final properties = _propertiesOf(event); - expect(properties, containsPair(r'$device_type', 'Desktop')); + expect(properties, containsPair(r'$device_type', 'Kiosk')); + expect(properties, isNot(contains(r'$os_name'))); + expect(event, isNot(contains('options'))); expect(event['session_id'], isA()); }); + test('properties the callbacks remove stay removed', () async { + final server = await LocalPostHogServer.start(); + server.respond = (_) => PostHogResponse.json(_variantFlagResponse()); + final flagsLoaded = Completer(); + Map? seen; + final removed = [ + r'$feature/variant-flag', + r'$active_feature_flags', + r'$recording_status', + ]; + final config = configFor(server) + ..onFeatureFlags = (_) { + if (!flagsLoaded.isCompleted) flagsLoaded.complete(); + } + ..beforeSend = [ + (event) { + seen = {...?event.properties}; + event.properties = {...?event.properties} + ..removeWhere((key, _) => removed.contains(key)); + return event; + }, + ]; + final platform = await setUpPlatform(config); + await flagsLoaded.future; + + await platform.capture(eventName: 'scrubbed'); + + final properties = _propertiesOf(await server.waitForEvent('scrubbed')); + expect(seen!.keys, containsAll(removed)); + for (final key in removed) { + expect(properties, isNot(contains(key))); + } + }); + + test('the event time is taken before the callbacks run', () async { + final server = await LocalPostHogServer.start(); + late DateTime hookStarted; + final config = configFor(server) + ..beforeSend = [ + (event) async { + hookStarted = DateTime.now().toUtc(); + // Real wait: the event must not take the time it is queued. + await Future.delayed(const Duration(milliseconds: 50)); + return event; + }, + ]; + final platform = await setUpPlatform(config); + + await platform.capture(eventName: 'slow hook'); + + final event = await server.waitForEvent('slow hook'); + final timestamp = DateTime.parse(event['timestamp']! as String); + expect(timestamp.isAfter(hookStarted), isFalse); + }); + test('SDK-internal events bypass the callbacks', () async { final server = await LocalPostHogServer.start(); server.respond = (_) => PostHogResponse.json(_variantFlagResponse()); final flagsLoaded = Completer(); final seenEventNames = []; final config = configFor(server) - ..onFeatureFlags = () { + ..onFeatureFlags = (_) { if (!flagsLoaded.isCompleted) flagsLoaded.complete(); } ..beforeSend = [ @@ -953,6 +1162,221 @@ void main() { }); }); + group('Event options', () { + test('are sent as they are, winning over their legacy properties', + () async { + final server = await LocalPostHogServer.start(); + final platform = await setUpPlatform(configFor(server)); + + await platform.capture( + eventName: 'tour step', + properties: {r'$product_tour_id': 'from-property'}, + options: { + 'process_person_profile': false, + 'cookieless_mode': true, + 'disable_skew_correction': true, + 'product_tour_id': 'from-option', + 'unknown_option': {'nested': 'x'}, + 'unset_option': null, + }, + ); + + final event = await server.waitForEvent('tour step'); + expect(event['options'], { + 'process_person_profile': false, + 'cookieless_mode': true, + 'disable_skew_correction': true, + 'product_tour_id': 'from-option', + 'unknown_option': {'nested': 'x'}, + }); + expect(_propertiesOf(event), isNot(contains(r'$product_tour_id'))); + }); + + test('a process_person_profile option applies to its event only', () async { + final server = await LocalPostHogServer.start(); + final platform = await setUpPlatform(configFor(server)); + + await platform.capture( + eventName: 'processed', + options: {'process_person_profile': true}, + ); + await platform.capture(eventName: 'anonymous'); + + final processed = await server.waitForEvent('processed'); + final anonymous = await server.waitForEvent('anonymous'); + expect(_optionsOf(processed)['process_person_profile'], isTrue); + expect(_optionsOf(anonymous)['process_person_profile'], isFalse); + }); + + test('beforeSend can change them', () async { + final server = await LocalPostHogServer.start(); + final config = configFor(server) + ..beforeSend = [ + (event) { + event.options = { + ...?event.options, + 'product_tour_id': 'from-hook', + }; + return event; + }, + ]; + final platform = await setUpPlatform(config); + + await platform.screen( + screenName: 'Home', + options: {'product_tour_id': 'from-call'}, + ); + await platform.captureException( + error: StateError('boom'), + options: {'disable_skew_correction': true}, + ); + + final screen = _optionsOf(await server.waitForEvent(r'$screen')); + final exception = _optionsOf(await server.waitForEvent(r'$exception')); + expect(screen['product_tour_id'], 'from-hook'); + expect(exception['product_tour_id'], 'from-hook'); + expect(exception['disable_skew_correction'], isTrue); + }); + + test('reach the events identify, setPersonProperties, group and alias send', + () async { + final server = await LocalPostHogServer.start(); + final platform = await setUpPlatform(configFor(server)); + Map options(String id) => + {'product_tour_id': id, 'cookieless_mode': false, 'custom': id}; + + await platform.identify(userId: 'user-1', options: options('identify')); + await platform.setPersonProperties( + userPropertiesToSet: {'plan': 'pro'}, + options: options('set'), + ); + await platform.group( + groupType: 'company', + groupKey: 'acme', + options: options('group'), + ); + await platform.alias(alias: 'alias-1', options: options('alias')); + + for (final (name, id) in [ + (r'$identify', 'identify'), + (r'$set', 'set'), + (r'$groupidentify', 'group'), + (r'$create_alias', 'alias'), + ]) { + final options = _optionsOf(await server.waitForEvent(name)); + expect(options['product_tour_id'], id, reason: name); + expect(options['cookieless_mode'], isFalse, reason: name); + expect(options['custom'], id, reason: name); + } + }); + + test(r'a personless $set does not mark the person properties as sent', + () async { + final server = await LocalPostHogServer.start(); + final platform = await setUpPlatform(configFor(server)); + await platform.identify(userId: 'user-1'); + + await platform.setPersonProperties( + userPropertiesToSet: {'plan': 'pro'}, + options: {'process_person_profile': false}, + ); + await platform.setPersonProperties(userPropertiesToSet: {'plan': 'pro'}); + await platform.capture(eventName: 'done'); + await server.waitForEvent('done'); + + final sets = [ + for (final event in server.events) + if (event['event'] == r'$set') _optionsOf(event), + ]; + expect( + [for (final set in sets) set['process_person_profile']], + [isFalse, isNull], + ); + }); + }); + + group('captureAi', () { + test('sends to the AI endpoint through beforeSend and returns the uuid', + () async { + final server = await LocalPostHogServer.start(); + PostHogEvent? seen; + final config = configFor(server) + ..beforeSend = [ + (event) { + seen = event; + event.properties = {...?event.properties, 'from_hook': true}; + return event; + }, + ]; + final platform = await setUpPlatform(config); + + final uuid = await platform.captureAi( + eventName: r'$ai_generation', + properties: {r'$ai_model': 'gpt-5'}, + options: {'custom': 'x'}, + ); + await platform.flush(); + + final event = await server.waitForAiEvent(r'$ai_generation'); + expect(uuid, isNotNull); + expect(event['uuid'], uuid); + expect(_propertiesOf(event)[r'$ai_model'], 'gpt-5'); + expect(_propertiesOf(event)['from_hook'], isTrue); + expect(_optionsOf(event)['custom'], 'x'); + expect(seen!.properties, contains(r'$session_id')); + expect(server.eventNames, isNot(contains(r'$ai_generation'))); + }); + + test('returns null when beforeSend drops the event', () async { + final server = await LocalPostHogServer.start(); + final platform = await setUpPlatform(configFor(server) + ..beforeSend = [ + (event) => event.event == r'$ai_generation' ? null : event, + ]); + + final uuid = await platform.captureAi(eventName: r'$ai_generation'); + await platform.captureAi(eventName: r'$ai_span'); + + expect(uuid, isNull); + await server.waitForAiEvent(r'$ai_span'); + expect(server.aiEvents, hasLength(1)); + }); + + test('returns null when the event is over captureAiMaxEventBytes', + () async { + final server = await LocalPostHogServer.start(); + final platform = + await setUpPlatform(configFor(server)..captureAiMaxEventBytes = 4096); + + final uuid = await platform.captureAi( + eventName: r'$ai_generation', + properties: {r'$ai_input': 'x' * 5000}, + ); + + expect(uuid, isNull); + }); + + test('returns null while opted out', () async { + final server = await LocalPostHogServer.start(); + final platform = await setUpPlatform(configFor(server)); + await platform.optOut(); + + expect(await platform.captureAi(eventName: r'$ai_generation'), isNull); + }); + + test('logs a non-AI event name and still sends it', () async { + final server = await LocalPostHogServer.start(); + final platform = await setUpPlatform(configFor(server)); + + final lines = await _printsOf( + () => platform.captureAi(eventName: 'not an AI event')); + + expect(lines, [contains(r'does not start with $ai_')]); + await platform.flush(); + expect(server.aiEvents.single['event'], 'not an AI event'); + }); + }); + group('Application lifecycle', () { /// A launch of the app with [build], keeping its state in [appDirectory]. PosthogFlutterDesktop launch( @@ -1728,7 +2152,7 @@ void main() { server.respond = (_) => PostHogResponse.json(_variantFlagResponse()); final flagsLoaded = Completer(); final config = configFor(server) - ..onFeatureFlags = () { + ..onFeatureFlags = (_) { if (!flagsLoaded.isCompleted) flagsLoaded.complete(); }; final platform = await setUpPlatform(config); @@ -1758,7 +2182,7 @@ void main() { server.respond = (_) => PostHogResponse.json(_variantFlagResponse()); final flagsLoaded = Completer(); final config = configFor(server) - ..onFeatureFlags = () { + ..onFeatureFlags = (_) { if (!flagsLoaded.isCompleted) flagsLoaded.complete(); }; final platform = await setUpPlatform(config); @@ -1794,7 +2218,7 @@ void main() { server.respond = (_) => PostHogResponse.json(_variantFlagResponse()); final flagsLoaded = Completer(); final config = configFor(server) - ..onFeatureFlags = () { + ..onFeatureFlags = (_) { if (!flagsLoaded.isCompleted) flagsLoaded.complete(); }; final platform = await setUpPlatform(config); @@ -1813,7 +2237,7 @@ void main() { server.respond = (_) => PostHogResponse.json(_variantFlagResponse()); final flagsLoaded = Completer(); final config = configFor(server) - ..onFeatureFlags = () { + ..onFeatureFlags = (_) { if (!flagsLoaded.isCompleted) flagsLoaded.complete(); }; final platform = await setUpPlatform(config); @@ -1840,7 +2264,7 @@ void main() { final flagsLoaded = Completer(); final config = configFor(server) ..sendFeatureFlagEvent = false - ..onFeatureFlags = () { + ..onFeatureFlags = (_) { if (!flagsLoaded.isCompleted) flagsLoaded.complete(); }; final platform = await setUpPlatform(config); @@ -1891,6 +2315,27 @@ void main() { expect(server.eventNames, isNot(contains(r'$feature_flag_called'))); }); + test( + 'reloadFeatureFlags returns the loaded flags, and the last known ones when loading fails', + () async { + final server = await LocalPostHogServer.start(); + server.respond = (_) => PostHogResponse.json(_variantFlagResponse()); + final announced = []; + final platform = await setUpPlatform(configFor(server) + ..preloadFeatureFlags = false + ..onFeatureFlags = announced.add); + + final loaded = await platform.reloadFeatureFlags(); + expect(loaded.variants, {'variant-flag': 'test-variant'}); + expect(loaded.errorsLoading, isFalse); + + server.respond = (_) => const PostHogResponse(HttpStatus.badRequest); + final failed = await platform.reloadFeatureFlags(); + expect(failed.variants, {'variant-flag': 'test-variant'}); + expect(failed.errorsLoading, isTrue); + expect(announced.last.errorsLoading, isTrue); + }); + test('onFeatureFlags reports the flags cached by the previous launch', () async { final server = await LocalPostHogServer.start(); @@ -1907,7 +2352,7 @@ void main() { final announced = Completer(); await platform.setup(configFor(server) ..preloadFeatureFlags = false - ..onFeatureFlags = () { + ..onFeatureFlags = (_) { payloads.add(platform .getFeatureFlagResult( key: 'variant-flag', sendFeatureFlagEvent: false) @@ -1928,6 +2373,9 @@ void main() { Map _propertiesOf(Map event) => Map.from(event['properties']! as Map); +Map _optionsOf(Map event) => + Map.from((event['options'] ?? const {}) as Map); + /// Runs [body] and returns the lines it printed. Future> _printsOf(Future Function() body) async { final lines = []; diff --git a/posthog_flutter/test/posthog_flutter_io_test.dart b/posthog_flutter/test/posthog_flutter_io_test.dart index b33e9db0..34dfec30 100644 --- a/posthog_flutter/test/posthog_flutter_io_test.dart +++ b/posthog_flutter/test/posthog_flutter_io_test.dart @@ -4,6 +4,7 @@ import 'package:flutter/services.dart'; import 'package:flutter_test/flutter_test.dart'; import 'package:posthog_flutter/src/feature_flag_result.dart'; import 'package:posthog_flutter/src/logs/posthog_log_severity.dart'; +import 'package:posthog_flutter/src/feature_flags_loaded.dart'; import 'package:posthog_flutter/src/posthog_config.dart'; import 'package:posthog_flutter/src/posthog_event.dart'; import 'package:posthog_flutter/src/posthog_flutter_io.dart'; @@ -162,7 +163,7 @@ void main() { 'setup initializes method call handler and registers callback if provided', () async { bool callbackInvoked = false; - void testCallback() { + void testCallback(PostHogFeatureFlagsLoaded _) { callbackInvoked = true; } @@ -212,94 +213,45 @@ void main() { }, ); - test( - 'invokes callback when native sends onFeatureFlagsCallback event', - () async { - bool callbackInvoked = false; - - void testCallback() { - callbackInvoked = true; - } - - testConfig = PostHogConfig( - 'test_project_token', - onFeatureFlags: testCallback, - ); - await posthogFlutterIO.setup(testConfig); - - // Native sends empty map (iOS/Android behavior) - final mockNativeArgs = {}; - - await TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger - .handlePlatformMessage( - channel.name, - channel.codec.encodeMethodCall( - MethodCall('onFeatureFlagsCallback', mockNativeArgs), - ), - (ByteData? data) {}, - ); - - expect(callbackInvoked, isTrue); - }, - ); - - test( - 'invokes callback when native sends onFeatureFlagsCallback with empty map (mobile behavior)', - () async { - bool callbackInvoked = false; - - void testCallback() { - callbackInvoked = true; - } - - testConfig = PostHogConfig( - 'test_project_token', - onFeatureFlags: testCallback, - ); - await posthogFlutterIO.setup(testConfig); - - // Simulate mobile sending an empty map - final mockNativeArgs = {}; - - await TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger - .handlePlatformMessage( - channel.name, - channel.codec.encodeMethodCall( - MethodCall('onFeatureFlagsCallback', mockNativeArgs), - ), - (ByteData? data) {}, - ); - - expect(callbackInvoked, isTrue); - }, - ); - - test('invokes callback even with malformed native args', () async { - bool callbackInvoked = false; + test('passes the native flags to the callback', () async { + final received = []; + await posthogFlutterIO.setup( + PostHogConfig('test_project_token', onFeatureFlags: received.add)); - void testCallback() { - callbackInvoked = true; - } + await TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger + .handlePlatformMessage( + channel.name, + channel.codec.encodeMethodCall(const MethodCall( + 'onFeatureFlagsCallback', + { + 'variants': {'on': true, 'variant': 'test', 'off': false}, + 'errorsLoading': true, + }, + )), + (ByteData? data) {}, + ); - testConfig = - PostHogConfig('test_project_token', onFeatureFlags: testCallback); - await posthogFlutterIO.setup(testConfig); + expect(received.single.variants, {'on': true, 'variant': 'test'}); + expect(received.single.flags, ['on', 'variant']); + expect(received.single.errorsLoading, isTrue); + }); - // Simulate native sending malformed arguments - callback should still be invoked - final mockNativeArgsMalformed = { - 'flags': 123, // Invalid type, but callback is void so it doesn't matter - }; + test('passes empty flags to the callback for malformed native args', + () async { + final received = []; + await posthogFlutterIO.setup( + PostHogConfig('test_project_token', onFeatureFlags: received.add)); await TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger .handlePlatformMessage( channel.name, channel.codec.encodeMethodCall( - MethodCall('onFeatureFlagsCallback', mockNativeArgsMalformed), + const MethodCall('onFeatureFlagsCallback', {'variants': 123}), ), (ByteData? data) {}, ); - expect(callbackInvoked, isTrue); + expect(received.single.variants, isEmpty); }); test('does not invoke callback when no callback is registered', () async { @@ -452,6 +404,133 @@ void main() { }); }); + group('PosthogFlutterIO event options', () { + const options = { + 'process_person_profile': false, + 'custom_key': 'kept', + 'unset_key': null, + }; + const sent = {'process_person_profile': false, 'custom_key': 'kept'}; + + Map argsOf(String method) => Map.from( + log.singleWhere((c) => c.method == method).arguments as Map, + ); + + setUp(() async { + await posthogFlutterIO.setup(PostHogConfig('test_project_token')); + }); + + final callsByMethod = Function(PosthogFlutterIO)>{ + 'capture': (io) => io.capture(eventName: 'clicked', options: options), + 'screen': (io) => io.screen(screenName: 'Home', options: options), + 'captureException': (io) => + io.captureException(error: StateError('boom'), options: options), + 'identify': (io) => io.identify(userId: 'user-1', options: options), + 'setPersonProperties': (io) => io.setPersonProperties( + userPropertiesToSet: {'plan': 'pro'}, + options: options, + ), + 'alias': (io) => io.alias(alias: 'alias-1', options: options), + 'group': (io) => + io.group(groupType: 'company', groupKey: 'acme', options: options), + 'captureAi': (io) => + io.captureAi(eventName: r'$ai_generation', options: options), + }; + + for (final entry in callsByMethod.entries) { + test('${entry.key} sends the options without unset keys', () async { + await entry.value(posthogFlutterIO); + expect(argsOf(entry.key)['options'], sent); + }); + } + + test('calls without options send no options argument', () async { + await posthogFlutterIO.capture(eventName: 'clicked'); + await posthogFlutterIO.alias(alias: 'alias-1', options: {'k': null}); + expect(argsOf('capture'), isNot(contains('options'))); + expect(argsOf('alias'), isNot(contains('options'))); + }); + + test('captureAi sends the event and returns the native uuid', () async { + TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger + .setMockMethodCallHandler(channel, (call) async { + log.add(call); + return call.method == 'captureAi' ? 'uuid-1' : null; + }); + + final uuid = await posthogFlutterIO.captureAi( + eventName: r'$ai_generation', + properties: {r'$ai_model': 'gpt-4o'}, + userProperties: {'plan': 'pro'}, + ); + + expect(uuid, 'uuid-1'); + expect(argsOf('captureAi'), { + 'eventName': r'$ai_generation', + 'properties': {r'$ai_model': 'gpt-4o'}, + 'userProperties': {'plan': 'pro'}, + }); + expect(log.where((c) => c.method == 'capture'), isEmpty); + }); + + test('beforeSend sees and can change the options', () async { + final seen = ?>[]; + await posthogFlutterIO.setup(PostHogConfig( + 'test_project_token', + beforeSend: [ + (event) { + seen.add({...?event.options}); + event.options = {...?event.options, 'product_tour_id': 'tour-1'} + ..remove('custom_key'); + return event; + }, + ], + )); + + await posthogFlutterIO.captureAi( + eventName: r'$ai_span', options: options); + await posthogFlutterIO.screen(screenName: 'Home', options: options); + + expect(seen, [options, options]); + const changed = { + 'process_person_profile': false, + 'product_tour_id': 'tour-1', + }; + expect(argsOf('captureAi')['options'], changed); + expect(argsOf('screen')['options'], changed); + }); + + test('a screen renamed by beforeSend keeps its options', () async { + await posthogFlutterIO.setup(PostHogConfig( + 'test_project_token', + beforeSend: [ + (event) { + if (event.event == r'$screen') event.event = 'screen viewed'; + return event; + }, + ], + )); + + await posthogFlutterIO.screen(screenName: 'Home', options: options); + + expect(argsOf('capture')['eventName'], 'screen viewed'); + expect(argsOf('capture')['options'], sent); + }); + + test('captureAi dropped by beforeSend returns null', () async { + await posthogFlutterIO.setup(PostHogConfig( + 'test_project_token', + beforeSend: [(event) => null], + )); + + expect( + await posthogFlutterIO.captureAi(eventName: r'$ai_generation'), + isNull, + ); + expect(log.where((c) => c.method == 'captureAi'), isEmpty); + }); + }); + group('PosthogFlutterIO beforeSend callback', () { test( 'capture sends event unchanged when no beforeSend registered', diff --git a/posthog_flutter/test/posthog_flutter_platform_interface_fake.dart b/posthog_flutter/test/posthog_flutter_platform_interface_fake.dart index e4ad6a2b..94957cda 100644 --- a/posthog_flutter/test/posthog_flutter_platform_interface_fake.dart +++ b/posthog_flutter/test/posthog_flutter_platform_interface_fake.dart @@ -1,4 +1,5 @@ import 'package:posthog_flutter/src/feature_flag_result.dart'; +import 'package:posthog_flutter/src/feature_flags_loaded.dart'; import 'package:posthog_flutter/src/logs/posthog_log_severity.dart'; import 'package:posthog_flutter/src/posthog_config.dart'; import 'package:posthog_flutter/src/posthog_flutter_platform_interface.dart'; @@ -8,11 +9,13 @@ class CapturedExceptionCall { final Object error; final StackTrace? stackTrace; final Map? properties; + final Map? options; CapturedExceptionCall({ required this.error, this.stackTrace, this.properties, + this.options, }); } @@ -128,8 +131,9 @@ class PosthogFlutterPlatformFake extends PosthogFlutterPlatformInterface { Future stopSessionRecording() async {} @override - Future reloadFeatureFlags() async { + Future reloadFeatureFlags() async { reloadFeatureFlagsCount++; + return PostHogFeatureFlagsLoaded(variants: const {}, errorsLoading: false); } @override @@ -163,12 +167,71 @@ class PosthogFlutterPlatformFake extends PosthogFlutterPlatformInterface { // Tracking for captureLog calls (after Dart-side beforeSend has run) final List capturedLogs = []; + /// The options each event call received, as (method, options). + final List<(String, Map?)> optionsCalls = []; + + /// Returned by [captureAi]. + String? captureAiResult; + + @override + Future capture({ + required String eventName, + Map? properties, + Map? userProperties, + Map? userPropertiesSetOnce, + Map? options, + }) async { + optionsCalls.add(('capture', options)); + } + + @override + Future captureAi({ + required String eventName, + Map? properties, + Map? userProperties, + Map? userPropertiesSetOnce, + Map? options, + }) async { + optionsCalls.add(('captureAi', options)); + return captureAiResult; + } + + @override + Future identify({ + required String userId, + Map? userProperties, + Map? userPropertiesSetOnce, + Map? options, + }) async { + optionsCalls.add(('identify', options)); + } + + @override + Future alias({ + required String alias, + Map? options, + }) async { + optionsCalls.add(('alias', options)); + } + + @override + Future group({ + required String groupType, + required String groupKey, + Map? groupProperties, + Map? options, + }) async { + optionsCalls.add(('group', options)); + } + @override Future screen({ required String screenName, Map? properties, + Map? options, }) async { this.screenName = screenName; + optionsCalls.add(('screen', options)); } @override @@ -205,12 +268,14 @@ class PosthogFlutterPlatformFake extends PosthogFlutterPlatformInterface { required Object error, StackTrace? stackTrace, Map? properties, + Map? options, }) async { capturedExceptions.add( CapturedExceptionCall( error: error, stackTrace: stackTrace, properties: properties, + options: options, ), ); } @@ -244,10 +309,12 @@ class PosthogFlutterPlatformFake extends PosthogFlutterPlatformInterface { Future setPersonProperties({ Map? userPropertiesToSet, Map? userPropertiesToSetOnce, + Map? options, }) async { setPersonPropertiesCalls.add({ 'userPropertiesToSet': userPropertiesToSet, 'userPropertiesToSetOnce': userPropertiesToSetOnce, + if (options != null) 'options': options, }); } diff --git a/posthog_flutter/test/posthog_flutter_web_handler_test.dart b/posthog_flutter/test/posthog_flutter_web_handler_test.dart index 35ab74c0..97c48b9f 100644 --- a/posthog_flutter/test/posthog_flutter_web_handler_test.dart +++ b/posthog_flutter/test/posthog_flutter_web_handler_test.dart @@ -80,6 +80,152 @@ void main() { }); }); + group('handleWebMethodCall reloadFeatureFlags', () { + late JSFunction? listener; + late int reloads; + late int unsubscribes; + + /// Installs a fake posthog-js whose reload answers with [answer], if any. + void installFake({ + Map config = const {}, + ({Map variants, bool errorsLoading})? answer, + Duration answerAfter = Duration.zero, + String? asyncStatus, + }) { + listener = null; + reloads = 0; + unsubscribes = 0; + var current = {'cached': true}.jsify()!; + final featureFlags = JSObject() + ..setProperty('getFlagVariants'.toJS, (() => current).toJS); + if (asyncStatus != null) { + featureFlags.setProperty( + 'reloadFeatureFlagsAsync'.toJS, + (() => Future(() { + current = {'fresh': 'v2'}.jsify()!; + return {'status': asyncStatus}.jsify(); + }).toJS).toJS, + ); + } + final fake = JSObject() + ..setProperty('featureFlags'.toJS, featureFlags) + ..setProperty('config'.toJS, config.jsify()) + ..setProperty( + 'onFeatureFlags'.toJS, + ((JSFunction callback) { + listener = callback; + callback.callAsFunction(null, [].jsify(), current); + return (() => unsubscribes++).toJS; + }).toJS, + ) + ..setProperty( + 'reloadFeatureFlags'.toJS, + (() { + reloads++; + if (answer == null) return; + Future.delayed( + answerAfter, + () => listener?.callAsFunction( + null, + answer.variants.keys.toList().jsify(), + answer.variants.jsify(), + {'errorsLoading': answer.errorsLoading}.jsify(), + )); + }).toJS, + ); + globalContext.setProperty('posthog'.toJS, fake); + } + + test('completes with the flags the reload delivers, not the replayed ones', + () async { + installFake(answer: (variants: {'fresh': 'v2'}, errorsLoading: true)); + + final result = + await handleWebMethodCall(const MethodCall('reloadFeatureFlags')) + as Map; + + expect(result, { + 'variants': {'fresh': 'v2'}, + 'errorsLoading': true, + }); + expect(unsubscribes, 1); + }); + + test('awaits reloadFeatureFlagsAsync when posthog-js has it', () async { + installFake(asyncStatus: 'loaded'); + + final result = + await handleWebMethodCall(const MethodCall('reloadFeatureFlags')) + as Map; + + expect(result, { + 'variants': {'fresh': 'v2'}, + 'errorsLoading': false, + }); + expect(reloads, 0); + }); + + test('reports an error when reloadFeatureFlagsAsync skips the request', + () async { + installFake(asyncStatus: 'skipped'); + + final result = + await handleWebMethodCall(const MethodCall('reloadFeatureFlags')) + as Map; + + expect(result['errorsLoading'], isTrue); + }); + + test('completes right away with an error when flags are disabled', + () async { + installFake(config: {'advanced_disable_feature_flags': true}); + + final result = + await handleWebMethodCall(const MethodCall('reloadFeatureFlags')) + as Map; + + expect(result, { + 'variants': {'cached': true}, + 'errorsLoading': true, + }); + expect(reloads, 0); + }); + + test('waits for a reload that posthog-js retries after a timeout', + () async { + // Past twice the request timeout, but within one retry after 500 ms. + installFake( + config: {'feature_flag_request_timeout_ms': 20}, + answer: (variants: {'fresh': 'v2'}, errorsLoading: false), + answerAfter: const Duration(milliseconds: 300), + ); + + final result = + await handleWebMethodCall(const MethodCall('reloadFeatureFlags')) + as Map; + + expect(result, { + 'variants': {'fresh': 'v2'}, + 'errorsLoading': false, + }); + }); + + test('completes with an error when posthog-js never calls back', () async { + installFake(config: {'feature_flag_request_timeout_ms': 5}); + + final result = + await handleWebMethodCall(const MethodCall('reloadFeatureFlags')) + as Map; + + expect(result, { + 'variants': {'cached': true}, + 'errorsLoading': true, + }); + expect(reloads, 1); + expect(unsubscribes, 1); + }); + }); + group('handleWebMethodCall addExceptionStep', () { String? capturedMessage; JSAny? capturedProperties; diff --git a/posthog_flutter/test/posthog_test.dart b/posthog_flutter/test/posthog_test.dart index 4ddb2fa8..fc89aa9e 100644 --- a/posthog_flutter/test/posthog_test.dart +++ b/posthog_flutter/test/posthog_test.dart @@ -27,7 +27,7 @@ void main() { test( 'setup passes config and onFeatureFlags callback to platform interface', () async { - void testCallback() {} + void testCallback(PostHogFeatureFlagsLoaded _) {} final config = PostHogConfig( 'test_project_token', @@ -214,6 +214,50 @@ void main() { ); }); + group('Posthog event options', () { + late PosthogFlutterPlatformFake fake; + const options = {'process_person_profile': false}; + + setUp(() async { + fake = PosthogFlutterPlatformFake(); + PosthogFlutterPlatformInterface.instance = fake; + await Posthog().close(); + }); + + test('each event method passes its options to the platform', () async { + final posthog = Posthog(); + await posthog.capture(eventName: 'clicked', options: options); + await posthog.screen(screenName: 'Home', options: options); + await posthog.identify(userId: 'user-1', options: options); + await posthog.alias(alias: 'alias-1', options: options); + await posthog.group( + groupType: 'company', groupKey: 'acme', options: options); + await posthog.captureAi(eventName: r'$ai_span', options: options); + await posthog.captureException( + error: StateError('boom'), options: options); + await posthog.setPersonProperties( + userPropertiesToSet: {'plan': 'pro'}, + options: options, + ); + + expect(fake.optionsCalls, [ + ('capture', options), + ('screen', options), + ('identify', options), + ('alias', options), + ('group', options), + ('captureAi', options), + ]); + expect(fake.capturedExceptions.single.options, options); + expect(fake.setPersonPropertiesCalls.single['options'], options); + }); + + test('captureAi returns the platform result', () async { + fake.captureAiResult = 'uuid-1'; + expect(await Posthog().captureAi(eventName: r'$ai_trace'), 'uuid-1'); + }); + }); + group('PostHogConfig', () { test('toMap forwards evaluationContexts only when set', () { final config = PostHogConfig('test_project_token'); diff --git a/posthog_flutter/test/web_before_send_test.dart b/posthog_flutter/test/web_before_send_test.dart index ad57000a..f3a2cc3e 100644 --- a/posthog_flutter/test/web_before_send_test.dart +++ b/posthog_flutter/test/web_before_send_test.dart @@ -103,4 +103,45 @@ void main() { expect(captures, isEmpty); }); + + test('event options are sent as their legacy properties on web', () async { + final web = PosthogFlutterWeb(); + await web.setup(PostHogConfig('test_token', beforeSend: [ + (event) { + event.options = {...?event.options, 'cookieless_mode': true}; + return event; + }, + ])); + const options = { + 'disable_skew_correction': true, + 'product_tour_id': 'tour-1', + 'unknown_option': 'dropped', + }; + + await web.capture( + eventName: 'tour step', + properties: {r'$product_tour_id': 'from-property'}, + options: options, + ); + await web.screen(screenName: 'Home', options: options); + await web.captureException(error: StateError('boom'), options: options); + + expect(captures.map((c) => c['event']), + ['tour step', r'$screen', r'$exception']); + for (final capture in captures) { + final properties = capture['properties'] as Map; + expect(properties[r'$ignore_sent_at'], isTrue); + expect(properties[r'$product_tour_id'], 'tour-1'); + expect(properties[r'$cookieless_mode'], isTrue); + expect(properties, isNot(contains('unknown_option'))); + } + }); + + test('captureAi sends nothing on web and returns null', () async { + final web = PosthogFlutterWeb(); + await web.setup(PostHogConfig('test_token')); + + expect(await web.captureAi(eventName: r'$ai_generation'), isNull); + expect(captures, isEmpty); + }); } diff --git a/pubspec.lock b/pubspec.lock index 97a86f5c..1bd0cbe4 100644 --- a/pubspec.lock +++ b/pubspec.lock @@ -246,10 +246,10 @@ packages: dependency: transitive description: name: google_maps_flutter - sha256: fc084ddabc22645bebbe9df51baeec4949e5d14fc37492dce80501863425a82e + sha256: "392492775b6928b7419bd1d04c7562dab73a543e71078088a40ae7324acd3641" url: "https://pub.dev" source: hosted - version: "2.19.0" + version: "2.18.1" google_maps_flutter_android: dependency: transitive description: @@ -347,10 +347,10 @@ packages: dependency: transitive description: name: matcher - sha256: "31bd099b47c10cd1aeb55146a2d46ce0277630ecef3f7dae54ad7873f36696cd" + sha256: dc0b7dc7651697ea4ff3e69ef44b0407ea32c487a39fff6a4004fa585e901861 url: "https://pub.dev" source: hosted - version: "0.12.20" + version: "0.12.19" material_color_utilities: dependency: transitive description: @@ -363,10 +363,10 @@ packages: dependency: transitive description: name: meta - sha256: "307249ce4ff29d58a18e97f6345f539382eb9c9c29ecda628900f31de0443dd9" + sha256: "1741988757a65eb6b36abe716829688cf01910bbf91c34354ff7ec1c3de2b349" url: "https://pub.dev" source: hosted - version: "1.19.0" + version: "1.18.0" package_config: dependency: transitive description: @@ -520,10 +520,10 @@ packages: dependency: transitive description: name: stack_trace - sha256: "277654b3034d17ac6f9f1cb5595db011b1d5d41e8806866db28e0abaa101c490" + sha256: "8b27215b45d22309b5cddda1aa2b19bdfec9df0e765f2de506401c071d38d1b1" url: "https://pub.dev" source: hosted - version: "1.12.2" + version: "1.12.1" stream_channel: dependency: transitive description: @@ -576,10 +576,10 @@ packages: dependency: transitive description: name: test_api - sha256: "2a122cbe059f8b610d3a5415f42e255b6c17b1f21eee1d960f31080237fb4f11" + sha256: "949a932224383300f01be9221c39180316445ecb8e7547f70a41a35bf421fb9e" url: "https://pub.dev" source: hosted - version: "0.7.12" + version: "0.7.11" tuple: dependency: transitive description: @@ -608,10 +608,10 @@ packages: dependency: transitive description: name: vector_math - sha256: f36f9f3be64c6198714492bb455c11056e33e2f85d9a0b676a48301e44fdcf47 + sha256: d530bd74fea330e6e364cda7a85019c434070188383e1cd8d9777ee586914c5b url: "https://pub.dev" source: hosted - version: "2.4.2" + version: "2.2.0" vm_service: dependency: transitive description: @@ -701,5 +701,5 @@ packages: source: hosted version: "3.1.3" sdks: - dart: ">=3.13.0 <4.0.0" - flutter: ">=3.47.0" + dart: ">=3.12.0 <4.0.0" + flutter: ">=3.44.0" diff --git a/sdk_compliance_adapter/docker-compose.yml b/sdk_compliance_adapter/docker-compose.yml index dbcadd1f..cc621dc5 100644 --- a/sdk_compliance_adapter/docker-compose.yml +++ b/sdk_compliance_adapter/docker-compose.yml @@ -9,7 +9,7 @@ services: - test-network test-harness: - image: ghcr.io/posthog/sdk-test-harness:0.9.0 + image: ghcr.io/posthog/sdk-test-harness:1.26.0 command: [ "run", diff --git a/sdk_compliance_adapter/lib/adapter_server.dart b/sdk_compliance_adapter/lib/adapter_server.dart index f0682d96..43858465 100644 --- a/sdk_compliance_adapter/lib/adapter_server.dart +++ b/sdk_compliance_adapter/lib/adapter_server.dart @@ -287,6 +287,7 @@ class _CompliancePlatform extends PosthogFlutterPlatformInterface { Map? properties, Map? userProperties, Map? userPropertiesSetOnce, + Map? options, }) async { if (!isInitialized) { throw StateError('SDK not initialized'); From 33171f6eec2ea9aac4515f8f62500a0c2de18f22 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Thu, 29 Oct 2026 17:14:30 -0400 Subject: [PATCH 07/28] fix(desktop): recheck person processing after beforeSend adds person properties An anonymous event that a callback gave $set kept the SDK's process_person_profile: false, so PostHog ignored the person update. Co-Authored-By: Claude Opus 5.5 --- .../lib/src/posthog_flutter_desktop.dart | 21 ++++++++++++------- .../test/posthog_flutter_desktop_test.dart | 16 ++++++++++++++ 2 files changed, 29 insertions(+), 8 deletions(-) diff --git a/posthog_flutter/lib/src/posthog_flutter_desktop.dart b/posthog_flutter/lib/src/posthog_flutter_desktop.dart index f7e4823a..648e3850 100644 --- a/posthog_flutter/lib/src/posthog_flutter_desktop.dart +++ b/posthog_flutter/lib/src/posthog_flutter_desktop.dart @@ -741,11 +741,12 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { Map? userPropertiesSetOnce, Map? options, }) { + final callerOptions = cleanEventOptions(options); final prepared = client.prepareEvent( eventName, properties: _mergeUserProps(properties, userProperties, userPropertiesSetOnce), - options: cleanEventOptions(options), + options: callerOptions, ); if (prepared == null) return null; final eventProperties = _nonNull(prepared.properties)!; @@ -771,7 +772,8 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { ), timestamp: prepared.timestamp, implicitPersonProcessing: - preparedOptions?['process_person_profile'] == null, + callerOptions?['process_person_profile'] == null, + sdkPersonProcessing: preparedOptions?['process_person_profile'], ); } @@ -838,11 +840,12 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { // Options are sent as they are, unknown keys included. An option wins // over its legacy property on the event. Map? options = cleanEventOptions(event.options); - // Person properties the callbacks removed no longer ask for person - // processing, unless a callback set the option itself. + // Person properties the callbacks added or removed decide person + // processing again, unless a callback changed the SDK's option. if (prepared.implicitPersonProcessing && - options?['process_person_profile'] == null) { - options = client.personProcessingOptions(options, properties); + options?['process_person_profile'] == prepared.sdkPersonProcessing) { + options = client.personProcessingOptions( + {...?options}..remove('process_person_profile'), properties); } return client.capturePrepared( event.event, @@ -906,10 +909,12 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { } } -/// An event built for the beforeSend callbacks, with the time it happened -/// and whether its person processing was left to its properties. +/// An event built for the beforeSend callbacks, with the time it happened, +/// whether its person processing was left to its properties, and the +/// `process_person_profile` option the SDK gave it. typedef _PreparedEvent = ({ PostHogEvent event, String timestamp, bool implicitPersonProcessing, + Object? sdkPersonProcessing, }); diff --git a/posthog_flutter/test/posthog_flutter_desktop_test.dart b/posthog_flutter/test/posthog_flutter_desktop_test.dart index 6609992c..277ac2c5 100644 --- a/posthog_flutter/test/posthog_flutter_desktop_test.dart +++ b/posthog_flutter/test/posthog_flutter_desktop_test.dart @@ -660,6 +660,22 @@ void main() { expect(_optionsOf(event)['process_person_profile'], isFalse); }); + test('person properties a callback adds turn on person processing', + () async { + final server = await LocalPostHogServer.start(); + final config = configFor(server) + ..beforeSend = [ + (event) => event..userProperties = {'email': 'user@example.com'}, + ]; + final platform = await setUpPlatform(config); + + await platform.capture(eventName: 'signed up'); + + final event = await server.waitForEvent('signed up'); + expect(_optionsOf(event), isNot(contains('process_person_profile'))); + expect(_propertiesOf(event)[r'$set'], {'email': 'user@example.com'}); + }); + test('a callback can turn person processing back on', () async { final server = await LocalPostHogServer.start(); final config = configFor(server) From daadc46ef9a6e3a030e352cbbd45cddd457aafbd Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Thu, 29 Oct 2026 17:14:30 -0400 Subject: [PATCH 08/28] fix(desktop): apply person state only once an event is queued An AI event dropped for its size still turned on person processing and fed its person properties to /flags. Co-Authored-By: Claude Opus 5.5 --- .../lib/src/core/posthog_core.dart | 9 ++++---- .../test/posthog_flutter_desktop_test.dart | 21 +++++++++++++++++++ 2 files changed, 26 insertions(+), 4 deletions(-) diff --git a/posthog_flutter/lib/src/core/posthog_core.dart b/posthog_flutter/lib/src/core/posthog_core.dart index 9a0b2bf1..04f31595 100644 --- a/posthog_flutter/lib/src/core/posthog_core.dart +++ b/posthog_flutter/lib/src/core/posthog_core.dart @@ -502,16 +502,17 @@ abstract class PostHogCore extends PostHogCoreStateless { bool ai = false, }) { final (:properties, :options, :timestamp) = prepared; + final uuid = captureStateless(getDistinctId(), event, + properties: properties, options: options, timestamp: timestamp, ai: ai); + if (uuid == null) return null; // Taken from the event as queued, after the beforeSend callbacks, so a - // value they removed or an event they dropped neither reaches /flags - // nor turns on person processing for later events. + // value they removed or an event they or the size limit dropped neither + // reaches /flags nor turns on person processing for later events. if (_requestsPersonProcessing(properties)) _enablePersonProcessing(); _setPersonPropertiesForFlagsIfNeeded( _asPropertyMap(properties[r'$set']), _asPropertyMap(properties[r'$set_once']), ); - final uuid = captureStateless(getDistinctId(), event, - properties: properties, options: options, timestamp: timestamp, ai: ai); // PostHog drops an AI event that is not an `$ai_*` event, so it never // updates the person. if (!ai && (event == r'$set' || event == r'$identify')) { diff --git a/posthog_flutter/test/posthog_flutter_desktop_test.dart b/posthog_flutter/test/posthog_flutter_desktop_test.dart index 277ac2c5..22c757da 100644 --- a/posthog_flutter/test/posthog_flutter_desktop_test.dart +++ b/posthog_flutter/test/posthog_flutter_desktop_test.dart @@ -1372,6 +1372,27 @@ void main() { expect(uuid, isNull); }); + test('an oversized event does not turn on person processing', () async { + final server = await LocalPostHogServer.start(); + final platform = await setUpPlatform(configFor(server) + ..preloadFeatureFlags = false + ..captureAiMaxEventBytes = 4096); + + final uuid = await platform.captureAi( + eventName: r'$ai_generation', + properties: {r'$ai_input': 'x' * 5000}, + userProperties: {'email': 'user@example.com'}, + ); + await platform.capture(eventName: 'after drop'); + await platform.reloadFeatureFlags(); + + expect(uuid, isNull); + final event = await server.waitForEvent('after drop'); + expect(_optionsOf(event)['process_person_profile'], isFalse); + expect(server.flagsRequests.single.body['person_properties'], + isNot(contains('email'))); + }); + test('returns null while opted out', () async { final server = await LocalPostHogServer.start(); final platform = await setUpPlatform(configFor(server)); From f933404f65802a72e20f0c07a733a9cb1a32d8fb Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Fri, 30 Oct 2026 12:27:44 -0400 Subject: [PATCH 09/28] docs: captureAiMaxEventBytes limits the whole event on Android too posthog-android applies a set value to the whole serialized event, as iOS and macOS do (captureAiMaxStoredEventBytes on feat/v4-capture-v1). Co-Authored-By: Claude Opus 5.5 --- posthog_flutter/lib/src/posthog_config.dart | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/posthog_flutter/lib/src/posthog_config.dart b/posthog_flutter/lib/src/posthog_config.dart index 0036c71e..bb51bb6a 100644 --- a/posthog_flutter/lib/src/posthog_config.dart +++ b/posthog_flutter/lib/src/posthog_config.dart @@ -237,8 +237,7 @@ class PostHogConfig { /// over 8 MiB, so a larger value, or a value of `0` or less, uses the /// default. By default the SDK drops a serialized event over 8 MiB plus /// 64 KiB for the rest of the event, measured before compression. A set - /// value limits the properties on Android, plus 64 KiB for the rest of the - /// event, and the whole serialized event on the other platforms. + /// value limits the whole serialized event. /// /// Not applied on web, where [Posthog.captureAi] sends nothing. /// From 34754a7a04feaa8fc696ebc384460b9d750f1135 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Fri, 30 Oct 2026 13:12:36 -0400 Subject: [PATCH 10/28] fix(desktop): log event names and sizes, not properties, in debug mode Co-Authored-By: Claude Opus 5.5 --- .../lib/src/core/file_storage.dart | 9 +++++---- .../lib/src/core/posthog_core_stateless.dart | 15 ++++++++++++--- .../test/core/posthog_core_test.dart | 19 +++++++++++++++++++ 3 files changed, 36 insertions(+), 7 deletions(-) diff --git a/posthog_flutter/lib/src/core/file_storage.dart b/posthog_flutter/lib/src/core/file_storage.dart index 754d6a7f..1a535081 100644 --- a/posthog_flutter/lib/src/core/file_storage.dart +++ b/posthog_flutter/lib/src/core/file_storage.dart @@ -378,7 +378,7 @@ class FileEventQueue { /// Adds [event] at the end of the queue. [json] is the event already /// encoded, and [bytes] its UTF-8 size, when the caller has them. - void add(Map event, {String? json, int? bytes}) { + int add(Map event, {String? json, int? bytes}) { // Loaded before the new file exists, which would otherwise be listed // on top of being added. final ids = _ids; @@ -391,11 +391,11 @@ class FileEventQueue { // Reported below when it is written. } } - ids.add(_track( - id, bytes ?? (encoded == null ? 0 : utf8.encode(encoded).length))); + final size = bytes ?? (encoded == null ? 0 : utf8.encode(encoded).length); + ids.add(_track(id, size)); if (_directory.isEmpty) { _unwritten[id] = event; - return; + return size; } try { _writeAtomically(File(_pathOf(id)), encoded ?? jsonEncode(event)); @@ -406,6 +406,7 @@ class FileEventQueue { 'is sent:', e); } + return size; } /// Returns up to [count] events from the front of the queue, oldest diff --git a/posthog_flutter/lib/src/core/posthog_core_stateless.dart b/posthog_flutter/lib/src/core/posthog_core_stateless.dart index 2cd81cb7..26827de9 100644 --- a/posthog_flutter/lib/src/core/posthog_core_stateless.dart +++ b/posthog_flutter/lib/src/core/posthog_core_stateless.dart @@ -291,8 +291,13 @@ abstract class PostHogCoreStateless { _removeDebugCallback = null; if (enabled) { - _removeDebugCallback = - events.onAny((event, payload) => logger.info(event, payload)); + _removeDebugCallback = events.onAny((event, payload) { + // Logged without their properties where they happen, see [_enqueue] + // and [_sendBatch]: properties can hold prompts and media. + if (event != 'capture' && event != 'flush') { + logger.info(event, payload); + } + }); } } @@ -540,7 +545,9 @@ abstract class PostHogCoreStateless { queue.removeOldest(overflow); logger.warn('Queue is full, the oldest event is dropped.'); } - queue.add(prepared, json: json, bytes: bytes); + final queuedBytes = queue.add(prepared, json: json, bytes: bytes); + logger.info('$type ${message['event']} queued for ${lane.path}, ' + '$queuedBytes bytes.'); final maxQueueBytes = lane.maxQueueBytes; if (maxQueueBytes != null && queue.removeOldestOver(maxQueueBytes) > 0) { logger.warn('Queue is over $maxQueueBytes bytes, the oldest events are ' @@ -720,6 +727,8 @@ abstract class PostHogCoreStateless { // flight, e.g. its oldest events dropped to make room. queue.remove([for (final queued in delivered) queued.id]); if (delivered.isNotEmpty) { + logger.info('flush ${delivered.length} events sent to ${lane.path}: ' + '${delivered.map((queued) => queued.event['event']).join(', ')}.'); events.emit('flush', [for (final queued in delivered) queued.event]); } if (delivered.length == batch.length) { diff --git a/posthog_flutter/test/core/posthog_core_test.dart b/posthog_flutter/test/core/posthog_core_test.dart index 51b5f47c..0e4490f4 100644 --- a/posthog_flutter/test/core/posthog_core_test.dart +++ b/posthog_flutter/test/core/posthog_core_test.dart @@ -1,5 +1,6 @@ import 'dart:convert'; +import 'package:flutter/foundation.dart' show debugPrint; import 'package:flutter_test/flutter_test.dart'; import 'package:posthog_flutter/src/core/file_storage.dart'; import 'package:posthog_flutter/src/core/persistence.dart'; @@ -323,6 +324,24 @@ void main() { expect(lines, contains(allOf(contains('capture'), contains('sign_in')))); expect(printedLines(() => client.capture('sign_out')), isEmpty); }); + + test('logs events without their properties', () async { + final client = testClient(server); + + client.debug(true); + final lines = []; + final previous = debugPrint; + debugPrint = (message, {wrapWidth}) => lines.add(message ?? ''); + try { + client.capture('sign_in', properties: {'prompt': 'secret'}); + await client.flush(); + } finally { + debugPrint = previous; + } + + expect(lines, contains(allOf(contains('flush'), contains('sign_in')))); + expect(lines.join(), isNot(contains('secret'))); + }); }); group('Super properties', () { From 4e7be56339b8590afd9c83103e455f89d8f50fc4 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Fri, 30 Oct 2026 13:12:36 -0400 Subject: [PATCH 11/28] fix(desktop): send the screen name beforeSend leaves Co-Authored-By: Claude Opus 5.5 --- .../lib/src/posthog_flutter_desktop.dart | 17 +++++--------- .../test/posthog_flutter_desktop_test.dart | 23 +++++++++++++++---- 2 files changed, 25 insertions(+), 15 deletions(-) diff --git a/posthog_flutter/lib/src/posthog_flutter_desktop.dart b/posthog_flutter/lib/src/posthog_flutter_desktop.dart index 648e3850..71e4b6a4 100644 --- a/posthog_flutter/lib/src/posthog_flutter_desktop.dart +++ b/posthog_flutter/lib/src/posthog_flutter_desktop.dart @@ -369,23 +369,18 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { return; } - // Re-added after the callbacks, so one that rebuilds the property map - // cannot drop the screen name. final finalScreenName = - processed.properties?[PostHogPropertyName.screenName] as String? ?? - screenName; - if (finalScreenName.isEmpty) { + processed.properties?[PostHogPropertyName.screenName]; + if (finalScreenName == '') { printIfDebug('[PostHog] Screen event dropped: empty screen name'); return; } // Later events that set no `$screen_name` of their own carry this one. - current.registerForSession( - {PostHogPropertyName.screenName: finalScreenName}); - processed.properties = { - ...?processed.properties, - PostHogPropertyName.screenName: finalScreenName, - }; + if (finalScreenName is String) { + current.registerForSession( + {PostHogPropertyName.screenName: finalScreenName}); + } _captureProcessed(current, processed, exceptionSteps, prepared); }); diff --git a/posthog_flutter/test/posthog_flutter_desktop_test.dart b/posthog_flutter/test/posthog_flutter_desktop_test.dart index 22c757da..df1ad83b 100644 --- a/posthog_flutter/test/posthog_flutter_desktop_test.dart +++ b/posthog_flutter/test/posthog_flutter_desktop_test.dart @@ -430,7 +430,7 @@ void main() { expect(_propertiesOf(event)[r'$set'], {'source': 'screen hook'}); }); - test('keeps the screen name when a callback rebuilds the properties', + test('a callback that removes the screen name keeps it off the events', () async { final server = await LocalPostHogServer.start(); final config = configFor(server) @@ -443,13 +443,28 @@ void main() { final platform = await setUpPlatform(config); await platform.screen(screenName: 'Home Screen'); + await platform.capture(eventName: 'after screen'); final event = await server.waitForEvent(r'$screen'); final properties = _propertiesOf(event); - expect(properties[r'$screen_name'], 'Home Screen', - reason: 'the screen name is re-added after the callbacks, so one ' - 'dropping the key must not lose it'); + expect(properties, isNot(contains(r'$screen_name'))); expect(properties['scrubbed'], isTrue); + final after = await server.waitForEvent('after screen'); + expect(_propertiesOf(after), isNot(contains(r'$screen_name'))); + }); + + test('sends a non-string screen name a callback leaves', () async { + final server = await LocalPostHogServer.start(); + final config = configFor(server) + ..beforeSend = [ + (event) => event..properties?[r'$screen_name'] = 42, + ]; + final platform = await setUpPlatform(config); + + await platform.screen(screenName: 'Home Screen'); + + final event = await server.waitForEvent(r'$screen'); + expect(_propertiesOf(event)[r'$screen_name'], 42); }); test('later events carry the last screen name', () async { From bc39ec019cc11e216c1a98136a439498d08471ed Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Fri, 30 Oct 2026 13:12:37 -0400 Subject: [PATCH 12/28] docs(desktop): registered and event properties override platform context Co-Authored-By: Claude Opus 5.5 --- posthog_flutter/lib/src/core/posthog_core.dart | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/posthog_flutter/lib/src/core/posthog_core.dart b/posthog_flutter/lib/src/core/posthog_core.dart index 04f31595..903dae8a 100644 --- a/posthog_flutter/lib/src/core/posthog_core.dart +++ b/posthog_flutter/lib/src/core/posthog_core.dart @@ -133,9 +133,8 @@ abstract class PostHogCore extends PostHogCoreStateless { bool isMinimalFlagCalledEventsEnabled() => _getStoredFlagDetails()?.minimalFlagCalledEvents == true; - /// Platform context (OS, app, device) attached to every event. It wins - /// over registered and event properties of the same name: it describes - /// the environment the SDK runs in. + /// Platform context (OS, app, device) attached to every event. Registered + /// and event properties of the same name override it. @protected Map getContextProperties(); From 2dee3509044bfec858e861de6d41a6fd43fb20c6 Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Thu, 29 Oct 2026 17:03:49 -0400 Subject: [PATCH 13/28] chore: stop passing RRStyle to replay screenshot frames (#684) posthog-android 4.0 drops RRStyle and the wireframe tree fields from the internal RRWireframe; screenshot frames don't need a style. Co-authored-by: Claude Opus 5.5 --- .../src/main/kotlin/com/posthog/flutter/SnapshotSender.kt | 2 -- 1 file changed, 2 deletions(-) diff --git a/posthog_flutter/android/src/main/kotlin/com/posthog/flutter/SnapshotSender.kt b/posthog_flutter/android/src/main/kotlin/com/posthog/flutter/SnapshotSender.kt index 9356a556..b10d3561 100644 --- a/posthog_flutter/android/src/main/kotlin/com/posthog/flutter/SnapshotSender.kt +++ b/posthog_flutter/android/src/main/kotlin/com/posthog/flutter/SnapshotSender.kt @@ -7,7 +7,6 @@ import com.posthog.android.internal.base64 import com.posthog.internal.replay.RREvent import com.posthog.internal.replay.RRFullSnapshotEvent import com.posthog.internal.replay.RRMetaEvent -import com.posthog.internal.replay.RRStyle import com.posthog.internal.replay.RRWireframe import com.posthog.internal.replay.capture @@ -62,7 +61,6 @@ class SnapshotSender( height = height ?: bitmap.height, type = "screenshot", base64 = bitmap.base64(quality = quality), - style = RRStyle(), ) return RRFullSnapshotEvent( listOf(wireframe), From 155c048afc36e4942afa901cdd7ffe038e774b9a Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Fri, 30 Oct 2026 18:34:00 -0400 Subject: [PATCH 14/28] chore!: adopt posthog-ios 4.0 and posthog-android 4.0 (#649) * chore!: adopt posthog-ios 4.0 - Require posthog-ios 4.x. - Adapt to the reloadFeatureFlags(_:) callback that now passes a PostHogFeatureFlagsLoaded (PostHog/posthog-ios#913). - Note the payload decoding changes from PostHog/posthog-ios#903. Co-Authored-By: Claude Opus 5.5 (1M context) * docs(changeset): note posthog-ios 4.0 drops lifecycle version and build PostHog/posthog-ios#905 removes the legacy version/build properties from lifecycle events in 4.0, so Flutter iOS and macOS apps stop sending them. Co-Authored-By: Claude Opus 5.5 (1M context) * chore(ios): drive onFeatureFlags from the posthog-ios onFeatureFlags listener posthog-ios 4.0 removes the didReceiveFeatureFlags notification. * chore!: adopt posthog-android 4.0 (#663) * chore!: adopt posthog-android 4.0 * chore!: pass the loaded flags to onFeatureFlags and reloadFeatureFlags (#664) * chore!: pass the loaded flags to onFeatureFlags and reloadFeatureFlags onFeatureFlags and reloadFeatureFlags now carry a PostHogFeatureFlagsLoaded with the enabled flags, their values and whether loading failed, matching posthog-ios 4.0 and posthog-android 4.0. On web, reloadFeatureFlags completes right away with the flags loaded so far, because posthog-js doesn't report when a reload finishes. * fix: complete the web reloadFeatureFlags with the reloaded flags Wait for the next posthog-js onFeatureFlags call instead of returning the flags already loaded, so a failed reload reports errorsLoading. Complete right away when flags are disabled, and after twice the flags request timeout when posthog-js skips the request without calling back. * chore: use PostHogFeatureFlagsCallback from posthog-android 4.0 * chore: fix ktlint function-signature * fix: await posthog-js reloadFeatureFlagsAsync on web The next onFeatureFlags callback can carry a response from a request already in flight, so reloadFeatureFlags() could complete with flags from before the reload. posthog-js 1.438.2+ settles reloadFeatureFlagsAsync() after this reload's own request; use it when present and keep the callback path for older posthog-js. * docs: pass the loaded flags in the setup example * docs: drop best-effort web note from the person and group property methods * fix(web): wait for posthog-js flags retries before reporting a reload failure posthog-js retries a timed-out /flags request once by default, 500 ms later, inside the same reload. The older-JS deadline of twice the request timeout reported cached flags with errorsLoading set before a successful retry landed. * docs: note where onFeatureFlags and errorsLoading differ on Android and web * docs: describe the older posthog-js reload timeout as the full retry budget Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 * docs(changeset): fold the posthog-android 4.0 and flags-loaded entries into one changeset Co-Authored-By: Claude Opus 5.5 * chore: stop passing RRStyle to replay screenshot frames (#684) posthog-android 4.0 drops RRStyle and the wireframe tree fields from the internal RRWireframe; screenshot frames don't need a style. Co-authored-by: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 (1M context) --- .../test/posthog_flutter_desktop_test.dart | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/posthog_flutter/test/posthog_flutter_desktop_test.dart b/posthog_flutter/test/posthog_flutter_desktop_test.dart index df1ad83b..9870e849 100644 --- a/posthog_flutter/test/posthog_flutter_desktop_test.dart +++ b/posthog_flutter/test/posthog_flutter_desktop_test.dart @@ -2415,6 +2415,27 @@ void main() { expect(_propertiesOf(called)[r'$feature_flag'], 'variant-flag'); }); + test( + 'reloadFeatureFlags returns the loaded flags, and the last known ones when loading fails', + () async { + final server = await LocalPostHogServer.start(); + server.respond = (_) => PostHogResponse.json(_variantFlagResponse()); + final announced = []; + final platform = await setUpPlatform(configFor(server) + ..preloadFeatureFlags = false + ..onFeatureFlags = announced.add); + + final loaded = await platform.reloadFeatureFlags(); + expect(loaded.variants, {'variant-flag': 'test-variant'}); + expect(loaded.errorsLoading, isFalse); + + server.respond = (_) => const PostHogResponse(HttpStatus.badRequest); + final failed = await platform.reloadFeatureFlags(); + expect(failed.variants, {'variant-flag': 'test-variant'}); + expect(failed.errorsLoading, isTrue); + expect(announced.last.errorsLoading, isTrue); + }); + test('onFeatureFlags reports the flags cached by the previous launch', () async { final server = await LocalPostHogServer.start(); From f2859c4877496f6618468bfeb9d91da926bf6a21 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Fri, 30 Oct 2026 22:10:15 -0400 Subject: [PATCH 15/28] docs: fold capture v1 and native 4.0 release notes into the 6.0 docs --- .changeset/v6-capture-options-ai.md | 8 --- .changeset/v6-desktop-capture-ai.md | 8 --- .changeset/v6-desktop-capture-v1.md | 8 --- .changeset/v6-flags-loaded-result.md | 6 -- .changeset/v6-major-release.md | 19 ++++++ .changeset/v6-posthog-android-4.md | 5 -- .changeset/v6-posthog-ios-4.md | 8 --- posthog_flutter/MIGRATION.md | 86 +++++++++++++++++++++++----- 8 files changed, 90 insertions(+), 58 deletions(-) delete mode 100644 .changeset/v6-capture-options-ai.md delete mode 100644 .changeset/v6-desktop-capture-ai.md delete mode 100644 .changeset/v6-desktop-capture-v1.md delete mode 100644 .changeset/v6-flags-loaded-result.md delete mode 100644 .changeset/v6-posthog-android-4.md delete mode 100644 .changeset/v6-posthog-ios-4.md diff --git a/.changeset/v6-capture-options-ai.md b/.changeset/v6-capture-options-ai.md deleted file mode 100644 index dc5602c9..00000000 --- a/.changeset/v6-capture-options-ai.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -"posthog_flutter": minor ---- - -- Add an `options` parameter to `capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group` and `captureException`, and `PostHogEvent.options` for `beforeSend` callbacks. The known keys `process_person_profile`, `cookieless_mode`, `disable_skew_correction` and `product_tour_id` win over their legacy `$` properties. On iOS, macOS, Android, Windows and Linux other keys are sent as-is; on web the known keys are sent as their legacy `$` properties and other keys are dropped -- Add `captureAi` for AI observability events such as `$ai_generation`, sent to PostHog's AI endpoint on iOS, macOS, Android, Windows and Linux, returning the event's UUID, or `null` when the event isn't admitted (dropped by `beforeSend`, oversized, SDK disabled or opted out). On web `captureAi` is a no-op: it sends nothing and returns `null` -- Add `PostHogConfig.captureAiCompression`, `captureAiMaxQueueSize`, `captureAiTimeout` and `captureAiMaxEventBytes` for the `captureAi` queue and requests. Unset, they keep the SDK defaults. They have no effect on web -- On Windows and Linux, a `$process_person_profile` property or `process_person_profile` option passed with an event now applies to that event instead of being replaced by the SDK's value diff --git a/.changeset/v6-desktop-capture-ai.md b/.changeset/v6-desktop-capture-ai.md deleted file mode 100644 index 3795283f..00000000 --- a/.changeset/v6-desktop-capture-ai.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -"posthog_flutter": major ---- - -- **Breaking:** on Windows and Linux, an event's properties are now the ones the SDK sets (device and app context, `$lib`, feature flags, `$session_id`, `$is_identified`, the `$sdk_debug_*` keys), then registered properties, then the event's own, as in `posthog-ios` and `posthog-android` 4.0. A registered or event property with the same name as an SDK property now wins, for that event only. The Dart `beforeSend` callbacks run after that merge, so they see and can change every property and option the SDK adds, and the event is sent as they leave it, except `$lib` and `$lib_version`: PostHog always sets them from the SDK's `PostHog-Sdk-Info` header -- **Breaking:** on Windows and Linux, person processing is sent as the `process_person_profile: false` option only while it is off, instead of a `$process_person_profile` property on every event -- On Windows and Linux, `captureAi` queues AI events on disk apart from other events. The queue keeps up to `captureAiMaxQueueSize` events (100 by default) and 50 MiB, drops a serialized event over `captureAiMaxEventBytes` (8 MiB plus 64 KiB by default, measured before compression) and is sent like other events: same batching, retries and backoff, compressed with `captureAiCompression`, a request failing after `captureAiTimeout` (60 seconds by default) without progress -- On Windows and Linux, an event's timestamp is taken before the `beforeSend` callbacks run diff --git a/.changeset/v6-desktop-capture-v1.md b/.changeset/v6-desktop-capture-v1.md deleted file mode 100644 index 00cf869e..00000000 --- a/.changeset/v6-desktop-capture-v1.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -"posthog_flutter": major ---- - -- **Breaking:** on iOS, macOS, Android, Windows and Linux, events now go to capture v1 (`/i/v1/analytics/events`) instead of `/batch/`: iOS and macOS through `posthog-ios` 4.x, Android through `posthog-android` 4.x, and Windows and Linux in the Dart client. If you send events through your own reverse proxy, update it before you upgrade: forward `/i/v1/analytics/events` and `/i/v1/ai/events`, pass `Authorization` (the project token, sent as `Bearer `), every `PostHog-*` header, `Content-Type`, `Content-Encoding` and `User-Agent` through unchanged, and accept request bodies up to 20 MB. PostHog's managed reverse proxy already does this. See the [iOS](https://github.com/PostHog/posthog-ios/blob/main/docs/migration-3.x-to-4.0.md#hosts-without-capture-v1) and [Android](https://github.com/PostHog/posthog-android/blob/main/docs/migration-3.x-to-4.0.md#hosts-without-capture-v1) migration guides -- **Breaking:** on Windows and Linux, a reverse proxy or self-hosted instance must serve the new path: a 404 is retried, the events stay queued, and the SDK prints a warning once, also without `debug`. Events queued before the upgrade are sent through the new endpoint -- **Breaking:** on Windows and Linux, a redirect drops the batch instead of retrying it (only same-origin 307/308 redirects are followed, while a 404 or 429 is retried), and a `Retry-After` wait is capped at 30 seconds -- On Windows and Linux, a failed batch, or one whose events the server asks to retry, is no longer resent within the same flush: the queue backs off like the iOS and Android SDKs, waiting 1 second and doubling up to 30 seconds with ±25% jitter, until a batch is delivered. A `Retry-After` is a floor under that wait rather than a replacement diff --git a/.changeset/v6-flags-loaded-result.md b/.changeset/v6-flags-loaded-result.md deleted file mode 100644 index 03501e51..00000000 --- a/.changeset/v6-flags-loaded-result.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -"posthog_flutter": major ---- - -- **Breaking:** `PostHogConfig.onFeatureFlags` now receives a `PostHogFeatureFlagsLoaded` with the enabled flags, their values and whether loading failed. Update callbacks from `() { ... }` to `(loaded) { ... }` (or `(_) { ... }`) -- **Breaking:** `reloadFeatureFlags()` now returns a `Future` with the reloaded flags diff --git a/.changeset/v6-major-release.md b/.changeset/v6-major-release.md index 9d30fb0e..13693637 100644 --- a/.changeset/v6-major-release.md +++ b/.changeset/v6-major-release.md @@ -14,4 +14,23 @@ - **Breaking:** remove `PostHogDataMode.cellular` — use `PostHogDataMode.any` - **Breaking:** remove `toMap()` from the config classes and `PostHogFeatureFlagResult.fromMap()` from the public API - **Breaking:** rename `enable()` and `disable()` to `optIn()` and `optOut()` on `PosthogFlutterPlatformInterface`, `PosthogFlutterIO` and `PosthogFlutterWeb` +- **Breaking:** adopt `posthog-ios` 4.x, which requires Xcode 26 +- **Breaking:** adopt `posthog-android` 4.x +- **Breaking:** pass a `PostHogFeatureFlagsLoaded` with the enabled flags, their values and whether loading failed to `PostHogConfig.onFeatureFlags` — update callbacks from `() { ... }` to `(loaded) { ... }` or `(_) { ... }` +- **Breaking:** return the reloaded flags from `reloadFeatureFlags()` as a `Future` +- **Breaking:** return `null` instead of the raw string for a malformed, empty or whitespace-only `getFeatureFlagResult()` payload on iOS, macOS and Android +- **Breaking:** keep string payloads passed to `PostHogBootstrapConfig.featureFlagPayloads`, such as `"123"`, as strings on iOS and macOS instead of decoding them to numbers or booleans +- **Breaking:** stop sending the legacy `version` and `build` properties on `Application Installed`, `Application Updated` and `Application Opened` on iOS and macOS — use `$app_version` and `$app_build` +- **Breaking:** send events to capture v1 (`/i/v1/analytics/events`) instead of `/batch/` on iOS, macOS, Android, Windows and Linux — update your reverse proxy first, see the [iOS](https://github.com/PostHog/posthog-ios/blob/main/MIGRATION.md#hosts-without-capture-v1) and [Android](https://github.com/PostHog/posthog-android/blob/main/docs/migration-3.x-to-4.0.md#hosts-without-capture-v1) migration guides +- **Breaking:** retry a 404 on Windows and Linux so events stay queued, printing one warning, also without `debug`, until a reverse proxy or self-hosted instance serves the new path +- **Breaking:** drop the batch on a redirect on Windows and Linux, following only same-origin 307 and 308 redirects, and cap a `Retry-After` wait at 30 seconds +- **Breaking:** apply SDK properties, then registered properties, then event properties on Windows and Linux, so your value wins for that event, and run `beforeSend` after that merge +- **Breaking:** always set `$lib` and `$lib_version` from the `PostHog-Sdk-Info` header on Windows and Linux, ignoring changes made in `beforeSend` +- **Breaking:** send person processing as the `process_person_profile: false` option on Windows and Linux, only while it's off, instead of a `$process_person_profile` property on every event +- Add an `options` parameter to `capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group` and `captureException`, and `PostHogEvent.options` for `beforeSend` callbacks +- Add `captureAi` for AI observability events, a no-op that returns `null` on web +- Add `PostHogConfig.captureAiCompression`, `captureAiMaxQueueSize`, `captureAiTimeout` and `captureAiMaxEventBytes` +- Apply a `$process_person_profile` property or `process_person_profile` option passed with an event to that event on Windows and Linux +- Back off failed sends on Windows and Linux from 1 second up to 30 seconds with ±25% jitter, instead of resending within the flush, treating `Retry-After` as a floor +- Take an event's timestamp before the `beforeSend` callbacks run on Windows and Linux - Declare Android `minSdkVersion` 23 to match `posthog-android` diff --git a/.changeset/v6-posthog-android-4.md b/.changeset/v6-posthog-android-4.md deleted file mode 100644 index 3ec91401..00000000 --- a/.changeset/v6-posthog-android-4.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -"posthog_flutter": major ---- - -- **Breaking:** adopt `posthog-android` 4.x diff --git a/.changeset/v6-posthog-ios-4.md b/.changeset/v6-posthog-ios-4.md deleted file mode 100644 index 39b171fa..00000000 --- a/.changeset/v6-posthog-ios-4.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -"posthog_flutter": major ---- - -- **Breaking:** adopt `posthog-ios` 4.x, which requires Xcode 26 -- **Breaking:** return `null` instead of the raw string for a malformed, empty, or whitespace-only `getFeatureFlagResult()` payload on iOS and macOS -- **Breaking:** keep string payloads passed to `PostHogBootstrapConfig.featureFlagPayloads`, such as `"123"`, as strings on iOS and macOS instead of decoding them to numbers or booleans -- **Breaking:** stop sending the legacy `version` and `build` properties on `Application Installed`, `Application Updated` and `Application Opened` on iOS and macOS — use `$app_version` and `$app_build`. Android still sends them until `posthog-android` drops them diff --git a/posthog_flutter/MIGRATION.md b/posthog_flutter/MIGRATION.md index 0ba88922..ed7d4bc8 100644 --- a/posthog_flutter/MIGRATION.md +++ b/posthog_flutter/MIGRATION.md @@ -51,21 +51,15 @@ If every plugin in your app supports Swift Package Manager, you can remove Cocoa `posthog-android` has required `minSdkVersion` 23 since 3.39.0, so an app on 21 or 22 already could not build with this plugin. The plugin now declares the same value, and you have nothing to change. -### Native SDKs - - - -The native dependency ranges are unchanged by this release: `posthog-ios` `>= 3.92.3, < 4.0.0` and `posthog-android` `[3.72.9, 4.0.0)`. +### Native SDKs and Xcode + +| | 5.x | 6.0 | +| --- | --- | --- | +| `posthog-ios` | `>= 3.92.3, < 4.0.0` | `>= 4.0.0, < 5.0.0` | +| `posthog-android` | `[3.72.9, 4.0.0)` | `[4.0.0, 5.0.0)` | +| Xcode | Not set by the plugin | 26 or later | + +Don't add these native SDKs to your app separately at a different major version. ## Breaking API changes @@ -199,8 +193,61 @@ Future disable() async {} Future optOut() async {} ``` +### `onFeatureFlags` and `reloadFeatureFlags()` + +`PostHogConfig.onFeatureFlags` now receives a `PostHogFeatureFlagsLoaded`, and `reloadFeatureFlags()` returns a `Future`. It has `flags`, `variants` and `errorsLoading`. + +```dart +// Before +config.onFeatureFlags = () { + // ... +}; + +// After +config.onFeatureFlags = (loaded) { + if (!loaded.errorsLoading) { + // Use loaded.variants + } +}; +``` + ## Behavior changes +### Events go to capture v1 + +**This is a silent change if you use a reverse proxy or self-host.** On iOS, macOS, Android, Windows and Linux, events go to `/i/v1/analytics/events` instead of `/batch/`, and `captureAi` events go to `/i/v1/ai/events`. Web keeps using posthog-js and its current endpoints. PostHog Cloud and the managed reverse proxy already serve the new paths. + +Before you upgrade, make your own proxy: + +- forward `/i/v1/analytics/events` and `/i/v1/ai/events` +- pass `Authorization` (the project token, sent as `Bearer `), every `PostHog-*` header, `Content-Type`, `Content-Encoding` and `User-Agent` through unchanged +- accept request bodies up to 20 MB + +If you ignore this on Windows and Linux, a 404 is retried, events stay queued, and the SDK prints one warning, also without `debug`. See the [iOS](https://github.com/PostHog/posthog-ios/blob/main/MIGRATION.md#hosts-without-capture-v1) and [Android](https://github.com/PostHog/posthog-android/blob/main/docs/migration-3.x-to-4.0.md#hosts-without-capture-v1) guides for those platforms. + +### Feature flag payloads + +On iOS, macOS and Android, a malformed, empty or whitespace-only payload from `getFeatureFlagResult()` is now `null` instead of the raw string. On Android, a JSON `null` payload is also `null` instead of the string `"null"`. + +On iOS and macOS, string values in `PostHogBootstrapConfig.featureFlagPayloads`, such as `"123"`, stay strings instead of being decoded to numbers or booleans. + +### Lifecycle events on iOS and macOS + +`Application Installed`, `Application Updated` and `Application Opened` no longer include `version` and `build`. Update insights, cohorts and filters that use them to `$app_version` and `$app_build`. Android still sends them. + +### Network reachability on iOS and macOS + +A path that needs user action, such as a VPN waiting for a password, counts as reachable, and queues pause while cellular data is off for the app. Events captured in the first 100 ms after setup may leave out `$network_wifi` and `$network_cellular`. Events still on disk from a `posthog-ios` 2.x SDK are deleted instead of sent. + +### Windows and Linux + +- **Property order:** an event's properties are the SDK's, then registered properties, then the event's own, so your value now wins for that event. `beforeSend` runs after that merge, except that `$lib` and `$lib_version` always come from the `PostHog-Sdk-Info` header. +- **Person processing:** it's sent as the `process_person_profile: false` option only while it's off, instead of a `$process_person_profile` property on every event. +- **Redirects:** only same-origin 307 and 308 redirects are followed. Any other redirect drops the batch. +- **Retries:** a failed batch waits 1 second, doubling up to 30 seconds with ±25% jitter, instead of retrying within the same flush. `Retry-After` is a floor under that wait, capped at 30 seconds. +- **Timestamps:** an event's timestamp is taken before `beforeSend` runs. +- **AI queue:** `captureAi` events have their own on-disk queue of up to `captureAiMaxQueueSize` events (100 by default) and 50 MiB. An event over `captureAiMaxEventBytes` (8 MiB plus 64 KiB by default) is dropped. + ### `getFeatureFlagResult()` follows your config **This is a silent change with no compile error.** When you omit `sendFeatureFlagEvent`, `getFeatureFlagResult()` now uses `PostHogConfig.sendFeatureFlagEvent` instead of always capturing `$feature_flag_called`. This matches `getFeatureFlag()` and `isFeatureEnabled()`. @@ -213,12 +260,21 @@ await Posthog().getFeatureFlagResult('my-flag', sendFeatureFlagEvent: true); On web, `PostHogConfig.sendFeatureFlagEvent` is not applied to posthog-js, so an omitted value keeps the posthog-js default, which captures the event. Pass `sendFeatureFlagEvent: false` to suppress it on web. +## New features + +- An `options` argument on `capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group` and `captureException`, and `PostHogEvent.options` in `beforeSend`. `process_person_profile`, `cookieless_mode`, `disable_skew_correction` and `product_tour_id` win over their legacy `$` properties. On web, known keys are sent as those legacy properties and other keys are dropped. +- `captureAi` for `$ai_*` events. It returns the event's UUID, or `null` when the event isn't admitted. On web it sends nothing and returns `null`. + ## Upgrade checklist - [ ] Use Flutter 3.41 or later and make sure Swift Package Manager is on. - [ ] Don't upgrade yet if you embed Flutter as an iOS or macOS add-to-app module. - [ ] Raise iOS to 15.0 and macOS to 11.0 in your Xcode projects, and in any `Podfile` you keep. - [ ] Rename `com.posthog.posthog.API_KEY` to `com.posthog.posthog.PROJECT_TOKEN` in `AndroidManifest.xml` and `Info.plist`. +- [ ] Use Xcode 26 or later. +- [ ] If you run your own reverse proxy or self-host, serve `/i/v1/analytics/events` and `/i/v1/ai/events` first. +- [ ] Update `onFeatureFlags` callbacks to take a `PostHogFeatureFlagsLoaded`. +- [ ] Move anything that reads `version` or `build` on iOS and macOS lifecycle events to `$app_version` and `$app_build`. - [ ] If you set `sendFeatureFlagEvent = false`, check whether anything relies on `$feature_flag_called` from `getFeatureFlagResult()`. - [ ] Add `sendFeatureFlagEvent: false` wherever you replace `getFeatureFlagPayload()`. - [ ] Fix the remaining compile errors using the sections above, including any test fakes of the platform classes. From 7edf2cd30837a952fb9785903c51033513e519b8 Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Mon, 2 Nov 2026 12:57:28 -0500 Subject: [PATCH 16/28] fix(desktop): skip phx_ keys, keep response bodies out of logs, count duplicate copies (#681) * fix(desktop): skip phx_ keys, keep response bodies out of logs, count duplicate copies - Posthog.setup skips a projectToken that is a personal API key (phx_), like the native SDKs, so the key never goes on the wire (INV-32). - PostHogFetchHttpError.toString leaves out the response body, which can echo request values (FC-5/FQ-18); the flush error log names the lane. - captureV1Results reads duplicates_dropped and the per-batch log reports the dropped copies (FQ-19). * fix(desktop): clamp duplicates_dropped to the batch size * fix(desktop): clamp duplicates_dropped against every copy sent Co-Authored-By: Claude Opus 5.5 * fix(desktop): drop unreadable 2xx batches and log lost events with endpoint and reasons - A 2xx whose body has no readable per-event results fails the batch for good: it's dropped, not resent, and reported through the error event, matching posthog-ios and posthog-android. - One aggregate line per batch that lost events, naming the endpoint, the count and capture's `details` tags (never uuids or content). A terminal status logs how many events it lost; a multi-event 413 still halves. - A `limited` result counts as delivered, like any unknown result. - The non-string session/window id warning names the JSON type `boolean`. - Test fakes answer capture requests with per-event results, as capture v1 does. Co-Authored-By: Claude Opus 5.5 * test(desktop): answer capture v1 batches with readable results Co-Authored-By: Claude Opus 5.5 * fix(desktop): log only reason codes from capture v1 drops Co-Authored-By: Claude Opus 5.5 * docs: fold #681 release notes into the 6.0 docs --------- Co-authored-by: Claude Opus 5.5 --- .changeset/v6-major-release.md | 4 + example/integration_test/desktop_test.dart | 6 +- posthog_flutter/MIGRATION.md | 4 + posthog_flutter/lib/src/core/capture_v1.dart | 43 +++++-- .../lib/src/core/posthog_core_stateless.dart | 54 ++++++--- posthog_flutter/lib/src/posthog.dart | 8 ++ .../test/core/capture_v1_test.dart | 113 +++++++++++++++++- posthog_flutter/test/core/requests_test.dart | 15 ++- posthog_flutter/test/posthog_api_fake.dart | 18 ++- .../test/posthog_flutter_desktop_test.dart | 38 +++--- posthog_flutter/test/posthog_test.dart | 16 +++ 11 files changed, 262 insertions(+), 57 deletions(-) diff --git a/.changeset/v6-major-release.md b/.changeset/v6-major-release.md index 13693637..b01f360b 100644 --- a/.changeset/v6-major-release.md +++ b/.changeset/v6-major-release.md @@ -31,6 +31,10 @@ - Add `captureAi` for AI observability events, a no-op that returns `null` on web - Add `PostHogConfig.captureAiCompression`, `captureAiMaxQueueSize`, `captureAiTimeout` and `captureAiMaxEventBytes` - Apply a `$process_person_profile` property or `process_person_profile` option passed with an event to that event on Windows and Linux +- Skip `setup()` with one log line when `projectToken` is a personal API key (`phx_`), so the key is never sent +- Stop printing capture's response body in flush error logs on Windows and Linux, and log how many repeated-uuid copies capture dropped +- Drop a batch whose 2xx response has no readable per-event results on Windows and Linux instead of counting it as delivered, without resending it +- Log one line per batch that lost events on Windows and Linux, with the endpoint, count and reasons, also for a terminal status, and count a `limited` result as delivered - Back off failed sends on Windows and Linux from 1 second up to 30 seconds with ±25% jitter, instead of resending within the flush, treating `Retry-After` as a floor - Take an event's timestamp before the `beforeSend` callbacks run on Windows and Linux - Declare Android `minSdkVersion` 23 to match `posthog-android` diff --git a/example/integration_test/desktop_test.dart b/example/integration_test/desktop_test.dart index acee9fb5..67525390 100644 --- a/example/integration_test/desktop_test.dart +++ b/example/integration_test/desktop_test.dart @@ -203,7 +203,11 @@ class _FakePostHog { switch (request.uri.path) { case '/i/v1/analytics/events': response.statusCode = batchStatus; - if (batchStatus == HttpStatus.ok) _batches.add(body); + if (batchStatus == HttpStatus.ok) { + _batches.add(body); + response.headers.contentType = ContentType.json; + response.write(jsonEncode({'results': {}})); + } case '/flags/': _flagsRequests.add(body); response.headers.contentType = ContentType.json; diff --git a/posthog_flutter/MIGRATION.md b/posthog_flutter/MIGRATION.md index ed7d4bc8..88f4d8a6 100644 --- a/posthog_flutter/MIGRATION.md +++ b/posthog_flutter/MIGRATION.md @@ -239,6 +239,10 @@ On iOS and macOS, string values in `PostHogBootstrapConfig.featureFlagPayloads`, A path that needs user action, such as a VPN waiting for a password, counts as reachable, and queues pause while cellular data is off for the app. Events captured in the first 100 ms after setup may leave out `$network_wifi` and `$network_cellular`. Events still on disk from a `posthog-ios` 2.x SDK are deleted instead of sent. +### Personal API keys + +A personal API key (`phx_...`) in `projectToken` now skips `setup()` with one log line, so the SDK doesn't start and the key is never sent. Use your project token (`phc_...`). + ### Windows and Linux - **Property order:** an event's properties are the SDK's, then registered properties, then the event's own, so your value now wins for that event. `beforeSend` runs after that merge, except that `$lib` and `$lib_version` always come from the `PostHog-Sdk-Info` header. diff --git a/posthog_flutter/lib/src/core/capture_v1.dart b/posthog_flutter/lib/src/core/capture_v1.dart index 491f76f8..216534eb 100644 --- a/posthog_flutter/lib/src/core/capture_v1.dart +++ b/posthog_flutter/lib/src/core/capture_v1.dart @@ -109,7 +109,7 @@ String? _liftString( } String _jsonType(Object value) => switch (value) { - bool() => 'bool', + bool() => 'boolean', num() => 'number', Map() => 'object', List() => 'array', @@ -150,13 +150,19 @@ class CaptureV1Identity { ); } +final _captureV1DropTag = RegExp(r'^[a-z0-9_]{1,64}$'); + /// The uuids among [uuids] that a capture v1 response [body] asks to -/// retry, with how many of them it rejected (`drop` or `limited`), or null -/// when the body has no readable per-event results. +/// retry, with how many of them it dropped (`drop`) by `details` tag and +/// how many repeated copies of them it dropped (`duplicates_dropped`), or +/// null when the body has no readable per-event results. +/// +/// [uuids] holds one entry per event sent, repeats included. /// -/// `ok`, `warning`, `drop`, `limited` and any unknown result are final. -/// An event missing from the results counts as delivered. -({Set retry, int rejected})? captureV1Results( +/// `ok`, `warning`, `drop` and any unknown result are final; only `drop` +/// counts as dropped. An event missing from the results counts as +/// delivered. +({Set retry, Map drops, int duplicates})? captureV1Results( String? body, Iterable uuids, ) { @@ -169,17 +175,30 @@ class CaptureV1Identity { return null; } if (results is! Map) return null; + final batch = uuids.toList(growable: false); final retry = {}; - var rejected = 0; - for (final uuid in uuids) { - switch (results[uuid]) { + final drops = {}; + var duplicates = 0; + for (final uuid in batch.toSet()) { + final result = results[uuid]; + switch (result) { case {'result': 'retry'}: retry.add(uuid); - case {'result': 'drop' || 'limited'}: - rejected++; + case {'result': 'drop'}: + // These tags reach the logs, so anything but a reason code, such as + // an echoed id or a forged log line, is discarded. + final details = switch (result['details']) { + final String tag when _captureV1DropTag.hasMatch(tag) => tag, + _ => 'no details', + }; + drops[details] = (drops[details] ?? 0) + 1; + } + // Clamped so a malformed count can't exceed the batch. + if (result case {'duplicates_dropped': final int dropped}) { + duplicates += dropped.clamp(0, batch.length); } } - return (retry: retry, rejected: rejected); + return (retry: retry, drops: drops, duplicates: duplicates); } /// Whether two `Set`s hold the same elements. diff --git a/posthog_flutter/lib/src/core/posthog_core_stateless.dart b/posthog_flutter/lib/src/core/posthog_core_stateless.dart index 26827de9..478a74b7 100644 --- a/posthog_flutter/lib/src/core/posthog_core_stateless.dart +++ b/posthog_flutter/lib/src/core/posthog_core_stateless.dart @@ -28,9 +28,11 @@ class PostHogFetchHttpError implements Exception { PostHogFetchHttpError(this.status, this.responseBody, this.reqByteLength, {this.retryAfter}); + /// Leaves out [responseBody]: capture's error details can echo request + /// values. @override String toString() => 'PostHogFetchHttpError: status=$status, ' - 'reqByteLength=$reqByteLength, response=$responseBody'; + 'reqByteLength=$reqByteLength'; } /// Network error during PostHog fetch. @@ -622,7 +624,7 @@ abstract class PostHogCoreStateless { void _flushBackground(_CaptureLane lane) { _flushLane(lane).catchError((e) { - logger.error('Error while flushing PostHog', e); + logger.error('Error while flushing PostHog ${lane.path}', e); }); } @@ -748,19 +750,21 @@ abstract class PostHogCoreStateless { /// delivered or dropped for good. /// /// A 2xx whose per-event results cannot be read, also when the response - /// fails after its status arrived, counts as delivered: the server stored - /// the events, and sending them again would store them twice. + /// fails after its status arrived, fails the whole batch for good. It + /// isn't retried: the server may have stored some of the events, and + /// sending them again would store them twice. /// - /// Throws [PostHogFetchHttpError] for a non-2xx status and - /// [PostHogFetchNetworkError] for a transport failure. + /// Throws [PostHogFetchHttpError] for a non-2xx status or an unreadable + /// 2xx, and [PostHogFetchNetworkError] for a transport failure. Future<({Set retryUuids, Duration? retryAfter})> _postCaptureV1( _CaptureLane lane, List batch, ) async { - final uuids = { + final eventUuids = [ for (final queued in batch) if (queued.event['uuid'] case final String uuid) uuid, - }; + ]; + final uuids = eventUuids.toSet(); final pending = lane.pendingIdentity; final identity = pending != null && sameUuids(pending.uuids, uuids) ? pending.next() @@ -791,6 +795,12 @@ abstract class PostHogCoreStateless { if (response.status < 200 || response.status >= 300) { if (!isRetriableCaptureV1Status(response.status)) { lane.pendingIdentity = null; + // A multi-event 413 halves the batch and resends it instead. + if (response.status != HttpStatus.requestEntityTooLarge || + batch.length == 1) { + logger.warn('Capture ${lane.path} returned ${response.status}: ' + '${batch.length} events dropped for good.'); + } } throw PostHogFetchHttpError( response.status, @@ -800,15 +810,29 @@ abstract class PostHogCoreStateless { ); } - final results = captureV1Results(response.body, uuids); + final results = captureV1Results(response.body, eventUuids); if (results == null) { - logger.info('Capture returned ${response.status} without readable ' - 'per-event results; ${uuids.length} events count as delivered.'); - } else if (results.rejected > 0) { - logger.warn('Capture dropped ${results.rejected} of ${uuids.length} ' - 'events for good.'); + lane.pendingIdentity = null; + // Status and count only: the body may name event uuids. + logger.warn('Capture ${lane.path} returned ${response.status} without ' + 'readable per-event results: ${batch.length} events dropped for ' + 'good.'); + throw PostHogFetchHttpError(response.status, '', body.length); + } + // Counts and the server's opaque reasons only, one line per batch: + // uuids and event content can identify users. + final dropped = results.drops.values.fold(0, (sum, n) => sum + n); + if (dropped > 0 || results.duplicates > 0) { + final reasons = [ + for (final MapEntry(:key, :value) in results.drops.entries) + '$key: $value', + ].join(', '); + logger.warn('Capture ${lane.path} dropped $dropped of ' + '${batch.length} events for good' + '${reasons.isEmpty ? '' : ' ($reasons)'}' + ' and ${results.duplicates} repeated-uuid copies.'); } - final retryUuids = results?.retry ?? const {}; + final retryUuids = results.retry; lane.pendingIdentity = retryUuids.isEmpty ? null : identity.withUuids(retryUuids); return (retryUuids: retryUuids, retryAfter: response.retryAfter); diff --git a/posthog_flutter/lib/src/posthog.dart b/posthog_flutter/lib/src/posthog.dart index fd0c2a06..2c8ed7f5 100644 --- a/posthog_flutter/lib/src/posthog.dart +++ b/posthog_flutter/lib/src/posthog.dart @@ -75,6 +75,14 @@ class Posthog { ); return Future.value(); } + // Capture rejects a personal API key, so it is never sent. + if (config.projectToken.startsWith('phx_')) { + debugPrint( + '[PostHog] projectToken is a personal API key (phx_), not a project ' + 'token. Setup skipped.', + ); + return Future.value(); + } if (!config.enableWindowsAndLinux && !kIsWeb && diff --git a/posthog_flutter/test/core/capture_v1_test.dart b/posthog_flutter/test/core/capture_v1_test.dart index b5340483..9d978497 100644 --- a/posthog_flutter/test/core/capture_v1_test.dart +++ b/posthog_flutter/test/core/capture_v1_test.dart @@ -154,6 +154,16 @@ void main() { expect(lines.single, contains('number')); expect(lines.single, isNot(contains('42'))); }); + + test('names the JSON type of a boolean session id', () { + final lines = []; + captureV1Event({ + 'event': 'e', + 'properties': {r'$window_id': true}, + }, CoreLogger((log) => lines.addAll(printedLines(log)))); + + expect(lines.single, contains('a boolean value')); + }); }); group('captureRetryDelay', () { @@ -228,8 +238,10 @@ void main() { final uuids = [ for (final event in api.batchRequests.single.events) event['uuid'], ]; - final rejection = - lines.singleWhere((line) => line.contains('dropped 2 of 7')); + // `limited` and unknown results count as delivered, like `ok`. + final rejection = lines.singleWhere((line) => line + .contains('/i/v1/analytics/events dropped 1 of 7 events for good ' + '(detail: 1)')); for (final uuid in uuids) { expect(rejection, isNot(contains('$uuid'))); } @@ -359,18 +371,109 @@ void main() { }); }); - test('counts a 2xx without readable results as delivered', () async { + test('counts the duplicate copies capture dropped', () { + final body = jsonEncode({ + 'results': { + 'a': {'result': 'ok', 'duplicates_dropped': 2}, + 'b': {'result': 'retry', 'duplicates_dropped': 1}, + 'c': {'result': 'ok'}, + }, + }); + + final results = captureV1Results(body, ['a', 'b', 'c'])!; + + expect(results.duplicates, 3); + expect(results.retry, {'b'}); + }); + + test('clamps malformed duplicates_dropped to the batch size', () { + final body = jsonEncode({ + 'results': { + 'a': {'result': 'ok', 'duplicates_dropped': 9007199254740991}, + 'b': {'result': 'ok', 'duplicates_dropped': -5}, + 'c': {'result': 'ok', 'duplicates_dropped': '2'}, + }, + }); + + expect(captureV1Results(body, ['a', 'b', 'c'])!.duplicates, 3); + }); + + test('clamps duplicates_dropped against every copy sent', () { + final body = jsonEncode({ + 'results': { + 'a': {'result': 'drop', 'duplicates_dropped': 2}, + }, + }); + + final results = captureV1Results(body, ['a', 'a', 'a'])!; + + expect(results.duplicates, 2); + expect(results.drops, {'no details': 1}); + }); + + test('keeps only reason codes as drop reasons', () { + final body = jsonEncode({ + 'results': { + 'a': {'result': 'drop', 'details': 'event_too_big'}, + 'b': {'result': 'drop', 'details': 'x\n[PostHog] forged'}, + 'c': {'result': 'drop', 'details': 'user@example.com'}, + 'd': {'result': 'drop', 'details': 'a' * 65}, + }, + }); + + expect(captureV1Results(body, ['a', 'b', 'c', 'd'])!.drops, { + 'event_too_big': 1, + 'no details': 3, + }); + }); + + test('drops a 2xx without readable results without retrying it', () async { final server = await LocalPostHogServer.start(); final storage = tempStorage(); final client = testClient(server, storage: storage); server.respond = (_) => const PostHogResponse(HttpStatus.ok, body: 'not json'); + final errors = []; + // ignore: invalid_use_of_protected_member + client.events.on('error', errors.add); + final flushed = []; + // ignore: invalid_use_of_protected_member + client.events.on('flush', flushed.add); client.capture('evt'); - await client.flush(); + await expectLater(client.flush(), throwsA(isA())); expect(server.batchRequests, hasLength(1)); expect(getQueue(storage), isEmpty); + expect(errors, hasLength(1)); + expect(flushed, isEmpty); + }); + + test('logs the endpoint and count of a batch lost to a terminal status', + () { + final api = InProcessPostHogApi(); + final storage = tempStorage(); + fakeAsync((async) { + final client = + testClient(api, config: testConfig(debug: true), storage: storage); + api.respond = (request) => request.isFlags + ? PostHogResponse.json({'flags': {}}) + : const PostHogResponse(HttpStatus.badRequest); + client.capture('one'); + client.capture('two'); + + final lines = printedLines(() { + client.flush().catchError((_) {}); + async.elapse(Duration.zero); + }); + + expect(api.batchRequests, hasLength(1)); + expect(queuedEvents(storage), isEmpty); + expect( + lines, + contains(contains('Capture /i/v1/analytics/events returned 400: ' + '2 events dropped for good.'))); + }); }); test('drops a single event that is still too large', () async { @@ -419,7 +522,7 @@ void main() { server.respond = (request) => request.path == '/i/v1/analytics/events' ? PostHogResponse(HttpStatus.temporaryRedirect, location: '${server.url}/moved/events') - : const PostHogResponse(HttpStatus.ok); + : PostHogResponse.results(request, (_) => 'ok'); client.capture('evt'); await client.flush(); diff --git a/posthog_flutter/test/core/requests_test.dart b/posthog_flutter/test/core/requests_test.dart index 004768ce..f80fef2e 100644 --- a/posthog_flutter/test/core/requests_test.dart +++ b/posthog_flutter/test/core/requests_test.dart @@ -46,7 +46,8 @@ void main() { client.flush(), throwsA(isA() .having((e) => e.status, 'status', 400) - .having((e) => e.responseBody, 'responseBody', 'invalid batch'))); + .having((e) => e.responseBody, 'responseBody', 'invalid batch') + .having((e) => '$e', 'toString', isNot(contains('invalid'))))); }); test('leave a redirect unfollowed', () async { @@ -243,6 +244,7 @@ void main() { async.elapse(const Duration(seconds: 6)); body.add(utf8.encode(' ')); } + body.add(utf8.encode('{"results": {}}')); body.close(); async.flushMicrotasks(); @@ -282,7 +284,7 @@ void main() { }); }); - test('counts a 2xx whose body times out as delivered', () { + test('drops a 2xx whose body times out without resending it', () { fakeAsync((async) { // Cancelled in this zone: fake_async does not run the root zone's // microtasks. @@ -299,11 +301,11 @@ void main() { createHttpClient: (_) => http, ); client.capture('evt'); - var flushed = false; - client.flush().then((_) => flushed = true); + Object? error; + client.flush().catchError((Object e) => error = e); async.elapse(const Duration(seconds: 10)); - expect(flushed, isTrue); + expect(error, isA()); async.elapse(const Duration(seconds: 30)); expect(openCalls, 1, reason: 'a resend would store the events a second time'); @@ -334,7 +336,8 @@ class _ControlledHttpClient implements HttpClient { class _ControlledRequest implements HttpClientRequest { _ControlledRequest({HttpClientResponse? response, this.takeChunk}) - : _response = response ?? _ControlledResponse(Stream.value([])); + : _response = response ?? + _ControlledResponse(Stream.value(utf8.encode('{"results": {}}'))); final HttpClientResponse _response; diff --git a/posthog_flutter/test/posthog_api_fake.dart b/posthog_flutter/test/posthog_api_fake.dart index d3b52fd2..f20606da 100644 --- a/posthog_flutter/test/posthog_api_fake.dart +++ b/posthog_flutter/test/posthog_api_fake.dart @@ -55,9 +55,12 @@ class PostHogRequest { /// How the PostHog API answers a request. class PostHogResponse { const PostHogResponse(this.status, - {this.body = '{"status": 1}', this.location, this.headers = const {}}) + {this.body = defaultBody, this.location, this.headers = const {}}) : isDropped = false; + /// The body of a response that sets none. + static const defaultBody = '{"status": 1}'; + /// A success with [json] as its body. PostHogResponse.json(Object? json, {Map headers = const {}}) : this(HttpStatus.ok, body: jsonEncode(json), headers: headers); @@ -169,7 +172,18 @@ abstract class PostHogApiFake { waiter.done.complete(); return true; }); - return respond(request); + final response = await respond(request); + // Capture v1 answers every 2xx with per-event results. A success left + // with the default body gets an `ok` result for each event, so only a + // test that sets a body of its own sends an unreadable one. + if ((request.isBatch || request.isAi) && + response.status >= 200 && + response.status < 300 && + identical(response.body, PostHogResponse.defaultBody)) { + return PostHogResponse.results(request, (_) => 'ok', + headers: response.headers); + } + return response; } Future _waitUntil(bool Function() isReady) { diff --git a/posthog_flutter/test/posthog_flutter_desktop_test.dart b/posthog_flutter/test/posthog_flutter_desktop_test.dart index 9870e849..e15a7f7e 100644 --- a/posthog_flutter/test/posthog_flutter_desktop_test.dart +++ b/posthog_flutter/test/posthog_flutter_desktop_test.dart @@ -790,7 +790,7 @@ void main() { test('properties the callbacks remove stay removed', () async { final server = await LocalPostHogServer.start(); - server.respond = (_) => PostHogResponse.json(_variantFlagResponse()); + server.respond = _answerFlags(_variantFlagResponse()); final flagsLoaded = Completer(); Map? seen; final removed = [ @@ -845,7 +845,7 @@ void main() { test('SDK-internal events bypass the callbacks', () async { final server = await LocalPostHogServer.start(); - server.respond = (_) => PostHogResponse.json(_variantFlagResponse()); + server.respond = _answerFlags(_variantFlagResponse()); final flagsLoaded = Completer(); final seenEventNames = []; final config = configFor(server) @@ -2201,7 +2201,7 @@ void main() { r'getFeatureFlagResult with sendFeatureFlagEvent false does not capture $feature_flag_called', () async { final server = await LocalPostHogServer.start(); - server.respond = (_) => PostHogResponse.json(_variantFlagResponse()); + server.respond = _answerFlags(_variantFlagResponse()); final flagsLoaded = Completer(); final config = configFor(server) ..onFeatureFlags = (_) { @@ -2231,7 +2231,7 @@ void main() { 'captureFeatureView and captureFeatureInteraction match the native event shape', () async { final server = await LocalPostHogServer.start(); - server.respond = (_) => PostHogResponse.json(_variantFlagResponse()); + server.respond = _answerFlags(_variantFlagResponse()); final flagsLoaded = Completer(); final config = configFor(server) ..onFeatureFlags = (_) { @@ -2267,7 +2267,7 @@ void main() { test('captureFeatureView keeps the user it was called for across reset', () async { final server = await LocalPostHogServer.start(); - server.respond = (_) => PostHogResponse.json(_variantFlagResponse()); + server.respond = _answerFlags(_variantFlagResponse()); final flagsLoaded = Completer(); final config = configFor(server) ..onFeatureFlags = (_) { @@ -2286,7 +2286,7 @@ void main() { test(r'sendFeatureFlagEvent false skips $feature_flag_called', () async { final server = await LocalPostHogServer.start(); - server.respond = (_) => PostHogResponse.json(_variantFlagResponse()); + server.respond = _answerFlags(_variantFlagResponse()); final flagsLoaded = Completer(); final config = configFor(server) ..onFeatureFlags = (_) { @@ -2312,7 +2312,7 @@ void main() { r'getFeatureFlag follows config.sendFeatureFlagEvent unless overridden', () async { final server = await LocalPostHogServer.start(); - server.respond = (_) => PostHogResponse.json(_variantFlagResponse()); + server.respond = _answerFlags(_variantFlagResponse()); final flagsLoaded = Completer(); final config = configFor(server) ..sendFeatureFlagEvent = false @@ -2338,12 +2338,12 @@ void main() { r'getAllFeatureFlags returns every loaded flag without capturing $feature_flag_called', () async { final server = await LocalPostHogServer.start(); - server.respond = (_) => PostHogResponse.json({ - 'flags': { - ..._variantFlagResponse()['flags']! as Map, - 'off-flag': {'key': 'off-flag', 'enabled': false}, - }, - }); + server.respond = _answerFlags({ + 'flags': { + ..._variantFlagResponse()['flags']! as Map, + 'off-flag': {'key': 'off-flag', 'enabled': false}, + }, + }); final platform = await setUpPlatform( configFor(server)..preloadFeatureFlags = false, ); @@ -2371,7 +2371,7 @@ void main() { 'reloadFeatureFlags returns the loaded flags, and the last known ones when loading fails', () async { final server = await LocalPostHogServer.start(); - server.respond = (_) => PostHogResponse.json(_variantFlagResponse()); + server.respond = _answerFlags(_variantFlagResponse()); final announced = []; final platform = await setUpPlatform(configFor(server) ..preloadFeatureFlags = false @@ -2392,7 +2392,7 @@ void main() { r'getFeatureFlagResult follows config.sendFeatureFlagEvent unless overridden', () async { final server = await LocalPostHogServer.start(); - server.respond = (_) => PostHogResponse.json(_variantFlagResponse()); + server.respond = _answerFlags(_variantFlagResponse()); final flagsLoaded = Completer(); final config = configFor(server) ..sendFeatureFlagEvent = false @@ -2439,7 +2439,7 @@ void main() { test('onFeatureFlags reports the flags cached by the previous launch', () async { final server = await LocalPostHogServer.start(); - server.respond = (_) => PostHogResponse.json(_variantFlagResponse()); + server.respond = _answerFlags(_variantFlagResponse()); final appDirectory = createAppDirectory(); final previousLaunch = createPlatform(appDirectory: appDirectory); await previousLaunch @@ -2503,3 +2503,9 @@ Map _variantFlagResponse() => { }, }, }; + +/// Answers `/flags/` with [flags], and every other request with a success. +PostHogResponder _answerFlags(Map flags) => + (request) => request.isFlags + ? PostHogResponse.json(flags) + : const PostHogResponse(HttpStatus.ok); diff --git a/posthog_flutter/test/posthog_test.dart b/posthog_flutter/test/posthog_test.dart index 0f6d6f66..20438317 100644 --- a/posthog_flutter/test/posthog_test.dart +++ b/posthog_flutter/test/posthog_test.dart @@ -44,6 +44,22 @@ void main() { }, ); + for (final token in [' \n\t ', 'phx_personal_api_key']) { + test('setup is skipped for the project token "$token"', () async { + final lines = []; + final previous = debugPrint; + debugPrint = (message, {wrapWidth}) => lines.add(message); + try { + await Posthog().setup(PostHogConfig(token)); + } finally { + debugPrint = previous; + } + + expect(fakePlatformInterface.receivedConfig, isNull); + expect(lines, hasLength(1)); + }); + } + test('Windows and Linux support is enabled by default', () { expect(PostHogConfig('test_project_token').enableWindowsAndLinux, isTrue); }); From 61bc998a2a59727a16c4af403a20477e37810fe3 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Mon, 2 Nov 2026 18:21:02 -0500 Subject: [PATCH 17/28] docs(migration): keep PostHog keys when a proxy strips Authorization Co-Authored-By: Claude Opus 5.5 --- posthog_flutter/MIGRATION.md | 1 + 1 file changed, 1 insertion(+) diff --git a/posthog_flutter/MIGRATION.md b/posthog_flutter/MIGRATION.md index 88f4d8a6..e56eb0d4 100644 --- a/posthog_flutter/MIGRATION.md +++ b/posthog_flutter/MIGRATION.md @@ -221,6 +221,7 @@ Before you upgrade, make your own proxy: - forward `/i/v1/analytics/events` and `/i/v1/ai/events` - pass `Authorization` (the project token, sent as `Bearer `), every `PostHog-*` header, `Content-Type`, `Content-Encoding` and `User-Agent` through unchanged +- if your proxy strips other credentials, keep `Authorization` values that start with `Bearer phc_`, `Bearer phs_` or `Bearer phx_`, plus the exact `Bearer ` of an older key without a prefix - accept request bodies up to 20 MB If you ignore this on Windows and Linux, a 404 is retried, events stay queued, and the SDK prints one warning, also without `debug`. See the [iOS](https://github.com/PostHog/posthog-ios/blob/main/MIGRATION.md#hosts-without-capture-v1) and [Android](https://github.com/PostHog/posthog-android/blob/main/docs/migration-3.x-to-4.0.md#hosts-without-capture-v1) guides for those platforms. From 66f5fe92f1cfbf08a2feda427d7303ca0e6d893d Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Mon, 2 Nov 2026 18:48:40 -0500 Subject: [PATCH 18/28] test: pass the loaded flags to onFeatureFlags in the #694 desktop tests Co-Authored-By: Claude Opus 5.5 --- posthog_flutter/test/posthog_flutter_desktop_test.dart | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/posthog_flutter/test/posthog_flutter_desktop_test.dart b/posthog_flutter/test/posthog_flutter_desktop_test.dart index 3f24d8e3..ef9b17c2 100644 --- a/posthog_flutter/test/posthog_flutter_desktop_test.dart +++ b/posthog_flutter/test/posthog_flutter_desktop_test.dart @@ -2300,7 +2300,7 @@ void main() { }); final flagsLoaded = Completer(); final config = configFor(server) - ..onFeatureFlags = () { + ..onFeatureFlags = (_) { if (!flagsLoaded.isCompleted) flagsLoaded.complete(); }; final platform = await setUpPlatform(config); @@ -2322,7 +2322,7 @@ void main() { server.respond = (_) => PostHogResponse.json(_variantFlagResponse()); final flagsLoaded = Completer(); final config = configFor(server) - ..onFeatureFlags = () { + ..onFeatureFlags = (_) { if (!flagsLoaded.isCompleted) flagsLoaded.complete(); }; final platform = await setUpPlatform(config); From 3bd4aa0a6f752427224e8870e79d5fe88d7c5d71 Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Tue, 3 Nov 2026 10:34:57 -0500 Subject: [PATCH 19/28] perf(desktop): move queue file work and request compression off the UI isolate (#688) * perf(desktop): move queue file work and request compression off the UI isolate On Windows and Linux the Dart client encoded, measured, wrote and read queued events and gzipped request bodies on the UI isolate. An 8 MB AI event stalled it for over 200 ms. A long-lived background isolate now does that work, in order, falling back to the calling isolate if it cannot start or exits. - The queue keeps its order and counts on the UI isolate; an event takes its place at once and is measured by the worker. - captureAi waits for the worker's size verdict, and applies person properties only if the user is unchanged. - close() waits for pending writes and deletes, so the next client neither misses an event nor sends one again. Co-Authored-By: Claude Opus 5.5 * fix(desktop): wait only for writes preceding a queue peek Co-Authored-By: Claude Opus 5.5 * fix(desktop): exclude AI events being measured from queue eviction Co-Authored-By: Claude Opus 5.5 * fix(desktop): keep selecting queue events past unreadable files Co-Authored-By: Claude Opus 5.5 * fix(desktop): keep person properties set while an AI event is measured Co-Authored-By: Claude Opus 5.5 * chore(ci): TEMP diagnose the hanging test step Co-Authored-By: Claude Opus 5.5 * chore(ci): remove the temporary test step diagnostics Co-Authored-By: Claude Opus 5.5 * fix(desktop): recheck flushAt once a queued event is written Co-Authored-By: Claude Opus 5.5 * fix(desktop): skip the snapshot write for AI events without person properties Co-Authored-By: Claude Opus 5.5 * fix(desktop): keep the directory locked until queue file work is done Co-Authored-By: Claude Opus 5.5 * fix(desktop): don't throw from settled while only one queue has file work Co-Authored-By: Claude Opus 5.5 * fix(desktop): bound how long close waits for queue file work Co-Authored-By: Claude Opus 5.5 * fix(desktop): bound the queue writes given to the worker Captures outpacing the worker kept every event in memory until it was written. Writes past a small window now wait in the queue, where eviction can cancel them. Co-Authored-By: Claude Opus 5.5 * test(desktop): finish queue file work before temp directories are deleted Windows can't delete a directory with a file still open. Co-Authored-By: Claude Opus 5.5 * fix(desktop): complete capture once the event is written, and survive failed queue jobs An awaited capture is on disk again, so awaiting it before exit() keeps the event. A failed write job keeps the event in memory instead of wedging the queue, a flush waits for events still being written, and a failed job during close no longer stops the next setup. Records the unawaited-capture timing as a breaking change. Co-Authored-By: Claude Opus 5.5 * fix(desktop): complete identify, alias, group and setPersonProperties once written Awaiting them before exit() keeps their events, like capture. Without this, identify lost its event for good, since the new id is already saved. Also tests the awaits and the failed close properly, and records the change in the changeset. Co-Authored-By: Claude Opus 5.5 * docs(desktop): state what awaiting a call keeps, and trim comments Co-Authored-By: Claude Opus 5.5 * fix(desktop): guard deferred AI person properties with a reset generation Identifying an anonymous user keeps the person, so comparing distinct ids discarded their properties, and let pre-reset ones back when the same id was identified again. Co-Authored-By: Claude Opus 5.5 * fix(desktop): log when queue work falls back to the UI isolate The frame drops the worker removes would otherwise return with no sign of why. Co-Authored-By: Claude Opus 5.5 * refactor(desktop): keep the gzip choice with the encoded body The bytes and the Content-Encoding header could otherwise disagree. Co-Authored-By: Claude Opus 5.5 * fix(desktop): release the shared worker's logger when its client closes The logger retains the client, and with it any events kept in memory. Co-Authored-By: Claude Opus 5.5 * test(desktop): avoid a protected member in the logger release test Co-Authored-By: Claude Opus 5.5 * docs: fold #688 release notes into the 6.0 docs * fix(desktop): keep events after an unmeasured AI event person-processed An AI event with $set turned on person processing only once the worker had measured it, so an unawaited captureAi followed by capture sent the next event personless. Co-Authored-By: Claude Opus 5.5 * fix(desktop): limit AI events waiting to be written by estimated bytes (#693) * fix(desktop): limit AI events waiting to be written by estimated bytes The count limit alone let unawaited captures of large events hold over a GiB in memory. These events would mostly be evicted by the 50 MiB queue limit once measured, so they are now evicted before that, and captureAi reports them as not queued. Co-Authored-By: Claude Opus 5.5 * fix(desktop): count containers in the waiting-bytes estimate A long list of empty strings otherwise counts as nothing. Co-Authored-By: Claude Opus 5.5 * perf(desktop): keep a running total of waiting bytes Rescanning every waiting event on each capture is quadratic on the UI isolate in a burst of small events. Co-Authored-By: Claude Opus 5.5 * docs: fold #693 release notes into the 6.0 docs --------- Co-authored-by: Claude Opus 5.5 * test(desktop): cover calls made while the queue worker holds its reply (#700) GatedWorker can now hold reads and request bodies too. The new tests make a call while the worker has not answered, then release it: captures, evictions, reset and close during a flush's read or encode, and AI events measured after close or dropped for their size during a flush. Co-authored-by: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --- .changeset/v6-major-release.md | 3 + README.md | 10 +- posthog_flutter/MIGRATION.md | 1 + .../lib/src/core/file_storage.dart | 403 ++++++-- .../lib/src/core/posthog_core.dart | 160 ++- .../lib/src/core/posthog_core_stateless.dart | 191 ++-- .../lib/src/core/queue_worker.dart | 410 ++++++++ posthog_flutter/lib/src/posthog.dart | 7 +- posthog_flutter/lib/src/posthog_config.dart | 2 + .../lib/src/posthog_flutter_desktop.dart | 58 +- .../test/core/capture_ai_test.dart | 22 +- .../test/core/file_queue_test.dart | 12 +- .../test/core/file_storage_test.dart | 2 +- .../test/core/flutter_test_config.dart | 11 + .../test/core/queue_worker_test.dart | 916 ++++++++++++++++++ posthog_flutter/test/core/test_client.dart | 76 +- .../test/posthog_flutter_desktop_test.dart | 125 +++ 17 files changed, 2161 insertions(+), 248 deletions(-) create mode 100644 posthog_flutter/lib/src/core/queue_worker.dart create mode 100644 posthog_flutter/test/core/flutter_test_config.dart create mode 100644 posthog_flutter/test/core/queue_worker_test.dart diff --git a/.changeset/v6-major-release.md b/.changeset/v6-major-release.md index e2230507..d876d643 100644 --- a/.changeset/v6-major-release.md +++ b/.changeset/v6-major-release.md @@ -24,6 +24,7 @@ - **Breaking:** send events to capture v1 (`/i/v1/analytics/events`) instead of `/batch/` on iOS, macOS, Android, Windows and Linux — update your reverse proxy first, see the [iOS](https://github.com/PostHog/posthog-ios/blob/main/MIGRATION.md#hosts-without-capture-v1) and [Android](https://github.com/PostHog/posthog-android/blob/main/docs/migration-3.x-to-4.0.md#hosts-without-capture-v1) migration guides - **Breaking:** retry a 404 on Windows and Linux so events stay queued, printing one warning, also without `debug`, until a reverse proxy or self-hosted instance serves the new path - **Breaking:** drop the batch on a redirect on Windows and Linux, following only same-origin 307 and 308 redirects, and cap a `Retry-After` wait at 30 seconds +- **Breaking:** write events to disk only when the returned future completes on Windows and Linux, so an unawaited call can be lost on a crash or `exit()` — await the call or `Posthog().close()` before `exit()` - **Breaking:** apply SDK properties, then registered properties, then event properties on Windows and Linux, so your value wins for that event, and run `beforeSend` after that merge - **Breaking:** always set `$lib` and `$lib_version` from the `PostHog-Sdk-Info` header on Windows and Linux, ignoring changes made in `beforeSend` - **Breaking:** send person processing as the `process_person_profile: false` option on Windows and Linux, only while it's off, instead of a `$process_person_profile` property on every event @@ -36,6 +37,8 @@ - Drop a batch whose 2xx response has no readable per-event results on Windows and Linux instead of counting it as delivered, without resending it - Log one line per batch that lost events on Windows and Linux, with the endpoint, count and reasons, also for a terminal status, and count a `limited` result as delivered - Back off failed sends on Windows and Linux from 1 second up to 30 seconds with ±25% jitter, instead of resending within the flush, treating `Retry-After` as a floor +- Run queued event encoding, file work and request compression on a background isolate on Windows and Linux so they no longer drop frames +- Limit AI events waiting to be written on Windows and Linux to about 50 MiB in memory, dropping the oldest first and completing `captureAi` with `null` for them - Take an event's timestamp before the `beforeSend` callbacks run on Windows and Linux - Declare Android `minSdkVersion` 23 to match `posthog-android` - Add a `defaultValue` option to `isFeatureEnabled()`, returned when the flag has no value diff --git a/README.md b/README.md index 639fea5b..77659582 100644 --- a/README.md +++ b/README.md @@ -33,10 +33,12 @@ file untouched. A new client can try reading the file again. Corrupt file contents reset the state to defaults; the next state write replaces the file. `Posthog().close()` makes one attempt to send the queued events and waits for it -for up to two seconds. Events it could not send stay on disk and go out with the -next client, or are lost when state is kept in memory. Closing the app window -does not call `close()`, but the SDK also sends the queue whenever the app -becomes inactive. +for up to two seconds, and for the queue's files for up to two more. Events it +could not send stay on disk and go out with the next client, or are lost when +state is kept in memory. Events are written in the background, so await +`close()` before calling `exit()`; awaiting a capture or `identify` call also +keeps that call's event. Closing the app window does not call `close()`, but the +SDK also sends the queue whenever the app becomes inactive. ## Questions? diff --git a/posthog_flutter/MIGRATION.md b/posthog_flutter/MIGRATION.md index e56eb0d4..fcd661c2 100644 --- a/posthog_flutter/MIGRATION.md +++ b/posthog_flutter/MIGRATION.md @@ -250,6 +250,7 @@ A personal API key (`phx_...`) in `projectToken` now skips `setup()` with one lo - **Person processing:** it's sent as the `process_person_profile: false` option only while it's off, instead of a `$process_person_profile` property on every event. - **Redirects:** only same-origin 307 and 308 redirects are followed. Any other redirect drops the batch. - **Retries:** a failed batch waits 1 second, doubling up to 30 seconds with ±25% jitter, instead of retrying within the same flush. `Retry-After` is a floor under that wait, capped at 30 seconds. +- **Writes to disk:** an event is no longer on disk when `capture`, `screen`, `captureException`, `captureFeatureView`, `captureFeatureInteraction`, `identify`, `alias`, `group` or `setPersonProperties` returns, only when the returned future completes. One you didn't await can be lost if the app crashes or calls `exit()` right after. Await the call, or `Posthog().close()`, before `exit()`. Only `close()` also covers events the SDK captures itself, such as `$feature_flag_called`. An `identify` not awaited before `exit()` can lose its `$identify` event for good, because the new ID is already saved. `close()` can now take up to 4 seconds, and a later `setup()` waits for the queue's file work. - **Timestamps:** an event's timestamp is taken before `beforeSend` runs. - **AI queue:** `captureAi` events have their own on-disk queue of up to `captureAiMaxQueueSize` events (100 by default) and 50 MiB. An event over `captureAiMaxEventBytes` (8 MiB plus 64 KiB by default) is dropped. diff --git a/posthog_flutter/lib/src/core/file_storage.dart b/posthog_flutter/lib/src/core/file_storage.dart index 1a535081..8c550457 100644 --- a/posthog_flutter/lib/src/core/file_storage.dart +++ b/posthog_flutter/lib/src/core/file_storage.dart @@ -1,8 +1,13 @@ +import 'dart:async'; import 'dart:convert'; import 'dart:io'; +import 'package:flutter/foundation.dart' + show SynchronousFuture, visibleForTesting; + import 'logger.dart'; import 'persistence.dart'; +import 'queue_worker.dart'; import 'uuid.dart'; /// Client state and queue storage, persistent unless created in memory. @@ -35,16 +40,27 @@ import 'uuid.dart'; /// changes with a snapshot it never saw; a new instance retries the disk. /// Files are replaced through a temporary file and a rename, without syncing /// them to disk: a crash can lose the latest writes but never leaves a file -/// half-written. +/// half-written. Queued events are written by a [QueueWorker] off the UI +/// isolate, so an event can be lost to a crash or `exit()` in the moments +/// after it is queued. The platform's capture and identify calls complete +/// once their event is on disk. class FileStorage { - FileStorage(this._directory); + /// A storage in [_directory]. Its queues give their file work to [worker], + /// a background isolate by default. + FileStorage(this._directory, {QueueWorker? worker}) + : _worker = worker ?? QueueWorker.defaultWorker(); + + /// A storage that keeps everything in memory. Its queues still measure + /// their events with [worker]. + FileStorage.memory({QueueWorker? worker}) + : this._memory(worker ?? QueueWorker.defaultWorker()); - FileStorage.memory() + FileStorage._memory(this._worker) : _directory = '', _cache = {}, _role = _Role.secondary, - _queue = FileEventQueue._memory(), - _aiQueue = FileEventQueue._memory(); + _queue = FileEventQueue._memory(_worker), + _aiQueue = FileEventQueue._memory(_worker); static const _dataFileName = 'posthog_data.json'; static const _lockFileName = 'posthog.lock'; @@ -58,6 +74,7 @@ class FileStorage { static final Set _heldLockPaths = {}; final String _directory; + final QueueWorker _worker; Map? _cache; bool _readFailed = false; @@ -93,15 +110,30 @@ class FileStorage { bool get isDegraded => _readAll() == null; /// The events waiting to be sent. - FileEventQueue get queue => - _queue ??= FileEventQueue._(_pathOf(_queueDirectoryName), () => logger, - includeExisting: _open() == _Role.primary); + FileEventQueue get queue => _queue ??= FileEventQueue._( + _pathOf(_queueDirectoryName), () => logger, _worker, + includeExisting: _open() == _Role.primary); /// The AI events waiting to be sent, apart from the other events. FileEventQueue get aiQueue => _aiQueue ??= FileEventQueue._( - _pathOf(_aiQueueDirectoryName), () => logger, + _pathOf(_aiQueueDirectoryName), () => logger, _worker, includeExisting: _open() == _Role.primary); + /// Does the file work of the queues, and encodes their request bodies. + QueueWorker get worker => _worker; + + /// Completes once both queues have no file work left, so that another + /// storage of the directory finds every event this one queued, and none it + /// removed. + Future get settled async { + // Not Future.wait, which throws on the SynchronousFuture of an idle queue. + await _queue?.settled; + await _aiQueue?.settled; + } + + /// Completes once the analytics events queued so far are on disk. + Future get written => _queue?._submitted ?? SynchronousFuture(null); + /// Decides, on first use, whether this storage writes the snapshot. _Role _open() { final role = _role; @@ -155,10 +187,19 @@ class FileStorage { return code == 11 || code == 13; // EAGAIN or EACCES on Linux } - /// Releases the directory lock, so that another storage can write the - /// snapshot; this one stops writing it. + /// Releases the directory lock once the queues have no file work left, so + /// that another storage can write the snapshot and finds exactly the events + /// still to send; this one stops writing it. void close() { _role = _Role.secondary; + if ((_queue?._jobs.isEmpty ?? true) && (_aiQueue?._jobs.isEmpty ?? true)) { + _releaseLock(); + } else { + settled.whenComplete(_releaseLock).ignore(); + } + } + + void _releaseLock() { final lockPath = _lockPath; if (lockPath != null) _heldLockPaths.remove(lockPath); _lockPath = null; @@ -262,7 +303,7 @@ class FileStorage { void _writeSnapshot(String encoded) { try { - _writeAtomically(File(_dataFilePath), encoded); + writeAtomically(File(_dataFilePath), encoded); } catch (e) { // Best effort: the cache keeps the new value, the next successful // write persists the whole snapshot. @@ -294,12 +335,17 @@ typedef PostHogQueuedEvent = ({String id, Map event}); /// Events are JSON-encodable maps; the client makes them so before adding /// them. The client removes an event by its id once it is delivered, so an /// event added while a batch is in flight is never removed with it. +/// +/// The [QueueWorker] encodes, measures, writes, reads and deletes the files, +/// in the order the queue asks it to. An event takes its place in the queue +/// as soon as it is added, and counts in [byteCount] once the worker has +/// measured it. class FileEventQueue { - FileEventQueue._(this._directory, this._logger, + FileEventQueue._(this._directory, this._logger, this._worker, {required bool includeExisting}) : _loadedIds = includeExisting ? null : []; - FileEventQueue._memory() + FileEventQueue._memory(this._worker) : _directory = '', _logger = _noLogger, _loadedIds = []; @@ -310,15 +356,34 @@ class FileEventQueue { final String _directory; final CoreLogger? Function() _logger; + final QueueWorker _worker; /// The queue, oldest first: the events found in the directory, read on /// first use, then the ones added here. List? _loadedIds; - /// Events whose file could not be written, so they can still be sent by - /// this client. + /// Events whose file could not be written, or that a queue in memory + /// keeps, so they can still be sent by this client. final Map> _unwritten = {}; + /// Events the worker is still measuring and writing. A peek leaves them + /// for later: the worker can still drop one for its size. + final Set _writing = {}; + + /// Events waiting for a free write, oldest first. Eviction can still cancel + /// them, unlike a job the worker was given. + final Map _unsent = {}; + int _unsentBytes = 0; + + /// The most writes the worker holds at once, so that captures outpacing it + /// keep only the events the queue limits allow in memory. + @visibleForTesting + static const maxWritesInFlight = 8; + + var _writesInFlight = 0; + + final Set> _jobs = {}; + /// The serialized size of each queued event, by id, and their total. final Map _sizes = {}; int _byteCount = 0; @@ -367,70 +432,186 @@ class FileEventQueue { return name.substring(0, name.length - _extension.length); } + Future _job(Future job) { + _jobs.add(job); + job.whenComplete(() => _jobs.remove(job)).ignore(); + return job; + } + /// The number of queued events. int get length => _ids.length; - /// The serialized size of the queued events, in bytes. + /// The number of queued events the worker has measured. The others come + /// after them, and can still be dropped for their size. + int get measuredLength => _ids.length - _writing.length; + + /// The serialized size of the measured events, in bytes. int get byteCount { _ids; // Loads the queue, and the sizes, on first use. return _byteCount; } - /// Adds [event] at the end of the queue. [json] is the event already - /// encoded, and [bytes] its UTF-8 size, when the caller has them. - int add(Map event, {String? json, int? bytes}) { + /// Completes once the worker has done every job the queue gave it so far: + /// the added events are measured and written, the removed ones deleted. + Future get settled => + _jobs.isEmpty ? SynchronousFuture(null) : _settle(); + + Future get _submitted => _jobs.isEmpty + ? SynchronousFuture(null) + : Future.wait(_jobs.toList()).then((_) {}); + + Future _settle() async { + // Jobs that finishing jobs start are waited for too. + while (_jobs.isNotEmpty) { + await Future.wait(_jobs.toList()); + } + } + + /// Adds [event] at the end of the queue, and completes with what the + /// worker did with it, or [queueWriteEvicted] when it was removed before it + /// reached the worker. With [maxBytes], an event + /// whose serialized size is over it is removed again and not written. + Future add(Map event, {int? maxBytes}) { // Loaded before the new file exists, which would otherwise be listed // on top of being added. final ids = _ids; final id = generateUuidV7(); - var encoded = json; - if (encoded == null) { - try { - encoded = jsonEncode(event); - } catch (_) { - // Reported below when it is written. - } + ids.add(id); + _writing.add(id); + if (_writesInFlight >= maxWritesInFlight) { + final unsent = _UnsentWrite(event, maxBytes); + _unsent[id] = unsent; + _unsentBytes += unsent.estimatedBytes; + return _job(unsent.result.future); } - final size = bytes ?? (encoded == null ? 0 : utf8.encode(encoded).length); - ids.add(_track(id, size)); - if (_directory.isEmpty) { - _unwritten[id] = event; - return size; + return _job(_write(id, event, maxBytes)); + } + + Future _write( + String id, + Map event, + int? maxBytes, + ) { + _writesInFlight++; + final path = _directory.isEmpty ? null : _pathOf(id); + QueueWriteResult done(QueueWriteResult result) { + _writesInFlight--; + _writeNext(); + _writing.remove(id); + if (result.tooLarge) { + _ids.remove(id); + return result; + } + // Removed while the worker wrote it: the deletion comes after. + if (!_ids.contains(id)) return result; + _track(id, result.bytes ?? 0); + if (path == null) { + _unwritten[id] = event; + } else if (result.error case final error?) { + _unwritten[id] = event; + _logger()?.warn( + 'Failed to persist a queued event; it is kept in memory until it ' + 'is sent:', + error); + } + return result; } - try { - _writeAtomically(File(_pathOf(id)), encoded ?? jsonEncode(event)); - } catch (e) { - _unwritten[id] = event; - _logger()?.warn( - 'Failed to persist a queued event; it is kept in memory until it ' - 'is sent:', - e); + + return _worker.write(path, event, maxBytes: maxBytes).then( + done, + onError: (Object e) => + done((bytes: null, tooLarge: false, error: '$e')), + ); + } + + void _writeNext() { + while (_writesInFlight < maxWritesInFlight && _unsent.isNotEmpty) { + final id = _unsent.keys.first; + final unsent = _unsent.remove(id)!; + _unsentBytes -= unsent.estimatedBytes; + unsent.result.complete(_write(id, unsent.event, unsent.maxBytes)); } - return size; } /// Returns up to [count] events from the front of the queue, oldest - /// first. + /// first, once the events added so far are written. Events added after + /// the call are not waited for, so that sustained captures can't hold back + /// the batch. /// /// With [maxBytes], the events also stay within that serialized size. Each /// event is checked before it is read, so one that does not fit is left /// for the next peek, and the first event always comes, alone when it is /// over the limit. - List peek(int count, {int? maxBytes}) { - final events = []; - final gone = {}; + Future> peek(int count, {int? maxBytes}) => + _submitted.then((_) => _peekWritten(count, maxBytes)); + + Future> _peekWritten( + int count, + int? maxBytes, { + Set skipped = const {}, + }) { + final selected = []; var bytes = 0; for (final id in _ids) { - if (events.length >= count) break; + if (skipped.contains(id)) continue; + if (selected.length >= count || _writing.contains(id)) break; final size = _sizes[id] ?? 0; - if (maxBytes != null && events.isNotEmpty && bytes + size > maxBytes) { + if (maxBytes != null && selected.isNotEmpty && bytes + size > maxBytes) { break; } - final event = _unwritten[id] ?? _read(id, gone); - if (event == null) continue; - events.add((id: id, event: event)); + selected.add(id); bytes += size; } + final toRead = [ + for (final id in selected) + if (!_unwritten.containsKey(id)) id, + ]; + final read = toRead.isEmpty + ? SynchronousFuture(const []) + : _job(_worker.read([for (final id in toRead) _pathOf(id)])); + return read.then((read) { + final events = _collect(selected, { + for (var i = 0; i < toRead.length; i++) toRead[i]: read[i], + }); + // An empty peek ends the flush, which must not leave the events behind + // the unreadable ones unsent. + return events.isEmpty && selected.isNotEmpty + ? _peekWritten(count, maxBytes, skipped: {...skipped, ...selected}) + : events; + }); + } + + /// The [selected] events still queued, from memory or from [read]. + List _collect( + List selected, + Map read, + ) { + final events = []; + final gone = {}; + final queued = _ids.toSet(); + for (final id in selected) { + // Removed while the files were read. + if (!queued.contains(id)) continue; + final event = _unwritten[id]; + if (event != null) { + events.add((id: id, event: event)); + continue; + } + final result = read[id]!; + if (result.event case final event?) { + events.add((id: id, event: event)); + } else if (result.gone) { + // Sent by another client using the same directory, or unreadable + // and deleted. + if (result.error case final error?) { + _logger() + ?.warn('Deleted queued event $id, which cannot be read:', error); + } + gone.add(id); + } else { + _logger()?.warn('Skipping queued event $id for now:', result.error); + } + } if (gone.isNotEmpty) { _ids.removeWhere(gone.contains); gone.forEach(_untrack); @@ -438,48 +619,48 @@ class FileEventQueue { return events; } - /// Reads the event queued as [id], or returns null. An event that is gone - /// for good (sent by another client, or unreadable and so deleted) is also - /// added to [gone]; one that cannot be read right now stays queued. - Map? _read(String id, Set gone) { - final file = File(_pathOf(id)); - try { - final event = jsonDecode(utf8.decode(file.readAsBytesSync())); - if (event is Map) return event; - throw const FormatException('Not a JSON object'); - } on PathNotFoundException { - // Sent by another client using the same directory. - gone.add(id); - } on FormatException catch (e) { - _logger()?.warn('Deleting queued event $id, which cannot be read:', e); - gone.add(id); - _delete(file); - } on FileSystemException catch (e) { - _logger()?.warn('Skipping queued event $id for now:', e); - } - return null; - } - /// Removes the events with the given [ids]; unknown ids are ignored. void remove(Iterable ids) { final removed = ids.toSet(); _ids.removeWhere(removed.contains); - removed.forEach(_forget); + _forget(removed); } /// Removes up to [count] events from the front of the queue. void removeOldest(int count) { final oldest = _ids.take(count).toList(); _ids.removeRange(0, oldest.length); - oldest.forEach(_forget); + _forget(oldest); + } + + /// Removes the oldest events still waiting to be written until at most + /// [maxCount] wait and, with [maxBytes], their estimated sizes add up to at + /// most that, always keeping the newest. Returns how many were removed. + /// + /// Their size is unmeasured, so eviction by [removeOldestOver] can't reach + /// them: this is what bounds a queue with a size limit on its events. + int removeOldestUnsentOver(int maxCount, {int? maxBytes}) { + var waiting = _unsent.length; + var bytes = _unsentBytes; + final evicted = []; + for (final MapEntry(key: id, value: unsent) in _unsent.entries) { + final overBytes = maxBytes != null && bytes > maxBytes && waiting > 1; + if (waiting <= maxCount && !overBytes) break; + evicted.add(id); + waiting--; + bytes -= unsent.estimatedBytes; + } + if (evicted.isNotEmpty) remove(evicted); + return evicted.length; } - /// Removes the oldest events until the queue holds at most [maxBytes], - /// always keeping the newest event. Returns how many were removed. + /// Removes the oldest events until the measured ones hold at most + /// [maxBytes], always keeping the newest measured event. Returns how many + /// were removed. int removeOldestOver(int maxBytes) { var total = byteCount; var count = 0; - while (total > maxBytes && count < _ids.length - 1) { + while (total > maxBytes && count < measuredLength - 1) { total -= _sizes[_ids[count]] ?? 0; count++; } @@ -487,34 +668,50 @@ class FileEventQueue { return count; } - void _forget(String id) { - _untrack(id); - if (_unwritten.remove(id) == null && _directory.isNotEmpty) { - _delete(File(_pathOf(id))); - } - } - - void _delete(File file) { - try { - file.deleteSync(); - } on PathNotFoundException { - // Already deleted by another client using the same directory. - } on FileSystemException catch (e) { - _logger() - ?.warn('Failed to delete a queued event; it may be sent again:', e); + void _forget(Iterable ids) { + final paths = []; + for (final id in ids) { + _untrack(id); + _writing.remove(id); + if (_unsent.remove(id) case final unsent?) { + _unsentBytes -= unsent.estimatedBytes; + unsent.result.complete(queueWriteEvicted); + } else if (_unwritten.remove(id) == null && _directory.isNotEmpty) { + paths.add(_pathOf(id)); + } } + if (paths.isEmpty) return; + _job(_worker.delete(paths)).then((errors) { + for (final error in errors) { + _logger()?.warn( + 'Failed to delete a queued event; it may be sent again:', error); + } + }).ignore(); } } -/// Replaces [file] with [contents] through a temporary file and a rename, so -/// the file never exists half-written. Creates the directory when missing. -void _writeAtomically(File file, String contents) { - final tmp = File('${file.path}.tmp'); - try { - tmp.writeAsStringSync(contents); - } on PathNotFoundException { - tmp.parent.createSync(recursive: true); - tmp.writeAsStringSync(contents); - } - tmp.renameSync(file.path); +final class _UnsentWrite { + _UnsentWrite(this.event, this.maxBytes) + : estimatedBytes = _estimateBytes(event); + + /// About what [value] takes as JSON, without encoding it: encoding is the + /// work kept off the UI isolate. Multi-byte text and escapes count low. + static int _estimateBytes(Object? value) => switch (value) { + final String string => string.length + 2, + final Map map => map.entries.fold( + 2, + (total, entry) => + total + + _estimateBytes(entry.key) + + _estimateBytes(entry.value) + + 2), + final List list => + list.fold(2, (total, element) => total + _estimateBytes(element) + 1), + _ => 8, + }; + + final Map event; + final int estimatedBytes; + final int? maxBytes; + final result = Completer(); } diff --git a/posthog_flutter/lib/src/core/posthog_core.dart b/posthog_flutter/lib/src/core/posthog_core.dart index 903dae8a..1448388a 100644 --- a/posthog_flutter/lib/src/core/posthog_core.dart +++ b/posthog_flutter/lib/src/core/posthog_core.dart @@ -2,6 +2,7 @@ import 'dart:async'; import 'dart:convert'; import 'dart:math'; +import 'package:flutter/foundation.dart' show SynchronousFuture; import 'package:meta/meta.dart'; import '../feature_flag_result.dart'; @@ -41,8 +42,9 @@ abstract class PostHogCore extends PostHogCoreStateless { /// The reload that waits for the /flags request in flight. Completer? _pendingFlagsReload; - /// Changes when reset invalidates responses requested for the previous user. - int _featureFlagsGeneration = 0; + /// Changes when reset ends the current user, invalidating what was requested + /// or captured for them but has not come back yet. + int _resetGeneration = 0; final _session = PostHogSessionManager(); @@ -52,6 +54,20 @@ abstract class PostHogCore extends PostHogCoreStateless { /// The person properties sent last, so that a duplicate `$set` is skipped. String? _cachedPersonProperties; + /// When each flag person property was last set, and when they were last + /// reset, counted in [_personPropertyClock]. An AI event's properties + /// apply only after the worker measured it, and must not overwrite newer + /// values set in the meantime. + var _personPropertyClock = 0; + var _personPropertiesResetAt = 0; + final _personPropertySetAt = {}; + + /// AI events with person properties the worker is still measuring. Events + /// captured meanwhile are person-processed, as they would be after a + /// [capture] with the same properties, even if the size limit then drops + /// the AI event. + var _aiEventsRequestingPerson = 0; + Map _bootstrappedFlags = const {}; Map _bootstrappedPayloads = const {}; @@ -90,7 +106,8 @@ abstract class PostHogCore extends PostHogCoreStateless { /// the configured default; this client keeps the current consent decision. void reset() { wrap(() { - _featureFlagsGeneration++; + _resetGeneration++; + _aiEventsRequestingPerson = 0; _sessionProps.clear(); _flagCallReported.clear(); _cachedPersonProperties = null; @@ -446,20 +463,55 @@ abstract class PostHogCore extends PostHogCoreStateless { /// Unlike [capture], it adds nothing to it. Its `$set` / `$set_once` /// feed flag evaluation. /// - /// With [ai], the event goes to PostHog's AI endpoint from a queue of its - /// own, which drops a serialized event over its size limit. - /// /// Returns the event's uuid, or null when it is not queued: the client - /// is closed or opted out, or the AI event is over the size limit. - String? capturePrepared( + /// is closed or opted out. + Future capturePrepared(String event, PostHogPreparedEvent prepared) { + final queued = wrap>(() { + if (_ignoredWhileOptedOut('posthog.capture')) { + return SynchronousFuture(null); + } + final (:uuid, :queued) = _queuePrepared(event, prepared); + return queued.then((kept) => kept ? uuid : null); + }); + return queued ?? SynchronousFuture(null); + } + + /// Queues an AI event built by [prepareEvent], like [capturePrepared], on + /// the queue of PostHog's AI endpoint, which drops a serialized event over + /// its size limit. + /// + /// Completes with the event's uuid, or null when it is not queued: the + /// client is closed or opted out, or the event is over the size limit or + /// was evicted while waiting to be written. Its person properties apply once it is queued, unless [reset] ran since + /// it was captured. + Future captureAiPrepared( String event, - PostHogPreparedEvent prepared, { - bool ai = false, - }) => - wrap(() { - if (_ignoredWhileOptedOut('posthog.capture')) return null; - return _queuePrepared(event, prepared, ai: ai); + PostHogPreparedEvent prepared, + ) { + final queued = wrap>(() { + if (_ignoredWhileOptedOut('posthog.capture')) { + return SynchronousFuture(null); + } + final (:properties, :options, :timestamp) = prepared; + final generation = _resetGeneration; + final capturedAt = ++_personPropertyClock; + final queued = captureAiStateless(getDistinctId(), event, + properties: properties, options: options, timestamp: timestamp); + final requestsPerson = _requestsPersonProcessing(properties); + if (requestsPerson) _aiEventsRequestingPerson++; + return queued.then((uuid) { + if (uuid != null && generation == _resetGeneration) { + _applyPersonProperties(properties, capturedAt: capturedAt); + } + return uuid; + }).whenComplete(() { + if (requestsPerson && generation == _resetGeneration) { + _aiEventsRequestingPerson--; + } }); + }); + return queued ?? SynchronousFuture(null); + } /// [options] with `process_person_profile: false` added when person /// processing is off and [properties] neither ask for it nor set @@ -495,26 +547,15 @@ abstract class PostHogCore extends PostHogCoreStateless { ); } - String? _queuePrepared( + ({String uuid, Future queued}) _queuePrepared( String event, - PostHogPreparedEvent prepared, { - bool ai = false, - }) { + PostHogPreparedEvent prepared, + ) { final (:properties, :options, :timestamp) = prepared; - final uuid = captureStateless(getDistinctId(), event, - properties: properties, options: options, timestamp: timestamp, ai: ai); - if (uuid == null) return null; - // Taken from the event as queued, after the beforeSend callbacks, so a - // value they removed or an event they or the size limit dropped neither - // reaches /flags nor turns on person processing for later events. - if (_requestsPersonProcessing(properties)) _enablePersonProcessing(); - _setPersonPropertiesForFlagsIfNeeded( - _asPropertyMap(properties[r'$set']), - _asPropertyMap(properties[r'$set_once']), - ); - // PostHog drops an AI event that is not an `$ai_*` event, so it never - // updates the person. - if (!ai && (event == r'$set' || event == r'$identify')) { + final queued = captureStateless(getDistinctId(), event, + properties: properties, options: options, timestamp: timestamp); + _applyPersonProperties(properties); + if (event == r'$set' || event == r'$identify') { final set = properties[r'$set']; final setOnce = properties[r'$set_once']; if ((set is Map || setOnce is Map) && @@ -523,7 +564,31 @@ abstract class PostHogCore extends PostHogCoreStateless { _personPropertiesHash(getDistinctId(), set, setOnce); } } - return uuid; + return queued; + } + + /// Applies the person properties of a queued event with [properties]: + /// taken from the event as queued, after the beforeSend callbacks, so a + /// value they removed or an event they or the size limit dropped neither + /// reaches /flags nor turns on person processing for later events. + /// + /// With [capturedAt], person properties set since then are kept. + void _applyPersonProperties( + Map properties, { + int? capturedAt, + }) { + if (_requestsPersonProcessing(properties)) _enablePersonProcessing(); + final set = _asPropertyMap(properties[r'$set']); + final setOnce = _asPropertyMap(properties[r'$set_once']); + if (capturedAt == null) { + _setPersonPropertiesForFlagsIfNeeded(set, setOnce); + } else if (capturedAt > _personPropertiesResetAt) { + final merged = { + ...?setOnce, + ...?set + }..removeWhere((key, _) => (_personPropertySetAt[key] ?? 0) > capturedAt); + if (merged.isNotEmpty) _mergePersonPropertiesForFlags(merged); + } } /// Creates an alias for a user. An empty [alias] is ignored. @@ -621,19 +686,29 @@ abstract class PostHogCore extends PostHogCoreStateless { /// flags reload sends. void setPersonPropertiesForFlags(Map properties) { wrap(() { - final existing = getPersistedProperty>( - PostHogPersistedProperty.personProperties) ?? - {}; - setPersistedProperty( - PostHogPersistedProperty.personProperties, - {...existing, ...toJsonMap(properties, logger)}, - ); + final now = ++_personPropertyClock; + for (final key in properties.keys) { + _personPropertySetAt[key] = now; + } + _mergePersonPropertiesForFlags(properties); }); } + void _mergePersonPropertiesForFlags(Map properties) { + final existing = getPersistedProperty>( + PostHogPersistedProperty.personProperties) ?? + {}; + setPersistedProperty( + PostHogPersistedProperty.personProperties, + {...existing, ...toJsonMap(properties, logger)}, + ); + } + /// Resets person properties for feature flag evaluation. void resetPersonPropertiesForFlags() { wrap(() { + _personPropertiesResetAt = ++_personPropertyClock; + _personPropertySetAt.clear(); setPersistedProperty(PostHogPersistedProperty.personProperties, null); }); } @@ -691,7 +766,7 @@ abstract class PostHogCore extends PostHogCoreStateless { Future _doFlagsAsync() async { _loadingFlags = true; - final generation = _featureFlagsGeneration; + final generation = _resetGeneration; try { final distinctId = getDistinctId(); final groupsMap = _getGroups(); @@ -723,7 +798,7 @@ abstract class PostHogCore extends PostHogCoreStateless { extraPayload: extraProperties, ); - if (generation != _featureFlagsGeneration) return; + if (generation != _resetGeneration) return; if (result is GetFlagsFailure) { final stored = _getStoredFlagDetails(); @@ -1087,6 +1162,7 @@ abstract class PostHogCore extends PostHogCoreStateless { bool _hasPersonProcessing() { if (_personProfiles == PostHogPersonProfiles.always) return true; if (_personProfiles == PostHogPersonProfiles.never) return false; + if (_aiEventsRequestingPerson > 0) return true; final isIdentified = _isIdentified(); final hasGroups = _getGroups().isNotEmpty; diff --git a/posthog_flutter/lib/src/core/posthog_core_stateless.dart b/posthog_flutter/lib/src/core/posthog_core_stateless.dart index 478a74b7..a2f3f81a 100644 --- a/posthog_flutter/lib/src/core/posthog_core_stateless.dart +++ b/posthog_flutter/lib/src/core/posthog_core_stateless.dart @@ -2,6 +2,7 @@ import 'dart:async'; import 'dart:convert'; import 'dart:io'; import 'dart:math'; +import 'dart:typed_data'; import 'package:flutter/foundation.dart' show debugPrint; import 'package:meta/meta.dart'; @@ -15,6 +16,7 @@ import 'feature_flags.dart'; import 'file_storage.dart'; import 'logger.dart'; import 'persistence.dart'; +import 'queue_worker.dart'; import 'utils/utils.dart'; import 'uuid.dart'; @@ -163,6 +165,7 @@ abstract class PostHogCoreStateless { events = SimpleEventEmitter( onListenerError: (e) => logger.warn('Error in event listener:', e)); storage.logger = logger; + storage.worker.logger = logger; if (config.debug) { debug(true); } @@ -349,20 +352,39 @@ abstract class PostHogCoreStateless { ); } - /// Queues [event] and returns its uuid, or null when it is not queued. - /// With [ai], the event goes to the AI queue, which drops an event over - /// its size limit. + /// Queues [event] and returns its uuid, with whether the queue keeps it. @protected - String? captureStateless( + ({String uuid, Future queued}) captureStateless( + String distinctId, + String event, { + required Map properties, + Map? options, + String? timestamp, + }) => + _enqueue( + _analytics, + 'capture', + _buildPayload( + distinctId: distinctId, + event: event, + properties: properties, + ), + options: options, + timestamp: timestamp, + ); + + /// Queues [event] on the AI queue, and completes with its uuid, or null + /// when it is over the AI event size limit and so not queued. + @protected + Future captureAiStateless( String distinctId, String event, { required Map properties, Map? options, String? timestamp, - bool ai = false, }) { - return _enqueue( - ai ? _ai : _analytics, + final (:uuid, :queued) = _enqueue( + _ai, 'capture', _buildPayload( distinctId: distinctId, @@ -372,6 +394,7 @@ abstract class PostHogCoreStateless { options: options, timestamp: timestamp, ); + return queued.then((kept) => kept ? uuid : null); } @protected @@ -502,11 +525,11 @@ abstract class PostHogCoreStateless { }); } - /// Queues [message] on [lane] and returns its uuid, or null when it is - /// over the lane's event size limit. Its capture v1 [options] are queued - /// with it; the legacy option properties are converted only when the - /// request is built, see [captureV1Event]. - String? _enqueue( + /// Queues [message] on [lane] and returns its uuid, with whether the queue + /// keeps it: the AI queue drops an event over its size limit. Its capture + /// v1 [options] are queued with it; the legacy option properties are + /// converted only when the request is built, see [captureV1Event]. + ({String uuid, Future queued}) _enqueue( _CaptureLane lane, String type, Map message, { @@ -526,47 +549,66 @@ abstract class PostHogCoreStateless { 'uuid': generateUuidV7(), }; - // Measured as queued, before compression. - String? json; - int? bytes; + final queue = lane.queue; final maxEventBytes = lane.maxEventBytes; - if (maxEventBytes != null) { - json = jsonEncode(prepared); - bytes = utf8.encode(json).length; - if (bytes > maxEventBytes) { + // An event that can still be dropped for its size makes room only once + // it is kept, so that it never displaces an older one for nothing. + if (maxEventBytes == null) _makeRoom(lane, queued: queue.length + 1); + final queued = queue.add(prepared, maxBytes: maxEventBytes).then((result) { + if (result == queueWriteEvicted) return false; + if (result.tooLarge) { // Name and size only: AI properties can hold prompts and media. - logger.warn('Dropping AI event ${message['event']} of $bytes bytes, ' - 'over the $maxEventBytes byte limit.'); - return null; + logger.warn('Dropping AI event ${message['event']} of ' + '${result.bytes} bytes, over the $maxEventBytes byte limit.'); + return false; + } + logger.info('$type ${message['event']} queued for ${lane.path}, ' + '${result.bytes} bytes.'); + if (maxEventBytes != null) _makeRoom(lane, queued: queue.measuredLength); + final maxQueueBytes = lane.maxQueueBytes; + if (maxQueueBytes != null && queue.removeOldestOver(maxQueueBytes) > 0) { + logger.warn('Queue is over $maxQueueBytes bytes, the oldest events ' + 'are dropped.'); } - } - final queue = lane.queue; - final overflow = queue.length - lane.maxQueueSize + 1; - if (overflow > 0) { - queue.removeOldest(overflow); - logger.warn('Queue is full, the oldest event is dropped.'); - } - final queuedBytes = queue.add(prepared, json: json, bytes: bytes); - logger.info('$type ${message['event']} queued for ${lane.path}, ' - '$queuedBytes bytes.'); - final maxQueueBytes = lane.maxQueueBytes; - if (maxQueueBytes != null && queue.removeOldestOver(maxQueueBytes) > 0) { - logger.warn('Queue is over $maxQueueBytes bytes, the oldest events are ' - 'dropped.'); - } + events.emit(type, prepared); - events.emit(type, prepared); + // A full request's worth of bytes flushes like flushAt does, so large + // events go out before the queue starts dropping them. + // The count is checked again: a flush that ran into this event while it + // was written ended without it. + if (queue.byteCount >= captureV1MaxBatchBytes || + queue.length >= lane.flushAt) { + _flushBackground(lane); + } + return true; + }, onError: (Object e) { + logger.error('Failed to queue an event:', e); + return false; + }); - // A full request's worth of bytes flushes like flushAt does, so large - // events go out before the queue starts dropping them. - if (queue.length >= lane.flushAt || - queue.byteCount >= captureV1MaxBatchBytes) { - _flushBackground(lane); + // Events over the limit before they are even measured would be evicted + // once they are, unless enough of the newer ones turn out too large. + if (maxEventBytes != null && + queue.removeOldestUnsentOver(lane.maxQueueSize, + maxBytes: lane.maxQueueBytes) > + 0) { + logger.warn('Queue is full, the oldest event is dropped.'); } + if (queue.length >= lane.flushAt) _flushBackground(lane); _scheduleFlush(lane); - return prepared['uuid'] as String; + return (uuid: prepared['uuid'] as String, queued: queued); + } + + /// Drops the oldest events of [lane] when [queued] events are over its + /// limit. + void _makeRoom(_CaptureLane lane, {required int queued}) { + final overflow = queued - lane.maxQueueSize; + if (overflow > 0) { + lane.queue.removeOldest(overflow); + logger.warn('Queue is full, the oldest event is dropped.'); + } } /// The event properties as they are queued and sent: values JSON cannot @@ -654,8 +696,11 @@ abstract class PostHogCoreStateless { // go out with the same flush. The queue sizes the batch before // reading it, so events past the batch are not decoded. final batch = - queue.peek(lane.maxBatchSize, maxBytes: captureV1MaxBatchBytes); + await queue.peek(lane.maxBatchSize, maxBytes: captureV1MaxBatchBytes); + if (_closed) break; if (batch.isEmpty) { + // The next peek waits for the event still being written. + if (queue.measuredLength < queue.length) continue; if (queue.length > 0) _scheduleFlush(lane); break; } @@ -775,12 +820,12 @@ abstract class PostHogCoreStateless { ); lane.pendingIdentity = identity; - final body = jsonEncode({ + final body = await storage.worker.encodeBody({ 'created_at': identity.createdAt, 'batch': [ for (final queued in batch) captureV1Event(queued.event, logger), ], - }); + }, gzip: lane.compression == PostHogCompression.gzip); final headers = { HttpHeaders.authorizationHeader: 'Bearer $_apiKey', 'PostHog-Sdk-Info': '$postHogFlutterSdkName/$postHogFlutterVersion', @@ -845,7 +890,7 @@ abstract class PostHogCoreStateless { Future<({int status, String? body, Duration? retryAfter, String? location})> _fetchCaptureV1( _CaptureLane lane, - String body, + EncodedBody body, Map headers, ) async { final origin = Uri.parse(_host); @@ -854,8 +899,7 @@ abstract class PostHogCoreStateless { final response = await _fetchOnce(url, body, headers: headers, deliveredOnBodyFailure: true, - timeout: lane.timeout, - compression: lane.compression); + timeout: lane.timeout); if (response.status != 307 && response.status != 308) return response; final location = response.location; final target = location == null ? null : url.resolve(location); @@ -880,14 +924,15 @@ abstract class PostHogCoreStateless { required Duration retryDelay, required bool Function(Object error) retryCheck, }) async { + final encoded = _encode(body, _compression); return retriable( () async { - final response = await _fetchOnce(Uri.parse(url), body); + final response = await _fetchOnce(Uri.parse(url), encoded); if (response.status < 200 || response.status >= 300) { throw PostHogFetchHttpError( response.status, response.body ?? '', - body.length, + encoded.length, retryAfter: response.retryAfter, ); } @@ -900,8 +945,7 @@ abstract class PostHogCoreStateless { } /// Sends one request, aborted once it makes no progress for [timeout], - /// [_requestTimeout] by default, and compressed with [compression], the - /// configured one by default. A transport failure is thrown as + /// [_requestTimeout] by default. A transport failure is thrown as /// [PostHogFetchNetworkError], except, with [deliveredOnBodyFailure], one /// that happens after a 2xx status arrived: the response is then returned /// without a body. @@ -913,17 +957,15 @@ abstract class PostHogCoreStateless { String? location, })> _fetchOnce( Uri url, - String body, { + EncodedBody body, { Map headers = const {}, bool deliveredOnBodyFailure = false, Duration timeout = _requestTimeout, - PostHogCompression? compression, }) async { final attempt = _FetchAttempt(timeout, timeout > _responseBodyTimeout ? timeout : _responseBodyTimeout); try { - return await attempt.guard( - _fetch(url, body, attempt, headers, compression ?? _compression)); + return await attempt.guard(_fetch(url, body, attempt, headers)); } catch (e) { final status = attempt.status; if (deliveredOnBodyFailure && @@ -941,6 +983,18 @@ abstract class PostHogCoreStateless { } } + /// [json] as a request body, encoded here: for the small `/flags` + /// requests, which don't wait for the queue's worker. + static EncodedBody _encode(String json, PostHogCompression compression) { + final bytes = utf8.encode(json); + final gzipped = compression == PostHogCompression.gzip; + return ( + payload: gzipped ? Uint8List.fromList(gzip.encode(bytes)) : bytes, + length: bytes.length, + gzipped: gzipped, + ); + } + static Duration? _parseRetryAfter(String? value) { if (value == null) return null; final seconds = int.tryParse(value.trim()); @@ -965,10 +1019,9 @@ abstract class PostHogCoreStateless { String? location, })> _fetch( Uri url, - String body, + EncodedBody body, _FetchAttempt attempt, Map headers, - PostHogCompression compression, ) async { final request = await _httpClient.postUrl(url); attempt.attachRequest(request); @@ -983,14 +1036,10 @@ abstract class PostHogCoreStateless { '$postHogFlutterSdkName/$postHogFlutterVersion') ..set(HttpHeaders.contentTypeHeader, 'application/json'); headers.forEach(request.headers.set); - final bytes = utf8.encode(body); - final List payload; - if (compression == PostHogCompression.gzip) { + if (body.gzipped) { request.headers.set(HttpHeaders.contentEncodingHeader, 'gzip'); - payload = gzip.encode(bytes); - } else { - payload = bytes; } + final payload = body.payload; request.contentLength = payload.length; // In chunks, so the socket taking each one counts as progress: it stops // taking them while its buffers are full. @@ -1018,6 +1067,14 @@ abstract class PostHogCoreStateless { ); } + /// Completes once the queues have no file work left: every event queued + /// so far is on disk, and every event removed is deleted. A client opening + /// the same directory after that finds exactly the events still to send. + Future get settled => storage.settled; + + /// Completes once the analytics events queued so far are on disk. + Future get written => storage.written; + /// Closes the client without sending anything: stops the periodic flush, /// aborts the requests in flight, ignores later calls and releases the /// storage. Queued events stay on disk for the next client; an in-memory @@ -1030,6 +1087,8 @@ abstract class PostHogCoreStateless { lane.retryAfterTimer = null; } _httpClient.close(force: true); + // The worker is shared and outlives this client, which its logger retains. + if (identical(storage.worker.logger, logger)) storage.worker.logger = null; storage.close(); } } diff --git a/posthog_flutter/lib/src/core/queue_worker.dart b/posthog_flutter/lib/src/core/queue_worker.dart new file mode 100644 index 00000000..b4ee23ba --- /dev/null +++ b/posthog_flutter/lib/src/core/queue_worker.dart @@ -0,0 +1,410 @@ +import 'dart:async'; +import 'dart:convert'; +import 'dart:io'; +import 'dart:isolate'; +import 'dart:typed_data'; + +import 'package:flutter/foundation.dart' show SynchronousFuture; +import 'package:meta/meta.dart'; + +import 'logger.dart'; + +/// What [QueueWorker.write] did with an event: its serialized size in +/// bytes, null when it cannot be encoded; whether it was over the size limit +/// and so not written; and the error that kept its file from being written. +typedef QueueWriteResult = ({int? bytes, bool tooLarge, String? error}); + +/// The result of an event removed from its queue before the worker got it. +const QueueWriteResult queueWriteEvicted = + (bytes: null, tooLarge: false, error: null); + +/// A queued event read back by [QueueWorker.read]: the event, or null with +/// the reason. A file that is [gone] was sent by another client, or could +/// not be decoded and was deleted; any other [error] may pass. +typedef QueueReadResult = ({ + Map? event, + bool gone, + String? error, +}); + +/// A request body as it is sent: its [payload], gzipped or not as [gzipped] +/// says, and its UTF-8 [length] before compression. +typedef EncodedBody = ({Uint8List payload, int length, bool gzipped}); + +/// Does the queue work that grows with the size of the events away from the +/// app's UI isolate: encoding events to JSON and measuring them, writing, +/// reading and deleting their files, and encoding and compressing request +/// bodies. An 8 MiB AI event takes tens of milliseconds to encode and write, +/// and over a hundred to compress, which would drop frames. +/// +/// Jobs run one at a time, in the order they were submitted, so a file is +/// deleted only after it is written and read only once it is complete. +abstract class QueueWorker { + /// The worker of every queue in this isolate: a background isolate, + /// started on first use. + static QueueWorker get shared => _shared ??= _IsolateQueueWorker(); + static QueueWorker? _shared; + + /// The worker a storage uses when it is not given one. Tests that drive + /// time with fake timers set it to [QueueWorker.inline]. + static QueueWorker Function() defaultWorker = () => shared; + + /// A worker that runs every job right away on the calling isolate, and + /// returns its result as a [SynchronousFuture], so that a queue using it + /// behaves as if it did its file work itself. Tests that drive time with + /// fake timers use it: messages from another isolate never arrive inside a + /// fake zone. + factory QueueWorker.inline() = _InlineQueueWorker; + + /// A background isolate worker of its own, for tests. + @visibleForTesting + factory QueueWorker.isolate() = _IsolateQueueWorker; + + /// Encodes [event] and writes it to the file at [path], replacing it + /// atomically. Without a [path] the event is only measured. With + /// [maxBytes], an event whose serialized size is over it is not written. + Future write( + String? path, + Map event, { + int? maxBytes, + }); + + /// Reads and decodes the events at [paths], in order. + Future> read(List paths); + + /// Deletes the files at [paths] and returns the errors of the ones that + /// could not be deleted. A file that is already gone is not an error. + Future> delete(List paths); + + /// Encodes [body] to JSON and compresses it with gzip when [gzip] is set. + Future encodeBody(Object? body, {required bool gzip}); + + /// Told when the jobs move back to the calling isolate. The worker is + /// shared, so this is the logger of the client created last, while it is + /// open. + CoreLogger? logger; + + /// Whether the jobs run on another isolate. + @visibleForTesting + bool get runsInBackground; + + /// Stops the background isolate, as if it crashed. Its unanswered jobs, + /// and every later one, then run on the calling isolate. + @visibleForTesting + void kill(); +} + +/// Replaces [file] with [contents] through a temporary file and a rename, so +/// the file never exists half-written. Creates the directory when missing. +void writeAtomically(File file, String contents) { + final tmp = File('${file.path}.tmp'); + try { + tmp.writeAsStringSync(contents); + } on PathNotFoundException { + tmp.parent.createSync(recursive: true); + tmp.writeAsStringSync(contents); + } + tmp.renameSync(file.path); +} + +sealed class _Job { + const _Job(); + + Object? run(); +} + +final class _Write extends _Job { + const _Write(this.path, this.event, this.maxBytes); + + final String? path; + final Map event; + final int? maxBytes; + + @override + QueueWriteResult run() { + final String json; + try { + json = jsonEncode(event); + } catch (e) { + return (bytes: null, tooLarge: false, error: '$e'); + } + final bytes = utf8.encode(json).length; + final maxBytes = this.maxBytes; + if (maxBytes != null && bytes > maxBytes) { + return (bytes: bytes, tooLarge: true, error: null); + } + final path = this.path; + if (path == null) return (bytes: bytes, tooLarge: false, error: null); + try { + writeAtomically(File(path), json); + } catch (e) { + return (bytes: bytes, tooLarge: false, error: '$e'); + } + return (bytes: bytes, tooLarge: false, error: null); + } +} + +final class _Read extends _Job { + const _Read(this.paths); + + final List paths; + + @override + List run() => [for (final path in paths) _readOne(path)]; + + static QueueReadResult _readOne(String path) { + final file = File(path); + try { + final event = jsonDecode(utf8.decode(file.readAsBytesSync())); + if (event is Map) { + return (event: event, gone: false, error: null); + } + throw const FormatException('Not a JSON object'); + } on PathNotFoundException { + return (event: null, gone: true, error: null); + } on FormatException catch (e) { + try { + file.deleteSync(); + } on FileSystemException { + // Read again, and deleted again, by a later run. + } + return (event: null, gone: true, error: '$e'); + } on FileSystemException catch (e) { + return (event: null, gone: false, error: '$e'); + } + } +} + +final class _Delete extends _Job { + const _Delete(this.paths); + + final List paths; + + @override + List run() { + final errors = []; + for (final path in paths) { + try { + File(path).deleteSync(); + } on PathNotFoundException { + // Already deleted by another client using the same directory. + } on FileSystemException catch (e) { + errors.add('$e'); + } + } + return errors; + } +} + +final class _EncodeBody extends _Job { + const _EncodeBody(this.body, this.compress); + + final Object? body; + final bool compress; + + @override + EncodedBody run() { + final bytes = utf8.encode(jsonEncode(body)); + return ( + payload: compress ? Uint8List.fromList(gzip.encode(bytes)) : bytes, + length: bytes.length, + gzipped: compress, + ); + } +} + +/// Turns the [QueueWorker] calls into jobs for [submit]. +abstract class _JobRunner implements QueueWorker { + @override + CoreLogger? logger; + + Future submit(_Job job); + + Future _submit(_Job job) => submit(job).then((result) => result as T); + + @override + Future write( + String? path, + Map event, { + int? maxBytes, + }) => + _submit(_Write(path, event, maxBytes)); + + @override + Future> read(List paths) => + _submit(_Read(paths)); + + @override + Future> delete(List paths) => _submit(_Delete(paths)); + + @override + Future encodeBody(Object? body, {required bool gzip}) => + _submit(_EncodeBody(body, gzip)); +} + +final class _InlineQueueWorker extends _JobRunner { + @override + void kill() {} + + @override + Future submit(_Job job) { + try { + return SynchronousFuture(job.run()); + } catch (e, s) { + return Future.error(e, s); + } + } + + @override + bool get runsInBackground => false; +} + +/// Runs the jobs on a background isolate of the same isolate group, so +/// the strings of an event go there without being copied. Falls +/// back to the calling isolate for good when the isolate cannot be started +/// or exits, running again the jobs it had not answered: every job can run +/// twice without harm. +final class _IsolateQueueWorker extends _JobRunner { + _IsolateQueueWorker() { + _results + ..handler = _onResult + ..keepIsolateAlive = false; + } + + final _results = RawReceivePort(null, 'PostHog queue results'); + final _pending = completer})>{}; + var _nextId = 0; + Future? _port; + Isolate? _isolate; + var _inline = false; + + @override + bool get runsInBackground => !_inline; + + @override + void kill() => _isolate?.kill(priority: Isolate.immediate); + + @override + Future submit(_Job job) { + final id = _nextId++; + final completer = Completer(); + _pending[id] = (job: job, completer: completer); + // Unanswered jobs keep the app's isolate alive, so a command-line app + // doesn't exit with events half-written; an idle worker doesn't. + _results.keepIsolateAlive = true; + // Chained on one future, so the jobs reach the worker in order, also + // while it starts. + (_port ??= _start()).then((port) { + if (port == null) { + _runInline(id); + } else { + port.send((id, job)); + } + }); + return completer.future; + } + + Future _start() async { + final ready = Completer(); + _onReady = ready.complete; + final exit = RawReceivePort(null, 'PostHog queue exit') + ..keepIsolateAlive = false; + exit.handler = (_) { + exit.close(); + _fallBack(); + if (!ready.isCompleted) ready.complete(null); + }; + try { + _isolate = await Isolate.spawn(_workerMain, _results.sendPort, + debugName: 'PostHog queue', onExit: exit.sendPort); + } catch (e) { + logger?.warn( + 'Cannot start the background isolate, the queue work runs on the ' + 'UI isolate:', + e); + exit.close(); + _inline = true; + return null; + } + return ready.future; + } + + void Function(SendPort)? _onReady; + + void _onResult(Object? message) { + if (message is SendPort) { + _onReady?.call(message); + _onReady = null; + return; + } + final (id, ok, value) = message! as (int, bool, Object?); + final pending = _pending.remove(id); + if (_pending.isEmpty) _results.keepIsolateAlive = false; + if (pending == null) return; + if (ok) { + pending.completer.complete( + value is TransferableTypedData ? _materialize(value) : value); + } else { + pending.completer.completeError(value!); + } + } + + /// Rebuilds the body the worker sent back without copying its bytes. + static EncodedBody _materialize(TransferableTypedData payload) { + final bytes = payload.materialize(); + final header = bytes.asByteData(0, 5); + return ( + payload: bytes.asUint8List(5), + length: header.getUint32(0), + gzipped: header.getUint8(4) == 1, + ); + } + + void _fallBack() { + logger?.warn('The background isolate stopped, the queue work runs on the ' + 'UI isolate.'); + _inline = true; + _port = Future.value(null); + for (final id in _pending.keys.toList()..sort()) { + _runInline(id); + } + } + + void _runInline(int id) { + final pending = _pending.remove(id); + if (_pending.isEmpty) _results.keepIsolateAlive = false; + if (pending == null) return; + try { + pending.completer.complete(pending.job.run()); + } catch (e, s) { + pending.completer.completeError(e, s); + } + } + + static void _workerMain(SendPort results) { + final jobs = RawReceivePort(null, 'PostHog queue jobs'); + jobs.handler = (Object? message) { + final (id, job) = message! as (int, _Job); + try { + final result = job.run(); + results.send(( + id, + true, + result is EncodedBody ? _transferable(result) : result, + )); + } catch (e) { + results.send((id, false, '$e')); + } + }; + results.send(jobs.sendPort); + } + + /// [body] as one transferable buffer: its length before compression in + /// 4 bytes, whether it is gzipped in 1, then its payload. + static TransferableTypedData _transferable(EncodedBody body) { + final header = ByteData(5) + ..setUint32(0, body.length) + ..setUint8(4, body.gzipped ? 1 : 0); + return TransferableTypedData.fromList([header, body.payload]); + } +} diff --git a/posthog_flutter/lib/src/posthog.dart b/posthog_flutter/lib/src/posthog.dart index 6c6a27c8..cda82522 100644 --- a/posthog_flutter/lib/src/posthog.dart +++ b/posthog_flutter/lib/src/posthog.dart @@ -1142,9 +1142,10 @@ class Posthog { /// Returns a [Future] that completes when platform resources have been closed. /// /// **Windows/Linux:** first makes one attempt to send the queued events and - /// waits for it for up to two seconds. Events left unsent go out with the - /// next [setup], or are lost when the application support directory is - /// unavailable and state is kept in memory. + /// waits for it for up to two seconds, and for the queue's files for up to + /// two more. Events left unsent go out with the next [setup], or are lost + /// when the application support directory is unavailable and state is kept + /// in memory. /// /// **Note:** After calling `close()`, surveys will not be rendered until the /// SDK is re-initialized and the next navigation event occurs. diff --git a/posthog_flutter/lib/src/posthog_config.dart b/posthog_flutter/lib/src/posthog_config.dart index bb51bb6a..4d4f5ea9 100644 --- a/posthog_flutter/lib/src/posthog_config.dart +++ b/posthog_flutter/lib/src/posthog_config.dart @@ -211,6 +211,8 @@ class PostHogConfig { /// [maxQueueSize]. The queue also keeps at most 50 MiB of AI events, /// whatever this is set to. A value of `0` or less uses the default. /// + /// When it is full, the oldest events are dropped. + /// /// Not applied on web, where [Posthog.captureAi] sends nothing. /// /// Defaults to `null`, which keeps the SDK default. diff --git a/posthog_flutter/lib/src/posthog_flutter_desktop.dart b/posthog_flutter/lib/src/posthog_flutter_desktop.dart index 6bd631da..55f8f010 100644 --- a/posthog_flutter/lib/src/posthog_flutter_desktop.dart +++ b/posthog_flutter/lib/src/posthog_flutter_desktop.dart @@ -228,6 +228,7 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { userPropertiesSetOnce: _normalize(userPropertiesSetOnce), options: cleanEventOptions(options), ); + return client.written; }); @override @@ -242,6 +243,7 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { userPropertiesToSetOnce: _normalize(userPropertiesToSetOnce), options: cleanEventOptions(options), ); + return client.written; }); @override @@ -279,7 +281,7 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { final current = _clientForContinuation('capture', scope, distinctId); if (current == null) return; - _captureProcessed(current, processed, exceptionSteps, prepared); + await _captureProcessed(current, processed, exceptionSteps, prepared); }); @override @@ -365,7 +367,7 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { // A renamed event is no longer a screen view. if (processed.event != PostHogEventName.screen) { - _captureProcessed(current, processed, exceptionSteps, prepared); + await _captureProcessed(current, processed, exceptionSteps, prepared); return; } @@ -381,7 +383,7 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { current.registerForSession( {PostHogPropertyName.screenName: finalScreenName}); } - _captureProcessed(current, processed, exceptionSteps, prepared); + await _captureProcessed(current, processed, exceptionSteps, prepared); }); /// Structured logs are not supported on the desktop implementation. @@ -423,10 +425,10 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { Future alias({required String alias, Map? options}) => _guard( 'alias', - (client) => client.alias( - alias, - options: cleanEventOptions(options), - ), + (client) { + client.alias(alias, options: cleanEventOptions(options)); + return client.written; + }, ); @override @@ -566,6 +568,7 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { groupProperties: _normalize(groupProperties), options: cleanEventOptions(options), ); + return client.written; }); @override @@ -642,7 +645,7 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { final current = _clientForContinuation('captureException', scope, distinctId); if (current == null) return; - _captureProcessed(current, processed, exceptionSteps, prepared); + await _captureProcessed(current, processed, exceptionSteps, prepared); }); @override @@ -670,15 +673,23 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { _featureFlagsUnsubscribe?.call(); _featureFlagsUnsubscribe = null; - return _previousClose = _closeClient(client); + _previousClose = _closeClient(client); }); - // A repeated close() also waits until the queue is sent. - await _previousClose; + // A repeated close() also waits until the queue is sent. Stalled storage + // doesn't hold up the app's shutdown, only the next setup(). + try { + await _previousClose.timeout(_closeTimeout); + } catch (e) { + printIfDebug('[PostHog] Queue file work left unfinished on close: $e'); + } } /// How long close() waits for the queue to be sent. static const _closeFlushTimeout = Duration(seconds: 2); + /// How long close() waits in all, with the queue's file work. + static const _closeTimeout = Duration(seconds: 4); + /// Makes one bounded attempt to send the queue, then closes [client]. /// Events left unsent stay on disk for the next client, or are lost when /// the storage is in memory. Nothing is sent while PostHog asked to wait @@ -690,6 +701,13 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { printIfDebug('[PostHog] Events left unsent on close: $e'); } client.close(); + try { + // The next client reads the directory only once this one's files are + // written and deleted, so it neither misses an event nor sends one again. + await client.settled; + } catch (e) { + printIfDebug('[PostHog] Queue file work failed on close: $e'); + } } @override @@ -816,7 +834,7 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { /// with [ai], and returns its uuid, or null when it is not queued. The /// client adds nothing to it; an `$exception` event gets the exception /// steps recorded up to now. - String? _captureProcessed( + FutureOr _captureProcessed( DesktopPostHog client, PostHogEvent event, ExceptionStepsBuffer? exceptionSteps, @@ -844,14 +862,14 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { options = client.personProcessingOptions( {...?options}..remove('process_person_profile'), properties); } - return client.capturePrepared( - event.event, - ( - properties: properties, - options: options, - timestamp: prepared.timestamp, - ), - ai: ai); + final queued = ( + properties: properties, + options: options, + timestamp: prepared.timestamp, + ); + return ai + ? client.captureAiPrepared(event.event, queued) + : client.capturePrepared(event.event, queued); } /// Whether [event] has a name; an event without one is dropped. diff --git a/posthog_flutter/test/core/capture_ai_test.dart b/posthog_flutter/test/core/capture_ai_test.dart index d63c33fa..2e8c5f33 100644 --- a/posthog_flutter/test/core/capture_ai_test.dart +++ b/posthog_flutter/test/core/capture_ai_test.dart @@ -21,12 +21,12 @@ String? captureAi( final prepared = client.prepareEvent(event, properties: properties); return prepared == null ? null - : client.capturePrepared(event, prepared, ai: true); + : now(client.captureAiPrepared(event, prepared)); } /// The queued AI events, oldest first. List> aiQueue(FileStorage storage) => [ - for (final queued in storage.aiQueue.peek(storage.aiQueue.length)) + for (final queued in now(storage.aiQueue.peek(storage.aiQueue.length))) queued.event, ]; @@ -146,6 +146,24 @@ void main() { ); }); + test('an oversized AI event does not displace a queued one', () { + final storage = tempStorage(); + final client = testClient(server, + config: testConfig() + ..captureAiMaxQueueSize = 1 + ..captureAiMaxEventBytes = 1000, + storage: storage); + + captureAi(client, r'$ai_span', properties: {'i': 0}); + captureAi(client, r'$ai_span', properties: {'input': filler(2000)}); + + expect([ + for (final event in aiQueue(storage)) (event['properties']! as Map)['i'] + ], [ + 0 + ]); + }); + test('keeps captureAiMaxQueueSize AI events, apart from maxQueueSize', () { final storage = tempStorage(); final client = testClient(server, diff --git a/posthog_flutter/test/core/file_queue_test.dart b/posthog_flutter/test/core/file_queue_test.dart index 61ddcb43..e43abe71 100644 --- a/posthog_flutter/test/core/file_queue_test.dart +++ b/posthog_flutter/test/core/file_queue_test.dart @@ -66,7 +66,7 @@ void main() { addTearDown(next.close); final restored = next.queue; expect(restored.byteCount, size(second) + size(third)); - restored.remove([restored.peek(1).single.id]); + restored.remove([now(restored.peek(1)).single.id]); expect(restored.byteCount, size(third)); }); @@ -88,21 +88,21 @@ void main() { test('stops before the event that would pass the limit', () { final queue = queueOf(['a' * 10, 'b' * 10, 'c' * 10]); - expect( - paddingsOf(queue.peek(10, maxBytes: 18 * 2)), ['a' * 10, 'b' * 10]); + expect(paddingsOf(now(queue.peek(10, maxBytes: 18 * 2))), + ['a' * 10, 'b' * 10]); }); test('returns an event over the limit alone', () { final queue = queueOf(['a' * 100, 'b']); - expect(paddingsOf(queue.peek(10, maxBytes: 50)), ['a' * 100]); + expect(paddingsOf(now(queue.peek(10, maxBytes: 50))), ['a' * 100]); }); test('counts UTF-8 bytes, not characters', () { // 18 characters but 28 bytes each. final queue = queueOf(['é' * 10, 'è' * 10]); - expect(paddingsOf(queue.peek(10, maxBytes: 18 * 2)), ['é' * 10]); + expect(paddingsOf(now(queue.peek(10, maxBytes: 18 * 2))), ['é' * 10]); }); test('does not read the events past the limit', () { @@ -110,7 +110,7 @@ void main() { // Unreadable: a peek that read it would delete it. final second = _queueFiles(dir).last..writeAsStringSync('not json'); - expect(paddingsOf(queue.peek(10, maxBytes: 18)), ['a' * 10]); + expect(paddingsOf(now(queue.peek(10, maxBytes: 18))), ['a' * 10]); expect(second.existsSync(), isTrue); }); }); diff --git a/posthog_flutter/test/core/file_storage_test.dart b/posthog_flutter/test/core/file_storage_test.dart index 3aadbe1c..6ac4127e 100644 --- a/posthog_flutter/test/core/file_storage_test.dart +++ b/posthog_flutter/test/core/file_storage_test.dart @@ -18,7 +18,7 @@ void main() { expect(storage.getProperty(PostHogPersistedProperty.optedOut), isTrue); - final queued = storage.queue.peek(1).single; + final queued = now(storage.queue.peek(1)).single; expect(queued.event['event'], 'captured'); storage.queue.removeOldest(1); storage.queue.remove([queued.id]); diff --git a/posthog_flutter/test/core/flutter_test_config.dart b/posthog_flutter/test/core/flutter_test_config.dart new file mode 100644 index 00000000..3a378bf2 --- /dev/null +++ b/posthog_flutter/test/core/flutter_test_config.dart @@ -0,0 +1,11 @@ +import 'dart:async'; + +import 'package:posthog_flutter/src/core/queue_worker.dart'; + +/// Core tests drive time with fake timers, in which messages from the +/// queue's background isolate never arrive, so their queues run the worker's +/// jobs inline. `queue_worker_test.dart` covers the background isolate. +Future testExecutable(FutureOr Function() testMain) async { + QueueWorker.defaultWorker = QueueWorker.inline; + await testMain(); +} diff --git a/posthog_flutter/test/core/queue_worker_test.dart b/posthog_flutter/test/core/queue_worker_test.dart new file mode 100644 index 00000000..3e324e19 --- /dev/null +++ b/posthog_flutter/test/core/queue_worker_test.dart @@ -0,0 +1,916 @@ +import 'dart:async'; +import 'dart:convert'; +import 'dart:io'; + +import 'package:flutter/foundation.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:posthog_flutter/src/core/file_storage.dart'; +import 'package:posthog_flutter/src/core/logger.dart'; +import 'package:posthog_flutter/src/core/persistence.dart'; +import 'package:posthog_flutter/src/core/posthog_core.dart'; +import 'package:posthog_flutter/src/core/queue_worker.dart'; +import 'package:posthog_flutter/src/posthog_desktop_client.dart'; + +import '../posthog_api_fake.dart'; + +import 'test_client.dart'; + +void main() { + late Directory dir; + late QueueWorker worker; + + setUp(() { + dir = tempDirectory(); + worker = QueueWorker.isolate(); + }); + + String pathOf(String name) => '${dir.path}${Platform.pathSeparator}$name'; + + group('QueueWorker.isolate', () { + test('writes an event on a background isolate and reports its size', + () async { + final event = {'event': 'é', 'n': 1}; + + final result = await worker.write(pathOf('a.json'), event); + + expect(worker.runsInBackground, isTrue); + expect(result.bytes, utf8.encode(jsonEncode(event)).length); + expect(result.tooLarge, isFalse); + expect(result.error, isNull); + expect(jsonDecode(File(pathOf('a.json')).readAsStringSync()), event); + }); + + test('measures an event without writing it when it has no path', () async { + final result = await worker.write(null, {'event': 'x'}); + + expect(result.bytes, '{"event":"x"}'.length); + expect(dir.listSync(), isEmpty); + }); + + test('does not write an event over maxBytes', () async { + final result = + await worker.write(pathOf('a.json'), {'p': 'x' * 100}, maxBytes: 50); + + expect(result.tooLarge, isTrue); + expect(result.bytes, greaterThan(50)); + expect(File(pathOf('a.json')).existsSync(), isFalse); + }); + + test('reports an event that cannot be encoded', () async { + final result = await worker.write(pathOf('a.json'), {'p': double.nan}); + + expect(result.bytes, isNull); + expect(result.error, isNotNull); + expect(File(pathOf('a.json')).existsSync(), isFalse); + }); + + test('reports a write that fails', () async { + final blocker = File(pathOf('blocker'))..writeAsStringSync(''); + + final result = + await worker.write('${blocker.path}/a.json', {'event': 'x'}); + + expect(result.error, isNotNull); + expect(result.bytes, isNotNull); + }); + + test('runs jobs in the order they were submitted', () async { + // Not awaited one by one: the deletes must still come after the writes. + final jobs = >[]; + for (var i = 0; i < 20; i++) { + jobs.add(worker.write(pathOf('$i.json'), {'i': i})); + } + jobs.add(worker.delete([for (var i = 0; i < 10; i++) pathOf('$i.json')])); + jobs.add(worker.write(pathOf('0.json'), {'i': 'again'})); + await Future.wait(jobs); + + final names = [ + for (final file in dir.listSync()) file.uri.pathSegments.last, + ]..sort(); + expect( + names, + [ + '0.json', + for (var i = 10; i < 20; i++) '$i.json', + ]..sort()); + expect(jsonDecode(File(pathOf('0.json')).readAsStringSync()), + {'i': 'again'}); + }); + + test('reads events, and deletes the ones that cannot be decoded', () async { + File(pathOf('good.json')).writeAsStringSync('{"event":"good"}'); + File(pathOf('bad.json')).writeAsStringSync('not json'); + File(pathOf('list.json')).writeAsStringSync('[1]'); + + final results = await worker.read([ + pathOf('good.json'), + pathOf('bad.json'), + pathOf('list.json'), + pathOf('missing.json'), + ]); + + expect(results[0].event, {'event': 'good'}); + expect([for (final r in results.skip(1)) r.gone], [true, true, true]); + expect(results[1].error, isNotNull); + expect(results[3].error, isNull); + expect(File(pathOf('bad.json')).existsSync(), isFalse); + expect(File(pathOf('list.json')).existsSync(), isFalse); + }); + + test('ignores a file that is already deleted', () async { + expect(await worker.delete([pathOf('missing.json')]), isEmpty); + }); + + test('logs when the work moves back to the calling isolate', () async { + final lines = []; + final previous = debugPrint; + debugPrint = (message, {wrapWidth}) => lines.add(message ?? ''); + addTearDown(() => debugPrint = previous); + worker.logger = CoreLogger((log) => log()); + await worker.write(pathOf('before.json'), {'i': 0}); + + worker.kill(); + await worker.write(pathOf('after.json'), {'i': 1}); + + expect(lines, contains(contains('background isolate stopped'))); + }); + + test('encodes and gzips a request body', () async { + final body = { + 'batch': [ + {'p': 'é' * 1000}, + ], + }; + final json = utf8.encode(jsonEncode(body)); + + final gzipped = await worker.encodeBody(body, gzip: true); + final plain = await worker.encodeBody(body, gzip: false); + + expect(gzipped.gzipped, isTrue); + expect(plain.gzipped, isFalse); + expect(gzipped.length, json.length); + expect(gzip.decode(gzipped.payload), json); + expect(plain.payload, json); + expect(plain.length, json.length); + }); + + test( + 'runs the jobs it had not answered on the calling isolate when it ' + 'stops', () async { + await worker.write(pathOf('before.json'), {'i': 0}); + + worker.kill(); + final results = await Future.wait([ + for (var i = 0; i < 5; i++) worker.write(pathOf('$i.json'), {'i': i}), + ]); + + expect(worker.runsInBackground, isFalse); + expect([for (final r in results) r.error], everyElement(isNull)); + for (var i = 0; i < 5; i++) { + expect(File(pathOf('$i.json')).existsSync(), isTrue); + } + await worker.delete([pathOf('0.json')]); + expect(File(pathOf('0.json')).existsSync(), isFalse); + }); + }); + + group('FileEventQueue with a background worker', () { + FileStorage storage() { + final storage = FileStorage(dir.path, worker: worker); + addTearDown(storage.close); + return storage; + } + + List queueFiles() => Directory(pathOf('posthog_queue')).existsSync() + ? Directory(pathOf('posthog_queue')) + .listSync() + .whereType() + .toList() + : []; + + test('takes the event in the queue at once and counts it once written', + () async { + final queue = storage().queue; + + final added = queue.add({'event': 'a'}); + + expect(queue.length, 1); + expect((await added).bytes, '{"event":"a"}'.length); + expect(queue.byteCount, '{"event":"a"}'.length); + expect(queueFiles(), hasLength(1)); + }); + + test('a peek waits for the events being written', () async { + final queue = storage().queue; + for (var i = 0; i < 10; i++) { + queue.add({'i': i}); + } + + final events = await queue.peek(100); + + expect([for (final queued in events) queued.event['i']], + List.generate(10, (i) => i)); + expect(queueFiles(), hasLength(10)); + }); + + test('a peek does not wait for events added after it', () async { + final queue = storage().queue; + queue.add({'i': 0}); + var peeked = false; + var next = 1; + void keepAdding() { + if (!peeked) queue.add({'i': next++}).then((_) => keepAdding()); + } + + keepAdding(); + final events = await queue.peek(1); + peeked = true; + await queue.settled; + + expect(events.single.event['i'], 0); + }); + + test('a peek leaves an event that can still be dropped for its size', + () async { + final queue = storage().queue; + queue.add({'i': 0}); + + final peek = queue.peek(100); + queue.add({'i': 'x' * 100}, maxBytes: 10); + + expect([for (final queued in await peek) queued.event['i']], [0]); + }); + + test('a peek goes on past events it cannot read', () async { + final queue = storage().queue; + await queue.add({'i': 0}); + await queue.add({'i': 1}); + await queue.add({'i': 2}); + final files = queueFiles()..sort((a, b) => a.path.compareTo(b.path)); + files[0].writeAsStringSync('{"i":'); + files[1].deleteSync(); + Directory(files[1].path).createSync(); + + final events = await queue.peek(1); + + expect(events.single.event['i'], 2); + expect(files[0].existsSync(), isFalse); + expect(queue.length, 2); + }); + + test('reads events written by an earlier storage', () async { + final first = storage(); + for (var i = 0; i < 3; i++) { + first.queue.add({'i': i}); + } + await first.settled; + first.close(); + + final next = FileStorage(dir.path, worker: worker); + addTearDown(next.close); + final events = await next.queue.peek(10); + + expect([for (final queued in events) queued.event['i']], [0, 1, 2]); + }); + + test('an event removed while it is written leaves no file', () async { + final queue = storage().queue; + queue.add({'event': 'a'}); + + queue.removeOldest(1); + await queue.settled; + + expect(queue.length, 0); + expect(queue.byteCount, 0); + expect(queueFiles(), isEmpty); + }); + + test('drops an event over maxBytes without writing it', () async { + final queue = storage().queue; + + final result = await queue.add({'p': 'x' * 100}, maxBytes: 50); + + expect(result.tooLarge, isTrue); + expect(queue.length, 0); + expect(queueFiles(), isEmpty); + }); + + test('keeps an event it cannot write in memory', () async { + // A file where the queue directory should be fails every write. + File(pathOf('posthog_queue')).writeAsStringSync(''); + final queue = storage().queue; + + final result = await queue.add({'event': 'a'}); + + expect(result.error, isNotNull); + expect(queue.byteCount, '{"event":"a"}'.length); + expect([for (final queued in await queue.peek(10)) queued.event['event']], + ['a']); + }); + + test('close keeps the directory locked until the file work is done', + () async { + String? stored() => FileStorage(dir.path) + .getProperty(PostHogPersistedProperty.distinctId); + final first = FileStorage(dir.path, worker: worker); + first.queue.add({'event': 'a'}); + + first.close(); + final during = storage() + ..setProperty(PostHogPersistedProperty.distinctId, 'during'); + expect(stored(), isNull); + + await first.settled; + during.close(); + storage().setProperty(PostHogPersistedProperty.distinctId, 'after'); + expect(stored(), 'after'); + }); + + group('while the worker is behind', () { + const inFlight = FileEventQueue.maxWritesInFlight; + const burst = inFlight + 12; + late GatedWorker gated; + late FileStorage gatedStorage; + + setUp(() { + gated = GatedWorker()..writeGate = Completer(); + gatedStorage = FileStorage(dir.path, worker: gated); + addTearDown(gatedStorage.close); + addTearDown(() async { + if (!gated.writeGate!.isCompleted) gated.writeGate!.complete(); + await gatedStorage.settled; + }); + for (var i = 0; i < burst; i++) { + gatedStorage.queue.add({'i': i}); + } + }); + + test('gives it a bounded number of writes', () { + expect(gated.writes, inFlight); + expect(gatedStorage.queue.length, burst); + }); + + test('never writes an evicted event that was not sent', () async { + gatedStorage.queue.removeOldest(inFlight + 7); + gated.writeGate!.complete(); + await gatedStorage.settled; + + expect(gated.writes, inFlight + 5); + expect(queueFiles(), hasLength(5)); + expect(gatedStorage.queue.length, 5); + }); + + test('removes the oldest unsent events over an estimated size', () async { + final queue = gatedStorage.queue; + queue.removeOldestUnsentOver(0); + for (var i = 0; i < 3; i++) { + queue.add({'p': 'x' * 100}); + } + + expect(queue.removeOldestUnsentOver(100, maxBytes: 250), 1); + expect(queue.removeOldestUnsentOver(100, maxBytes: 1), 1); + expect(queue.removeOldestUnsentOver(100, maxBytes: 1), 0); + }); + + test('keeps the estimated size of unsent events as they leave', () async { + final queue = gatedStorage.queue; + void addTwo() { + for (var i = 0; i < 2; i++) { + queue.add({'p': 'x' * 100}); + } + } + + // Evicted ones leave the total. + addTwo(); + queue.removeOldestUnsentOver(2); + expect(queue.removeOldestUnsentOver(100, maxBytes: 250), 0); + + // So do the ones sent to the worker. + gated.writeGate!.complete(); + await gatedStorage.settled; + gated.writeGate = Completer(); + for (var i = 0; i < inFlight; i++) { + queue.add({'i': i}); + } + addTwo(); + expect(queue.removeOldestUnsentOver(100, maxBytes: 250), 0); + gated.writeGate!.complete(); + }); + + test('counts the containers of unsent events in their estimated size', + () async { + final queue = gatedStorage.queue; + queue.removeOldestUnsentOver(0); + for (var i = 0; i < 2; i++) { + queue.add({'p': List.filled(100, '')}); + } + + expect(queue.removeOldestUnsentOver(100, maxBytes: 500), 1); + }); + + test('removes the oldest unsent events over a count', () async { + expect(gatedStorage.queue.removeOldestUnsentOver(3), 9); + gated.writeGate!.complete(); + + final events = await gatedStorage.queue.peek(burst); + + expect([ + for (final queued in events) queued.event['i'] + ], [ + ...List.generate(inFlight, (i) => i), + burst - 3, + burst - 2, + burst - 1 + ]); + }); + + test('writes the unsent events after close', () async { + gatedStorage.close(); + gated.writeGate!.complete(); + await gatedStorage.settled; + + expect(queueFiles(), hasLength(burst)); + }); + }); + + test('settled waits for one queue while the other is idle', () async { + final both = storage(); + both.aiQueue; + both.queue.add({'event': 'a'}); + + await both.settled; + + expect(queueFiles(), hasLength(1)); + }); + + test('settled waits for the deletions', () async { + final queue = storage().queue; + for (var i = 0; i < 5; i++) { + queue.add({'i': i}); + } + await queue.settled; + + queue.remove([for (final queued in await queue.peek(5)) queued.id]); + await queue.settled; + + expect(queueFiles(), isEmpty); + }); + }); + + group('PostHogCore with a background worker', () { + test('a closed client leaves the logger of a newer client on the worker', + () async { + final server = await LocalPostHogServer.start(); + final older = testClient(server, + storage: FileStorage(pathOf('older'), worker: worker)); + final newer = testClient(server, + storage: FileStorage(pathOf('newer'), worker: worker)); + + older.close(); + expect(worker.logger, isNotNull); + + newer.close(); + expect(worker.logger, isNull); + }); + + test('sends and deletes the events it queued', () async { + final server = await LocalPostHogServer.start(); + final storage = FileStorage(dir.path, worker: worker); + final client = testClient(server, storage: storage); + + client.capture('a'); + client.capture('b'); + await client.flush(); + await client.settled; + + expect(server.batchRequests.single.eventNames, ['a', 'b']); + expect(storage.queue.length, 0); + expect(Directory(pathOf('posthog_queue')).listSync().whereType(), + isEmpty); + }); + + test('an event a flush ran into while it was written is still sent', + () async { + final server = await LocalPostHogServer.start(); + final gated = GatedWorker()..deleteGate = Completer(); + final client = testClient(server, + config: testConfig(flushAt: 1, flushInterval: Duration.zero), + storage: FileStorage(dir.path, worker: gated)); + + client.capture('a'); + await server.waitForEvent('a'); + while (gated.deletes == 0) { + await pumpEventQueue(); + } + gated.writeGate = Completer(); + client.capture('b'); + gated.deleteGate!.complete(); + await pumpEventQueue(); + gated.writeGate!.complete(); + + await server.waitForEvent('b'); + }); + + test('AI captures outpacing the worker keep the newest events', () async { + final server = await LocalPostHogServer.start(); + final gated = GatedWorker()..writeGate = Completer(); + final storage = FileStorage(dir.path, worker: gated); + final client = testClient(server, + config: testConfig()..captureAiMaxQueueSize = 2, storage: storage); + + const burst = FileEventQueue.maxWritesInFlight + 20; + for (var i = 0; i < burst; i++) { + client.captureAiPrepared(r'$ai_span', + client.prepareEvent(r'$ai_span', properties: {'i': i})!); + } + expect(gated.writes, FileEventQueue.maxWritesInFlight); + gated.writeGate!.complete(); + await storage.settled; + + final events = await storage.aiQueue.peek(burst); + expect([ + for (final queued in events) (queued.event['properties']! as Map)['i'] + ], [ + burst - 2, + burst - 1 + ]); + }); + + test('a flush waits for an event still being written', () async { + final server = await LocalPostHogServer.start(); + final gated = GatedWorker()..deleteGate = Completer(); + final client = testClient(server, + config: testConfig(flushInterval: Duration.zero), + storage: FileStorage(dir.path, worker: gated)); + + client.capture('a'); + final first = client.flush(); + await server.waitForEvent('a'); + while (gated.deletes == 0) { + await pumpEventQueue(); + } + gated.writeGate = Completer(); + client.capture('b'); + final joined = client.flush(); + gated.deleteGate!.complete(); + await pumpEventQueue(); + gated.writeGate!.complete(); + await first; + await joined; + + expect(server.eventNames, ['a', 'b']); + }); + + test('a write job that fails keeps the event and the queue going', + () async { + final server = await LocalPostHogServer.start(); + final client = testClient(server, + storage: FileStorage(dir.path, worker: _FailingFirstWrite())); + + client.capture('a'); + client.capture('b'); + await client.flush(); + + expect(server.eventNames, ['a', 'b']); + }); + + test('an AI event still being measured does not evict a kept one', + () async { + final server = await LocalPostHogServer.start(); + final storage = FileStorage(dir.path, worker: worker); + final client = testClient(server, + config: testConfig() + ..captureAiMaxQueueSize = 1 + ..captureAiMaxEventBytes = 1000, + storage: storage); + + final kept = client.captureAiPrepared( + r'$ai_span', client.prepareEvent(r'$ai_span')!); + final oversized = client.captureAiPrepared(r'$ai_span', + client.prepareEvent(r'$ai_span', properties: {'input': 'x' * 2000})!); + + final uuid = await kept; + expect(uuid, isNotNull); + expect(await oversized, isNull); + expect(storage.aiQueue.length, 1); + expect((await storage.aiQueue.peek(1)).single.event['uuid'], uuid); + }); + + test('AI events waiting for a write stay within the byte limit', () async { + final gated = GatedWorker()..writeGate = Completer(); + final server = await LocalPostHogServer.start(); + final client = + testClient(server, storage: FileStorage(dir.path, worker: gated)); + final input = 'x' * (6 * 1024 * 1024); + + final uuids = [ + for (var i = 0; i < FileEventQueue.maxWritesInFlight + 12; i++) + client.captureAiPrepared( + r'$ai_generation', + client.prepareEvent(r'$ai_generation', + properties: {'input': input})!), + ]; + gated.writeGate!.complete(); + final results = await Future.wait(uuids); + await client.settled; + + // 6 MiB each: eight fit in 50 MiB, so four of the twelve waiting go. + expect(gated.writes, FileEventQueue.maxWritesInFlight + 8); + expect( + results.sublist(FileEventQueue.maxWritesInFlight, + FileEventQueue.maxWritesInFlight + 4), + everyElement(isNull)); + }); + + test('an AI event does not overwrite person properties set after it', + () async { + final server = await LocalPostHogServer.start(); + final client = + testClient(server, storage: FileStorage(dir.path, worker: worker)); + client.identify('user'); + final prepared = client.prepareEvent(r'$ai_generation', properties: { + r'$set': {'plan': 'old', 'coins': 1}, + })!; + + // The worker measures the event only after the newer value is set. + final uuid = client.captureAiPrepared(r'$ai_generation', prepared); + client.setPersonProperties(userPropertiesToSet: {'plan': 'new'}); + expect(await uuid, isNotNull); + + await client.reloadFeatureFlagsAsync(); + await client.settled; + + expect(server.flagsRequests.last.body['person_properties'], + allOf(containsPair('plan', 'new'), containsPair('coins', 1))); + }); + + test('an AI event without person properties does not rewrite the snapshot', + () async { + final server = await LocalPostHogServer.start(); + final client = + testClient(server, storage: FileStorage(dir.path, worker: worker)); + final prepared = client.prepareEvent(r'$ai_generation')!; + final snapshot = File(pathOf('posthog_data.json'))..deleteSync(); + + expect(await client.captureAiPrepared(r'$ai_generation', prepared), + isNotNull); + + expect(snapshot.existsSync(), isFalse); + }); + + test('an AI event applies its person properties only to its own user', + () async { + final server = await LocalPostHogServer.start(); + final client = + testClient(server, storage: FileStorage(dir.path, worker: worker)); + final prepared = client.prepareEvent(r'$ai_generation', properties: { + r'$set': {'email': 'user@example.com'}, + })!; + + // The worker measures the event only after reset() has run. + final uuid = client.captureAiPrepared(r'$ai_generation', prepared); + client.reset(); + expect(await uuid, isNotNull); + client.capture('next'); + await client.flush(); + + final next = server.batchRequests.single.events.single; + expect((next['options']! as Map)['process_person_profile'], isFalse); + }); + + test('an AI event keeps its person properties when identify follows it', + () async { + final server = await LocalPostHogServer.start(); + final client = + testClient(server, storage: FileStorage(dir.path, worker: worker)); + final prepared = client.prepareEvent(r'$ai_generation', properties: { + r'$set': {'plan': 'pro'}, + })!; + + // The worker measures the event only after identify() has run. + final uuid = client.captureAiPrepared(r'$ai_generation', prepared); + client.identify('user'); + expect(await uuid, isNotNull); + + await client.reloadFeatureFlagsAsync(); + await client.settled; + + expect(server.flagsRequests.last.body['person_properties'], + containsPair('plan', 'pro')); + }); + + test('an AI event from before reset does not apply to the same id again', + () async { + final server = await LocalPostHogServer.start(); + final client = + testClient(server, storage: FileStorage(dir.path, worker: worker)); + client.identify('user'); + final prepared = client.prepareEvent(r'$ai_generation', properties: { + r'$set': {'email': 'user@example.com'}, + })!; + + // The worker measures the event only after the same id is back. + final uuid = client.captureAiPrepared(r'$ai_generation', prepared); + client.reset(); + client.identify('user'); + expect(await uuid, isNotNull); + + await client.reloadFeatureFlagsAsync(); + await client.settled; + + expect((server.flagsRequests.last.body['person_properties'] ?? {}) as Map, + isNot(contains('email'))); + }); + + group('an event captured while an AI event with \$set is measured', () { + late LocalPostHogServer server; + late FileStorage storage; + late DesktopPostHog client; + + setUp(() async { + server = await LocalPostHogServer.start(); + storage = FileStorage(dir.path, worker: worker); + client = testClient(server, storage: storage); + }); + + PostHogPreparedEvent aiEvent() => + client.prepareEvent(r'$ai_generation', properties: { + r'$set': {'plan': 'pro'}, + })!; + + Future> sentOptions(String event) async { + await client.flush(); + await client.settled; + final sent = + server.events.singleWhere((sent) => sent['event'] == event); + return Map.from((sent['options'] ?? const {}) as Map); + } + + test('is person-processed', () async { + final uuid = client.captureAiPrepared(r'$ai_generation', aiEvent()); + client.capture('next'); + expect(await uuid, isNotNull); + + expect(await sentOptions('next'), + isNot(contains('process_person_profile'))); + }); + + test('is personless again after reset', () async { + final uuid = client.captureAiPrepared(r'$ai_generation', aiEvent()); + client.reset(); + client.capture('next'); + expect(await uuid, isNotNull); + + expect(await sentOptions('next'), + containsPair('process_person_profile', false)); + }); + }); + }); + + group('PostHogCore while the worker holds its reply', () { + late LocalPostHogServer server; + late GatedWorker gated; + + setUp(() async { + server = await LocalPostHogServer.start(); + gated = GatedWorker(); + }); + + DesktopPostHog client({int maxQueueSize = 1000, int? aiMaxEventBytes}) => + testClient(server, + config: testConfig( + maxQueueSize: maxQueueSize, flushInterval: Duration.zero) + ..captureAiMaxEventBytes = aiMaxEventBytes, + storage: FileStorage(dir.path, worker: gated)); + + test('an event captured while a batch is encoded goes out with that flush', + () async { + final posthog = client(); + posthog.capture('a'); + gated.encodeGate = Completer(); + final flush = posthog.flush(); + await pumpEventQueue(); + + posthog.capture('b'); + gated.encodeGate!.complete(); + await flush; + + expect(server.batchRequests, hasLength(2)); + expect(server.eventNames, ['a', 'b']); + }); + + test('an event evicted while its batch is encoded is sent once', () async { + final posthog = client(maxQueueSize: 1); + posthog.capture('a'); + gated.encodeGate = Completer(); + final flush = posthog.flush(); + await pumpEventQueue(); + + posthog.capture('b'); + gated.encodeGate!.complete(); + await flush; + await posthog.settled; + + expect(server.eventNames, ['a', 'b']); + expect(Directory(pathOf('posthog_queue')).listSync().whereType(), + isEmpty); + }); + + test('an event evicted while its batch is read is not sent', () async { + final posthog = client(maxQueueSize: 1); + posthog.capture('a'); + gated.readGate = Completer(); + final flush = posthog.flush(); + await pumpEventQueue(); + + posthog.capture('b'); + gated.readGate!.complete(); + await flush; + + expect(server.eventNames, ['b']); + }); + + test('an event captured before reset keeps its distinct id', () async { + final posthog = client(); + final distinctId = posthog.getDistinctId(); + gated.writeGate = Completer(); + posthog.capture('a'); + + posthog.reset(); + gated.writeGate!.complete(); + await posthog.flush(); + + expect(server.events.single['distinct_id'], distinctId); + }); + + test('close while a batch is encoded leaves it for the next client', + () async { + final posthog = client(); + posthog.capture('a'); + gated.encodeGate = Completer(); + final flush = posthog.flush(); + await pumpEventQueue(); + + posthog.close(); + gated.encodeGate!.complete(); + await flush.catchError((Object _) {}); + await posthog.settled; + expect(server.batchRequests, isEmpty); + + await client().flush(); + expect(server.eventNames, ['a']); + }); + + test('an AI event measured after close is sent by the next client', + () async { + final posthog = client(); + gated.writeGate = Completer(); + final uuid = posthog.captureAiPrepared( + r'$ai_span', posthog.prepareEvent(r'$ai_span')!); + + posthog.close(); + gated.writeGate!.complete(); + expect(await uuid, isNotNull); + await posthog.settled; + await client().flush(); + expect( + [for (final event in server.aiEvents) event['event']], [r'$ai_span']); + }); + + test('a flush sends the AI events kept, not one dropped for its size', + () async { + final posthog = client(aiMaxEventBytes: 1000); + gated.writeGate = Completer(); + final dropped = posthog.captureAiPrepared( + r'$ai_span', + posthog + .prepareEvent(r'$ai_span', properties: {'input': 'x' * 2000})!); + final kept = posthog.captureAiPrepared( + r'$ai_trace', posthog.prepareEvent(r'$ai_trace')!); + final flush = posthog.flush(); + + gated.writeGate!.complete(); + await flush; + + expect(await dropped, isNull); + expect(await kept, isNotNull); + expect([for (final event in server.aiEvents) event['event']], + [r'$ai_trace']); + }); + }); +} + +class _FailingFirstWrite extends GatedWorker { + var failed = false; + + @override + Future write( + String? path, + Map event, { + int? maxBytes, + }) { + if (failed) return super.write(path, event, maxBytes: maxBytes); + failed = true; + return Future.error(StateError('job failed')); + } +} diff --git a/posthog_flutter/test/core/test_client.dart b/posthog_flutter/test/core/test_client.dart index de35e5fd..2159996c 100644 --- a/posthog_flutter/test/core/test_client.dart +++ b/posthog_flutter/test/core/test_client.dart @@ -1,8 +1,11 @@ +import 'dart:async'; import 'dart:io'; import 'package:flutter/foundation.dart'; import 'package:flutter_test/flutter_test.dart'; import 'package:posthog_flutter/src/core/file_storage.dart'; +import 'package:posthog_flutter/src/core/logger.dart'; +import 'package:posthog_flutter/src/core/queue_worker.dart'; import 'package:posthog_flutter/src/posthog_config.dart'; import 'package:posthog_flutter/src/posthog_desktop_client.dart'; @@ -85,9 +88,22 @@ Future flagsRequestsFor( return api.flagsRequests.length - before - 1; } +/// The value of [future], which an inline [QueueWorker] completes right +/// away. +T now(Future future) { + late T value; + var done = false; + future.then((result) { + value = result; + done = true; + }); + if (!done) throw StateError('The future did not complete synchronously.'); + return value; +} + /// The queued event messages, oldest first. List> getQueue(FileStorage storage) => [ - for (final queued in storage.queue.peek(storage.queue.length)) + for (final queued in now(storage.queue.peek(storage.queue.length))) queued.event, ]; @@ -117,6 +133,64 @@ Map queuedPropsOf(FileStorage storage, String event) { return message['properties'] as Map; } +/// Runs jobs like [QueueWorker.inline], except that each kind of job waits +/// for its gate while that is set: writes for [writeGate], reads for +/// [readGate], deletes for [deleteGate], request bodies for [encodeGate]. +class GatedWorker implements QueueWorker { + @override + CoreLogger? logger; + + final _inline = QueueWorker.inline(); + Completer? writeGate; + Completer? deleteGate; + Completer? readGate; + Completer? encodeGate; + var writes = 0; + var deletes = 0; + + @override + Future write( + String? path, + Map event, { + int? maxBytes, + }) { + writes++; + final gate = writeGate; + return gate == null + ? _inline.write(path, event, maxBytes: maxBytes) + : gate.future + .then((_) => _inline.write(path, event, maxBytes: maxBytes)); + } + + @override + Future> delete(List paths) { + deletes++; + // Like the real worker, a delete never overtakes an earlier write or read. + final gates = + [writeGate, readGate, deleteGate].nonNulls.map((gate) => gate.future); + return gates.isEmpty + ? _inline.delete(paths) + : Future.wait(gates).then((_) => _inline.delete(paths)); + } + + @override + Future> read(List paths) => + _after(readGate, () => _inline.read(paths)); + + @override + Future encodeBody(Object? body, {required bool gzip}) => + _after(encodeGate, () => _inline.encodeBody(body, gzip: gzip)); + + static Future _after(Completer? gate, Future Function() job) => + gate == null ? job() : gate.future.then((_) => job()); + + @override + bool get runsInBackground => false; + + @override + void kill() {} +} + /// Skip reason for tests that simulate IO failures with POSIX permissions. final chmodSkip = Platform.isWindows ? 'simulates IO failures via POSIX chmod' : false; diff --git a/posthog_flutter/test/posthog_flutter_desktop_test.dart b/posthog_flutter/test/posthog_flutter_desktop_test.dart index ef9b17c2..1d817981 100644 --- a/posthog_flutter/test/posthog_flutter_desktop_test.dart +++ b/posthog_flutter/test/posthog_flutter_desktop_test.dart @@ -3,6 +3,7 @@ import 'dart:io'; import 'dart:ui'; import 'package:flutter_test/flutter_test.dart'; +import 'package:posthog_flutter/src/core/queue_worker.dart'; import 'package:posthog_flutter/src/error_tracking/posthog_error_tracking_autocapture_integration.dart'; import 'package:posthog_flutter/src/feature_flag_result.dart'; import 'package:posthog_flutter/src/feature_flags_loaded.dart'; @@ -12,6 +13,7 @@ import 'package:posthog_flutter/src/posthog_event.dart'; import 'package:posthog_flutter/src/posthog_flutter_desktop.dart'; import 'package:posthog_flutter/src/posthog_flutter_version.dart'; +import 'core/test_client.dart'; import 'posthog_api_fake.dart'; // No TestWidgetsFlutterBinding here: the test binding replaces dart:io's @@ -327,6 +329,83 @@ void main() { }); }); + Function(PosthogFlutterDesktop)>{ + 'capture': (platform) => platform.capture(eventName: 'event'), + 'screen': (platform) => platform.screen(screenName: 'screen'), + 'captureException': (platform) => + platform.captureException(error: StateError('error')), + 'identify': (platform) => platform.identify(userId: 'user'), + 'alias': (platform) => platform.alias(alias: 'alias'), + 'group': (platform) => + platform.group(groupType: 'company', groupKey: 'acme'), + 'setPersonProperties': (platform) => + platform.setPersonProperties(userPropertiesToSet: {'plan': 'pro'}), + }.forEach((name, call) { + test('an awaited $name completes once the event is on disk', () async { + final server = await LocalPostHogServer.start(); + final worker = GatedWorker(); + final defaultWorker = QueueWorker.defaultWorker; + QueueWorker.defaultWorker = () => worker; + addTearDown(() => QueueWorker.defaultWorker = defaultWorker); + final platform = await setUpPlatform(configFor(server)); + worker.writeGate = Completer(); + + var done = false; + final completed = call(platform).then((_) => done = true); + await pumpEventQueue(); + expect(done, isFalse); + + worker.writeGate!.complete(); + await completed; + }); + }); + + test('a queue file job failing on close does not stop the next setup', + () async { + final server = await LocalPostHogServer.start(); + final worker = _LateFailingDeletes(); + final defaultWorker = QueueWorker.defaultWorker; + QueueWorker.defaultWorker = () => worker; + addTearDown(() => QueueWorker.defaultWorker = defaultWorker); + final platform = await setUpPlatform(configFor(server)); + await platform.capture(eventName: 'first'); + await server.waitForEvent('first'); + + // Fails only once close() has given up on the flush and awaits settled. + final closed = platform.close(); + await Future.delayed(const Duration(milliseconds: 2500)); + worker.gate.complete(); + await closed; + + worker.fail = false; + await platform.setup(configFor(server)); + await platform.capture(eventName: 'second'); + + await server.waitForEvent('second'); + }); + + test('close gives up on stalled file work, and the next setup waits for it', + () async { + final server = await LocalPostHogServer.start(); + final worker = GatedWorker(); + final defaultWorker = QueueWorker.defaultWorker; + QueueWorker.defaultWorker = () => worker; + addTearDown(() => QueueWorker.defaultWorker = defaultWorker); + final platform = await setUpPlatform(configFor(server)); + + worker.writeGate = Completer(); + unawaited(platform.capture(eventName: 'stalled')); + await platform.close(); + + var ready = false; + final setup = platform.setup(configFor(server)).then((_) => ready = true); + await pumpEventQueue(); + expect(ready, isFalse); + + worker.writeGate!.complete(); + await setup; + }); + group('PosthogFlutterDesktop.screen', () { test(r'delivers $screen with the screen name property', () async { final server = await LocalPostHogServer.start(); @@ -1580,6 +1659,42 @@ void main() { expect(await nextLaunch.isOptOut(), isTrue); expect(await nextLaunch.getDistinctId(), distinctId); }); + test('an event left unsent at close is sent once after the next setup', + () async { + final server = await LocalPostHogServer.start(); + server.respond = + (_) => const PostHogResponse(HttpStatus.serviceUnavailable); + final platform = createPlatform(); + await platform.setup(configFor(server)); + await platform.capture(eventName: 'kept'); + await platform.close(); + + // The server records the events of the refused requests too. + final refused = server.eventNames.length; + server.respond = (_) => const PostHogResponse(HttpStatus.ok); + await platform.setup(configFor(server)); + await platform.capture(eventName: 'sentinel'); + await server.waitForEvent('sentinel'); + + expect(server.eventNames.skip(refused).where((name) => name == 'kept'), + hasLength(1)); + }); + + test('an event sent before close is not sent again after the next setup', + () async { + final server = await LocalPostHogServer.start(); + final platform = createPlatform(); + await platform.setup(configFor(server)); + await platform.capture(eventName: 'once'); + await server.waitForEvent('once'); + await platform.close(); + + await platform.setup(configFor(server)); + await platform.capture(eventName: 'sentinel'); + await server.waitForEvent('sentinel'); + + expect(server.eventNames.where((name) => name == 'once'), hasLength(1)); + }); }); group('PosthogFlutterDesktop.setup', () { @@ -2566,6 +2681,16 @@ Map _variantFlagResponse() => { }, }; +class _LateFailingDeletes extends GatedWorker { + final gate = Completer(); + var fail = true; + + @override + Future> delete(List paths) => fail + ? gate.future.then((_) => throw StateError('job failed')) + : super.delete(paths); +} + /// Answers `/flags/` with [flags], and every other request with a success. PostHogResponder _answerFlags(Map flags) => (request) => request.isFlags From f9e1698b67c72ad929e2929f38ae50ca7c35d254 Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Tue, 3 Nov 2026 10:36:12 -0500 Subject: [PATCH 20/28] feat!: make beforeSend callbacks synchronous (#686) * feat!: make beforeSend callbacks synchronous Event and log beforeSend callbacks no longer return FutureOr, matching the native SDKs and the before-send-hook spec. The event is handed to the SDK in the same call, so calls made right after an un-awaited capture can no longer reach the SDK first, on every platform including Windows and Linux. Co-Authored-By: Claude Opus 5.5 * fix: keep the call queue on iOS, macOS and Android With #682 and beforeSend set, an event takes two native calls. Without the queue, an optOut(), close() or setup() made right after capture() reaches native between them and the event is lost. Co-Authored-By: Claude Opus 5.5 * test(android): restore the screenshot scale expectation lost in the main merge * fix(web): hand feature events to posthog-js before yielding Without CallOrder the await on the flag lookup let a reset() made right after an un-awaited captureFeatureView or captureFeatureInteraction overtake it, so the event went out as the new anonymous user with the previous user's flag. Co-Authored-By: Claude Opus 5.5 * docs: fold #686 release notes into the 6.0 docs --------- Co-authored-by: Claude Opus 5.5 --- .changeset/v6-major-release.md | 2 + api/posthog_flutter.api.json | 10 +- posthog_flutter/MIGRATION.md | 20 ++ posthog_flutter/lib/posthog_flutter_web.dart | 253 ++++++-------- posthog_flutter/lib/src/posthog.dart | 3 +- posthog_flutter/lib/src/posthog_config.dart | 43 +-- .../lib/src/posthog_flutter_desktop.dart | 42 +-- .../lib/src/posthog_flutter_io.dart | 22 +- .../lib/src/posthog_flutter_web_handler.dart | 19 +- .../lib/src/utils/before_send.dart | 28 +- posthog_flutter/lib/src/utils/call_order.dart | 11 +- .../test/posthog_flutter_desktop_test.dart | 314 ++---------------- .../test/posthog_flutter_io_test.dart | 250 +------------- posthog_flutter/test/posthog_logs_test.dart | 16 - .../test/web_before_send_test.dart | 193 +++-------- 15 files changed, 257 insertions(+), 969 deletions(-) diff --git a/.changeset/v6-major-release.md b/.changeset/v6-major-release.md index d876d643..726f1e95 100644 --- a/.changeset/v6-major-release.md +++ b/.changeset/v6-major-release.md @@ -12,6 +12,8 @@ - **Breaking:** remove `Posthog().getFeatureFlagPayload()` — use `getFeatureFlagResult(key, sendFeatureFlagEvent: false)` and read `payload` - **Breaking:** remove the `PostHogSessionReplayConfig.debouncerDelay` setter — use `throttleDelay` - **Breaking:** remove `PostHogDataMode.cellular` — use `PostHogDataMode.any` +- **Breaking:** make `beforeSend` and `logsConfig.beforeSend` callbacks synchronous — load what they need ahead of time instead of using `await` +- Keep a `reset()`, `identify()` or `optOut()` made right after an un-awaited `capture()`, `screen()` or `captureException()` from applying to that event first, and stop dropping that event on Windows and Linux - **Breaking:** remove `toMap()` from the config classes and `PostHogFeatureFlagResult.fromMap()` from the public API - **Breaking:** rename `enable()` and `disable()` to `optIn()` and `optOut()` on `PosthogFlutterPlatformInterface`, `PosthogFlutterIO` and `PosthogFlutterWeb` - **Breaking:** adopt `posthog-ios` 4.x, which requires Xcode 26 diff --git a/api/posthog_flutter.api.json b/api/posthog_flutter.api.json index b48fe1a8..628dffe4 100644 --- a/api/posthog_flutter.api.json +++ b/api/posthog_flutter.api.json @@ -2570,7 +2570,7 @@ "isRequired": false, "name": "beforeSend", "relativePath": "lib/src/posthog_config.dart", - "typeName": "List Function(PostHogEvent)>?" + "typeName": "List?" } ], "relativePath": "lib/src/posthog_config.dart", @@ -2930,7 +2930,7 @@ "isWriteable": true, "name": "beforeSend", "relativePath": "lib/src/posthog_config.dart", - "typeName": "List Function(PostHogEvent)>" + "typeName": "List" } ], "isDeprecated": false, @@ -3744,7 +3744,7 @@ "isWriteable": true, "name": "beforeSend", "relativePath": "lib/src/posthog_config.dart", - "typeName": "List Function(PostHogLogRecord)>" + "typeName": "List" } ], "isDeprecated": false, @@ -6655,7 +6655,7 @@ ], "typeAliasDeclarations": [ { - "aliasedTypeName": "FutureOr Function(PostHogEvent)", + "aliasedTypeName": "PostHogEvent? Function(PostHogEvent)", "entryPoints": [ "posthog_flutter.dart" ], @@ -6665,7 +6665,7 @@ "relativePath": "lib/src/posthog_config.dart" }, { - "aliasedTypeName": "FutureOr Function(PostHogLogRecord)", + "aliasedTypeName": "PostHogLogRecord? Function(PostHogLogRecord)", "entryPoints": [ "posthog_flutter.dart" ], diff --git a/posthog_flutter/MIGRATION.md b/posthog_flutter/MIGRATION.md index fcd661c2..be8ea86c 100644 --- a/posthog_flutter/MIGRATION.md +++ b/posthog_flutter/MIGRATION.md @@ -175,6 +175,26 @@ config.dataMode = PostHogDataMode.any; They serialized the internal platform-channel format and have no replacement. `toMap()` is gone from `PostHogConfig`, `PostHogBootstrapConfig`, `PostHogLogsConfig`, `PostHogRageClickConfig`, `PostHogSessionReplayConfig`, `PostHogErrorTrackingConfig` and `PostHogExceptionStepsConfig`. To build a result, for example in a test, call the `PostHogFeatureFlagResult` constructor, which stays public. +### `beforeSend` callbacks are synchronous + +`BeforeSendCallback` is now `PostHogEvent? Function(PostHogEvent)`, and `BeforeSendLogCallback` is `PostHogLogRecord? Function(PostHogLogRecord)`. An `async` callback is a compile error. Load what it needs ahead of time and read it synchronously. + +```dart +// Before +config.beforeSend = [ + (event) async { + final allowed = await loadAllowList(); + return allowed.contains(event.event) ? event : null; + }, +]; + +// After +final allowed = await loadAllowList(); +config.beforeSend = [ + (event) => allowed.contains(event.event) ? event : null, +]; +``` + ### Platform interface changes These affect only code that calls, extends or fakes `PosthogFlutterPlatformInterface`, `PosthogFlutterIO` or `PosthogFlutterWeb` directly, such as test mocks. `Posthog().optIn()` and `optOut()` are unaffected. diff --git a/posthog_flutter/lib/posthog_flutter_web.dart b/posthog_flutter/lib/posthog_flutter_web.dart index 97f2511d..994a2779 100644 --- a/posthog_flutter/lib/posthog_flutter_web.dart +++ b/posthog_flutter/lib/posthog_flutter_web.dart @@ -1,7 +1,6 @@ // In order to *not* need this ignore, consider extracting the "web" version // of your plugin as a separate package, instead of inlining it in the same // package as the core of your plugin. -import 'dart:async'; import 'dart:js_interop'; import 'package:flutter/services.dart'; @@ -20,7 +19,6 @@ import 'src/posthog_event.dart'; import 'src/posthog_flutter_platform_interface.dart'; import 'src/posthog_flutter_web_handler.dart'; import 'src/utils/before_send.dart'; -import 'src/utils/call_order.dart'; import 'src/replay/web/web_canvas_mask_provider.dart'; import 'src/utils/capture_utils.dart'; import 'src/utils/event_options.dart'; @@ -43,27 +41,23 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { // its final name, until close(). String? _currentScreen; - final _order = CallOrder(); - - /// Without callbacks the event comes back synchronously, so it is handed - /// over in the same call and nothing has to wait for it. - FutureOr _runBeforeSend( + PostHogEvent? _runBeforeSend( String eventName, Map? properties, { Map? userProperties, Map? userPropertiesSetOnce, Map? options, }) { - final event = PostHogEvent( - event: eventName, - properties: properties, - userProperties: userProperties, - userPropertiesSetOnce: userPropertiesSetOnce, - options: options == null ? null : {...options}, + return applyBeforeSend( + _beforeSendCallbacks, + PostHogEvent( + event: eventName, + properties: properties, + userProperties: userProperties, + userPropertiesSetOnce: userPropertiesSetOnce, + options: options == null ? null : {...options}, + ), ); - return _beforeSendCallbacks.isEmpty - ? event - : applyBeforeSend(_beforeSendCallbacks, event); } /// posthog-js sends these calls' events without event properties, so @@ -77,9 +71,6 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { 'were dropped.'); } - Future _call(MethodCall call) => - _order.run(() => handleWebMethodCall(call)); - static void registerWith(Registrar registrar) { final channel = MethodChannel( 'posthog_flutter', @@ -105,7 +96,7 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { // For now, let's assume direct call to overridden setup handles it. return null; } - return _call(call); + return handleWebMethodCall(call); } @override @@ -173,7 +164,7 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { Map? options, }) async { _logUnsupportedOptions('identify', options); - return _call( + return handleWebMethodCall( MethodCall('identify', { 'userId': userId, if (userProperties != null) 'userProperties': userProperties, @@ -195,7 +186,7 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { return; } - return _call( + return handleWebMethodCall( MethodCall('setPersonProperties', { if (userPropertiesToSet != null) 'userPropertiesToSet': userPropertiesToSet, @@ -212,22 +203,14 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { Map? userProperties, Map? userPropertiesSetOnce, Map? options, - }) => - _order.event( - () => _runBeforeSend( - eventName, - properties, - userProperties: userProperties, - userPropertiesSetOnce: userPropertiesSetOnce, - options: options, - ), - (processedEvent) => _sendCapture(eventName, processedEvent), - ); - - Future _sendCapture( - String eventName, - PostHogEvent? processedEvent, - ) async { + }) async { + final processedEvent = _runBeforeSend( + eventName, + properties, + userProperties: userProperties, + userPropertiesSetOnce: userPropertiesSetOnce, + options: options, + ); if (processedEvent == null) { printIfDebug('[PostHog] Event dropped by beforeSend: $eventName'); return; @@ -258,7 +241,7 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { ? PropertyNormalizer.normalize(extractedUserPropertiesSetOnce) : null; - return _call( + return handleWebMethodCall( MethodCall('capture', { 'eventName': processedEvent.event, if (normalizedProperties != null) 'properties': normalizedProperties, @@ -309,7 +292,7 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { final normalizedAttributes = attributes != null ? PropertyNormalizer.normalize(attributes) : null; - return _call( + return handleWebMethodCall( MethodCall('captureLog', { 'body': body, 'level': level.name, @@ -335,20 +318,11 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { PostHogPropertyName.screenName: screenName, }; - return _order.event( - () => _runBeforeSend( - PostHogEventName.screen, - propsWithScreenName, - options: options, - ), - (processedEvent) => _sendScreen(screenName, processedEvent), + final processedEvent = _runBeforeSend( + PostHogEventName.screen, + propsWithScreenName, + options: options, ); - } - - Future _sendScreen( - String screenName, - PostHogEvent? processedEvent, - ) async { if (processedEvent == null) { printIfDebug('[PostHog] Screen event dropped by beforeSend: $screenName'); return; @@ -374,7 +348,7 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { PostHogEventName.screen, ); - return _call( + return handleWebMethodCall( MethodCall('screen', { 'screenName': finalScreenName, if (remaining != null && remaining.isNotEmpty) 'properties': remaining, @@ -388,12 +362,12 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { Map? options, }) async { _logUnsupportedOptions('alias', options); - return _call(MethodCall('alias', {'alias': alias})); + return handleWebMethodCall(MethodCall('alias', {'alias': alias})); } @override Future getDistinctId() async { - final result = await _call(const MethodCall('distinctId')); + final result = await handleWebMethodCall(const MethodCall('distinctId')); return result as String? ?? ''; } @@ -411,78 +385,75 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { }) => _captureFeatureEvent(r'$feature_interaction', flag, flagVariant); + // Looks up the flag and starts the capture without an await in between, so + // a reset() right after the call cannot move the event to the next user. Future _captureFeatureEvent( String event, String flag, String? flagVariant, - ) => - // The flag lookup belongs to the send step so it reads the flags of the - // user at hand-over time; an async hook keeps later calls waiting for it. - _order.event( - () => Future.value(), - (_) async { - final result = flagVariant == null - ? await getFeatureFlagResult( - key: flag, sendFeatureFlagEvent: false) - : null; - final captured = featureEvent( - event, flag, flagVariant ?? result?.variant ?? result?.enabled); - if (captured == null) return; - final screenName = _currentScreen; - await capture( - eventName: event, - properties: { - ...captured.properties, - if (screenName != null) - PostHogPropertyName.screenName: screenName, - }, - userProperties: captured.userProperties, - ); - }, - ); + ) async { + final screenName = _currentScreen; + final result = flagVariant == null + ? featureFlagResultFromMap( + readFeatureFlagResult(flag, sendEvent: false), + flag, + ) + : null; + final captured = featureEvent( + event, flag, flagVariant ?? result?.variant ?? result?.enabled); + if (captured == null) return; + await capture( + eventName: event, + properties: { + ...captured.properties, + if (screenName != null) PostHogPropertyName.screenName: screenName, + }, + userProperties: captured.userProperties, + ); + } @override Future reset() async { - return _call(const MethodCall('reset')); + return handleWebMethodCall(const MethodCall('reset')); } @override Future optOut() async { - return _call(const MethodCall('disable')); + return handleWebMethodCall(const MethodCall('disable')); } @override Future optIn() async { - return _call(const MethodCall('enable')); + return handleWebMethodCall(const MethodCall('enable')); } @override Future isOptOut() async { - final result = await _call(const MethodCall('isOptOut')); + final result = await handleWebMethodCall(const MethodCall('isOptOut')); return result as bool? ?? true; } @override Future debug(bool enabled) async { - return _call(MethodCall('debug', {'debug': enabled})); + return handleWebMethodCall(MethodCall('debug', {'debug': enabled})); } @override Future register(String key, Object value) async { - return _call( + return handleWebMethodCall( MethodCall('register', {'key': key, 'value': value}), ); } @override Future unregister(String key) async { - return _call(MethodCall('unregister', {'key': key})); + return handleWebMethodCall(MethodCall('unregister', {'key': key})); } @override Future isFeatureEnabled(String key, {bool? sendFeatureFlagEvent, bool? defaultValue}) async { - final result = await _call( + final result = await handleWebMethodCall( MethodCall('isFeatureEnabled', { 'key': key, if (sendFeatureFlagEvent != null) 'sendEvent': sendFeatureFlagEvent, @@ -495,14 +466,14 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { @override Future reloadFeatureFlags() async { return featureFlagsLoadedFromMap( - await _call(const MethodCall('reloadFeatureFlags'))); + await handleWebMethodCall(const MethodCall('reloadFeatureFlags'))); } @override Future setPersonPropertiesForFlags( Map userProperties, ) async { - return _call( + return handleWebMethodCall( MethodCall('setPersonPropertiesForFlags', { 'userProperties': userProperties, }), @@ -511,7 +482,7 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { @override Future resetPersonPropertiesForFlags() async { - return _call( + return handleWebMethodCall( const MethodCall('resetPersonPropertiesForFlags'), ); } @@ -521,7 +492,7 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { String groupType, Map groupProperties, ) async { - return _call( + return handleWebMethodCall( MethodCall('setGroupPropertiesForFlags', { 'groupType': groupType, 'groupProperties': groupProperties, @@ -531,7 +502,7 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { @override Future resetGroupPropertiesForFlags({String? groupType}) async { - return _call( + return handleWebMethodCall( MethodCall('resetGroupPropertiesForFlags', { if (groupType != null) 'groupType': groupType, }), @@ -546,7 +517,7 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { Map? options, }) async { _logUnsupportedOptions('group', options); - return _call( + return handleWebMethodCall( MethodCall('group', { 'groupType': groupType, 'groupKey': groupKey, @@ -560,7 +531,7 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { required String key, bool? sendFeatureFlagEvent, }) async { - return _call(MethodCall('getFeatureFlag', { + return handleWebMethodCall(MethodCall('getFeatureFlag', { 'key': key, if (sendFeatureFlagEvent != null) 'sendEvent': sendFeatureFlagEvent, })); @@ -571,7 +542,7 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { required String key, bool? sendFeatureFlagEvent, }) async { - final result = await _call( + final result = await handleWebMethodCall( MethodCall('getFeatureFlagResult', { 'key': key, if (sendFeatureFlagEvent != null) 'sendEvent': sendFeatureFlagEvent, @@ -584,7 +555,8 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { @override Future?> getAllFeatureFlags() async { - final results = await _call(const MethodCall('getAllFeatureFlags')); + final results = + await handleWebMethodCall(const MethodCall('getAllFeatureFlags')); if (results is! List) return null; return results .map((result) => featureFlagResultFromMap(result, '')) @@ -594,18 +566,18 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { @override Future flush() async { - return _call(const MethodCall('flush')); + return handleWebMethodCall(const MethodCall('flush')); } @override Future close() async { _currentScreen = null; - return _call(const MethodCall('close')); + return handleWebMethodCall(const MethodCall('close')); } @override Future getSessionId() async { - final result = await _call(const MethodCall('getSessionId')); + final result = await handleWebMethodCall(const MethodCall('getSessionId')); return result as String?; } @@ -660,68 +632,59 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { inAppByDefault: _config?.errorTrackingConfig.inAppByDefault ?? true, ); - return await _order.event( - () => _runBeforeSend( - PostHogEventName.exception, - exceptionData.cast(), - options: options, - ), - (processedEvent) => _sendException(error, processedEvent), + final processedEvent = _runBeforeSend( + PostHogEventName.exception, + exceptionData.cast(), + options: options, ); - } catch (error) { - printIfDebug('Exception in captureException: $error'); - } - } - - Future _sendException( - Object error, - PostHogEvent? processedEvent, - ) async { - if (processedEvent == null) { - printIfDebug( - '[PostHog] Exception event dropped by beforeSend: ${error.runtimeType}', + if (processedEvent == null) { + printIfDebug( + '[PostHog] Exception event dropped by beforeSend: ${error.runtimeType}', + ); + return; + } + + if (processedEvent.event != PostHogEventName.exception) { + await capture( + eventName: processedEvent.event, + properties: processedEvent.properties?.cast(), + options: processedEvent.options, + ); + return; + } + + final normalizedData = PropertyNormalizer.normalize( + _withOptionProperties( + processedEvent.properties?.cast(), + processedEvent.options, + PostHogEventName.exception, + ) ?? + {}, ); - return; - } - if (processedEvent.event != PostHogEventName.exception) { - await capture( - eventName: processedEvent.event, - properties: processedEvent.properties?.cast(), - options: processedEvent.options, + return await handleWebMethodCall( + MethodCall('captureException', {'properties': normalizedData}), ); - return; + } catch (error) { + printIfDebug('Exception in captureException: $error'); } - - final normalizedData = PropertyNormalizer.normalize( - _withOptionProperties( - processedEvent.properties?.cast(), - processedEvent.options, - PostHogEventName.exception, - ) ?? - {}, - ); - - return _call( - MethodCall('captureException', {'properties': normalizedData}), - ); } @override Future startSessionRecording({bool resumeCurrent = true}) async { - return _call( + return handleWebMethodCall( MethodCall('startSessionRecording', {'resumeCurrent': resumeCurrent}), ); } @override Future stopSessionRecording() async { - return _call(const MethodCall('stopSessionRecording')); + return handleWebMethodCall(const MethodCall('stopSessionRecording')); } @override Future isSessionReplayActive() async { - final result = await _call( + final result = await handleWebMethodCall( const MethodCall('isSessionReplayActive'), ); return result as bool? ?? false; @@ -735,7 +698,7 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { final normalizedProperties = properties != null ? PropertyNormalizer.normalize(properties) : null; - return _call( + return handleWebMethodCall( MethodCall('addExceptionStep', { 'message': message, if (normalizedProperties != null) 'properties': normalizedProperties, diff --git a/posthog_flutter/lib/src/posthog.dart b/posthog_flutter/lib/src/posthog.dart index cda82522..25d998b0 100644 --- a/posthog_flutter/lib/src/posthog.dart +++ b/posthog_flutter/lib/src/posthog.dart @@ -14,7 +14,6 @@ import 'posthog_flutter_platform_interface.dart'; import 'posthog_internal_events.dart'; import 'posthog_observer.dart'; import 'replay/mask/posthog_mask_controller.dart'; -import 'utils/before_send.dart'; /// Entry point for the PostHog Flutter SDK. /// @@ -424,7 +423,7 @@ class Posthog { _config?.logsConfig.beforeSend ?? const []; for (final callback in callbacks) { try { - final result = await runBeforeSend(callback, record); + final result = callback(record); if (result == null) { debugPrint('[PostHog] Log dropped by beforeSend'); return; diff --git a/posthog_flutter/lib/src/posthog_config.dart b/posthog_flutter/lib/src/posthog_config.dart index 4d4f5ea9..f39265c3 100644 --- a/posthog_flutter/lib/src/posthog_config.dart +++ b/posthog_flutter/lib/src/posthog_config.dart @@ -14,9 +14,9 @@ import 'replay/mask/posthog_text_mask.dart'; /// that are about to be captured. Return a possibly modified event to send it, /// or return `null` to drop it. /// -/// Callbacks can be synchronous or asynchronous (returning -/// `FutureOr`). -typedef BeforeSendCallback = FutureOr Function( +/// Callbacks are synchronous, as in the native SDKs, so the event is sent +/// with the user and properties it was captured under. +typedef BeforeSendCallback = PostHogEvent? Function( PostHogEvent event, ); @@ -27,9 +27,8 @@ typedef BeforeSendCallback = FutureOr Function( /// attributes that are about to be captured. Return a possibly modified record /// to send it, or return `null` to drop it. /// -/// Callbacks can be synchronous or asynchronous (returning -/// `FutureOr`). -typedef BeforeSendLogCallback = FutureOr Function( +/// Callbacks are synchronous, as in the native SDKs. +typedef BeforeSendLogCallback = PostHogLogRecord? Function( PostHogLogRecord record, ); @@ -427,23 +426,6 @@ class PostHogConfig { /// ]; /// ``` /// - /// **Example (async callback):** - /// ```dart - /// config.beforeSend = [ - /// (event) async { - /// // Perform async operations - /// final shouldSend = await checkIfEventAllowed(event.event); - /// if (!shouldSend) { - /// return null; // Drop the event - /// } - /// // Enrich event with async data - /// final extraData = await fetchExtraContext(); - /// event.properties = {...?event.properties, ...extraData}; - /// return event; - /// }, - /// ]; - /// ``` - /// /// **Limitations:** /// - These callbacks do NOT intercept native-initiated events such as: /// - Session replay events (`$snapshot`) when `config.sessionReplay` is @@ -461,20 +443,12 @@ class PostHogConfig { /// except `$lib` and `$lib_version`, which PostHog sets from the SDK. /// /// **Note:** - /// - Callbacks can be synchronous or asynchronous (via - /// `FutureOr`) + /// - Callbacks are synchronous. Load anything they need (such as remote + /// config) ahead of time. /// - If a callback throws, the event is dropped and later callbacks are not /// called. /// - If any callback returns `null`, the event is dropped and subsequent /// callbacks are not called. - /// - On every platform except Windows and Linux, PostHog calls made after a - /// capture (including `reset()`, `identify()` and getters) wait until its - /// callbacks finish, so the event keeps the user and consent it was - /// captured under. A callback that runs longer than 10 seconds stops - /// holding them back; its event is still sent when it finishes, with the - /// user, super properties, groups and consent current by then. Calls made - /// from inside a callback do not wait, but a callback that waits on a - /// PostHog call made elsewhere stalls until that limit. List beforeSend = []; // TODO: missing getAnonymousId, captureDeepLinks integrations @@ -650,8 +624,7 @@ class PostHogLogsConfig { /// native SDKs' own `beforeSend`. Dart callbacks cannot cross the platform /// channel, and running it here gives identical behavior everywhere /// (including web). This mirrors the event [PostHogConfig.beforeSend]. - /// - Callbacks can be synchronous or asynchronous (via - /// `FutureOr`). + /// - Callbacks are synchronous. /// - A callback that throws is logged, and the record is dropped. /// - The W3C trace fields (`traceId`, `spanId`, `traceFlags`) are **not** /// part of [PostHogLogRecord] and are not visible here. They pass straight diff --git a/posthog_flutter/lib/src/posthog_flutter_desktop.dart b/posthog_flutter/lib/src/posthog_flutter_desktop.dart index 55f8f010..66b82a87 100644 --- a/posthog_flutter/lib/src/posthog_flutter_desktop.dart +++ b/posthog_flutter/lib/src/posthog_flutter_desktop.dart @@ -271,9 +271,7 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { options: options, ); if (prepared == null) return; - final hooked = _runBeforeSend(prepared.event); - final processed = - hooked is Future ? await hooked : hooked; + final processed = _runBeforeSend(prepared.event); if (processed == null) { printIfDebug('[PostHog] Event dropped by beforeSend: $eventName'); return; @@ -314,9 +312,7 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { options: options, ); if (prepared == null) return null; - final hooked = _runBeforeSend(prepared.event); - final processed = - hooked is Future ? await hooked : hooked; + final processed = _runBeforeSend(prepared.event); if (processed == null) { printIfDebug('[PostHog] Event dropped by beforeSend: $eventName'); return null; @@ -353,9 +349,7 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { options: options, ); if (prepared == null) return; - final hooked = _runBeforeSend(prepared.event); - final processed = - hooked is Future ? await hooked : hooked; + final processed = _runBeforeSend(prepared.event); if (processed == null) { printIfDebug( '[PostHog] Screen event dropped by beforeSend: $screenName'); @@ -632,9 +626,7 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { options: options, ); if (prepared == null) return; - final hooked = _runBeforeSend(prepared.event); - final processed = - hooked is Future ? await hooked : hooked; + final processed = _runBeforeSend(prepared.event); if (processed == null) { printIfDebug( '[PostHog] Exception event dropped by beforeSend: ${error.runtimeType}', @@ -807,28 +799,10 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { /// /// Returns the possibly modified event, or null if any callback drops it /// or throws. - /// - /// Without callbacks the event is returned synchronously and the caller - /// must not await it: an identify(), reset() or opt-out made right after - /// an unawaited capture would otherwise run first, and the event would be - /// dropped as belonging to another user. - FutureOr _runBeforeSend(PostHogEvent event) { - final callbacks = _config?.beforeSend ?? const []; - return callbacks.isEmpty ? event : _applyCallbacks(callbacks, event); - } - - /// Applies [callbacks], then waits for a setup() in progress: an event - /// whose callbacks finish while the previous client is still closing - /// goes to the next client rather than finding none. - Future _applyCallbacks( - List callbacks, - PostHogEvent event, - ) async { - final processed = await applyBeforeSend(callbacks, event); - final setup = _setupFuture; - if (_client == null && setup != null) await setup; - return processed; - } + PostHogEvent? _runBeforeSend(PostHogEvent event) => applyBeforeSend( + _config?.beforeSend ?? const [], + event, + ); /// Queues [event] as the beforeSend callbacks left it, on the AI queue /// with [ai], and returns its uuid, or null when it is not queued. The diff --git a/posthog_flutter/lib/src/posthog_flutter_io.dart b/posthog_flutter/lib/src/posthog_flutter_io.dart index 6cfd6014..239f123b 100644 --- a/posthog_flutter/lib/src/posthog_flutter_io.dart +++ b/posthog_flutter/lib/src/posthog_flutter_io.dart @@ -53,25 +53,23 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { /// Applies the beforeSend callbacks to an event in order. /// Returns the possibly modified event, or null if any callback drops it. - /// Without callbacks the event comes back synchronously, so it is handed - /// over in the same call and nothing has to wait for it. - FutureOr _runBeforeSend( + PostHogEvent? _runBeforeSend( String eventName, Map? properties, { Map? userProperties, Map? userPropertiesSetOnce, Map? options, }) { - final event = PostHogEvent( - event: eventName, - properties: properties, - userProperties: userProperties, - userPropertiesSetOnce: userPropertiesSetOnce, - options: options == null ? null : {...options}, + return applyBeforeSend( + _beforeSendCallbacks, + PostHogEvent( + event: eventName, + properties: properties, + userProperties: userProperties, + userPropertiesSetOnce: userPropertiesSetOnce, + options: options == null ? null : {...options}, + ), ); - return _beforeSendCallbacks.isEmpty - ? event - : applyBeforeSend(_beforeSendCallbacks, event); } /// Native plugin calls to Flutter diff --git a/posthog_flutter/lib/src/posthog_flutter_web_handler.dart b/posthog_flutter/lib/src/posthog_flutter_web_handler.dart index 95f5e307..2772007e 100644 --- a/posthog_flutter/lib/src/posthog_flutter_web_handler.dart +++ b/posthog_flutter/lib/src/posthog_flutter_web_handler.dart @@ -137,6 +137,15 @@ JSAny? _flagOptions(Map args) { return {if (sendEvent != null) 'send_event': sendEvent}.jsify(); } +Object? readFeatureFlagResult(String key, {bool? sendEvent}) { + return posthog + ?.getFeatureFlagResult( + stringToJSAny(key), + {if (sendEvent != null) 'send_event': sendEvent}.jsify(), + ) + ?.dartify(); +} + bool _sdkInfoOverridden = false; void _maybeOverrideSDKInfo() { @@ -465,14 +474,10 @@ Future handleWebMethodCall(MethodCall call) async { posthog?.getFeatureFlag(stringToJSAny(key), _flagOptions(args)); return featureFlag?.dartify(); case 'getFeatureFlagResult': - final key = args['key'] as String; - final sendEvent = args['sendEvent'] as bool?; - - final result = posthog?.getFeatureFlagResult( - stringToJSAny(key), - {if (sendEvent != null) 'send_event': sendEvent}.jsify(), + return readFeatureFlagResult( + args['key'] as String, + sendEvent: args['sendEvent'] as bool?, ); - return result?.dartify(); case 'getAllFeatureFlags': try { return posthog?.getAllFeatureFlags()?.dartify(); diff --git a/posthog_flutter/lib/src/utils/before_send.dart b/posthog_flutter/lib/src/utils/before_send.dart index 3554ded9..3344d9bb 100644 --- a/posthog_flutter/lib/src/utils/before_send.dart +++ b/posthog_flutter/lib/src/utils/before_send.dart @@ -1,37 +1,17 @@ -import 'dart:async'; - import '../posthog_event.dart'; import '../util/logging.dart'; -/// Runs a single beforeSend [callback] against [record], awaiting an async -/// result. Returns the (possibly modified) record, or `null` to drop it. -/// -/// A throw propagates. [applyBeforeSend] is the event policy: it drops the -/// event. Log capture drops the record in its own loop. -Future runBeforeSend( - FutureOr Function(T) callback, - T record, -) async { - final result = callback(record); - if (result is Future) { - return await result; - } - return result; -} - /// Runs [callbacks] in order against [event]. /// /// A null return drops the event and skips the rest of the list. A throw drops /// the event too. -Future applyBeforeSend( - List Function(PostHogEvent)> callbacks, +PostHogEvent? applyBeforeSend( + List callbacks, PostHogEvent event, -) async { - if (callbacks.isEmpty) return event; - +) { for (final callback in callbacks) { try { - final result = await runBeforeSend(callback, event); + final result = callback(event); if (result == null) return null; event = result; } catch (e) { diff --git a/posthog_flutter/lib/src/utils/call_order.dart b/posthog_flutter/lib/src/utils/call_order.dart index 3defee58..9dbb430a 100644 --- a/posthog_flutter/lib/src/utils/call_order.dart +++ b/posthog_flutter/lib/src/utils/call_order.dart @@ -4,14 +4,13 @@ import '../util/logging.dart'; /// Hands calls to the underlying SDK in the order the app made them. /// -/// The native SDKs and posthog-js run beforeSend synchronously inside -/// capture, so an event always goes out with the user, super properties, -/// groups and consent it was captured under. Flutter's beforeSend can be -/// async. While one runs, later calls such as reset() or identify() wait here +/// An event always has to go out with the user, super properties, groups and +/// consent it was captured under, but handing it over can take more than one +/// async step. While it does, later calls such as reset() or optOut() wait here /// until the event has been handed over, so they still apply after it. class CallOrder { - /// A beforeSend that runs longer than this stops holding back later calls. - /// Its event is still sent when the callbacks finish. + /// An event that takes longer than this stops holding back later calls. It + /// is still sent when it is ready. static const maxWait = Duration(seconds: 10); // Set while a turn is being used: calls made from beforeSend, or from the diff --git a/posthog_flutter/test/posthog_flutter_desktop_test.dart b/posthog_flutter/test/posthog_flutter_desktop_test.dart index 1d817981..01541050 100644 --- a/posthog_flutter/test/posthog_flutter_desktop_test.dart +++ b/posthog_flutter/test/posthog_flutter_desktop_test.dart @@ -263,22 +263,18 @@ void main() { test('does not admit a capture made while opted out', () async { final server = await LocalPostHogServer.start(); final callbackEvents = []; - final releaseHook = Completer(); final config = configFor(server) ..beforeSend = [ - (event) async { + (event) { callbackEvents.add(event.event); - if (event.event == 'blocked capture') await releaseHook.future; return event; }, ]; final platform = await setUpPlatform(config); await platform.optOut(); - final blocked = platform.capture(eventName: 'blocked capture'); + await platform.capture(eventName: 'blocked capture'); await platform.optIn(); - releaseHook.complete(); - await blocked; await platform.capture(eventName: 'sentinel event'); await server.waitForEvent('sentinel event'); @@ -463,36 +459,6 @@ void main() { reason: 'the screen did not become the current one'); }); - test('does not remember a screen when consent changes during its hook', - () async { - final server = await LocalPostHogServer.start(); - final hookStarted = Completer(); - final releaseHook = Completer(); - final config = configFor(server) - ..beforeSend = [ - (event) async { - if (event.event == r'$screen') { - hookStarted.complete(); - await releaseHook.future; - } - return event; - }, - ]; - final platform = await setUpPlatform(config); - - final screen = platform.screen(screenName: 'Blocked'); - await hookStarted.future; - await platform.optOut(); - releaseHook.complete(); - await screen; - await platform.optIn(); - await platform.capture(eventName: 'sentinel event'); - - final event = await server.waitForEvent('sentinel event'); - expect(server.eventNames, ['sentinel event']); - expect(_propertiesOf(event), isNot(contains(r'$screen_name'))); - }); - test('runs the hook once when it renames a screen event', () async { final server = await LocalPostHogServer.start(); var callbackCount = 0; @@ -911,10 +877,11 @@ void main() { late DateTime hookStarted; final config = configFor(server) ..beforeSend = [ - (event) async { + (event) { hookStarted = DateTime.now().toUtc(); // Real wait: the event must not take the time it is queued. - await Future.delayed(const Duration(milliseconds: 50)); + final waited = Stopwatch()..start(); + while (waited.elapsedMilliseconds < 50) {} return event; }, ]; @@ -988,22 +955,18 @@ void main() { test('does not admit an exception made while opted out', () async { final server = await LocalPostHogServer.start(); final callbackEvents = []; - final releaseHook = Completer(); final config = configFor(server) ..beforeSend = [ - (event) async { + (event) { callbackEvents.add(event.event); - if (event.event == r'$exception') await releaseHook.future; return event; }, ]; final platform = await setUpPlatform(config); await platform.optOut(); - final blocked = platform.captureException(error: StateError('blocked')); + await platform.captureException(error: StateError('blocked')); await platform.optIn(); - releaseHook.complete(); - await blocked; await platform.capture(eventName: 'sentinel event'); await server.waitForEvent('sentinel event'); @@ -1097,69 +1060,6 @@ void main() { expect(stepMessagesOf(sentinel), isNull); }); - for (final call in ['capture', 'screen', 'captureException']) { - for (final enabled in [true, false]) { - test( - '$call keeps its original exception steps across close/setup ' - '(initially enabled: $enabled)', () async { - final server = await LocalPostHogServer.start(); - final entered = Completer(); - final release = Completer(); - final config = configFor(server) - ..errorTrackingConfig.exceptionSteps.enabled = enabled - ..beforeSend = [ - (event) async { - entered.complete(); - await release.future; - event.event = r'$exception'; - return event; - }, - ]; - final platform = await setUpPlatform(config); - await platform.addExceptionStep('original client'); - - final pending = switch (call) { - 'capture' => platform.capture(eventName: 'custom error'), - 'screen' => platform.screen(screenName: 'Error'), - _ => platform.captureException(error: StateError('pending')), - }; - await entered.future; - await platform.close(); - await platform.setup(configFor(server)); - await platform.addExceptionStep('replacement client'); - release.complete(); - await pending; - - final event = await server.waitForEvent(r'$exception'); - expect(stepMessagesOf(event), enabled ? ['original client'] : null); - }); - } - } - - test('includes steps recorded while the same client awaits beforeSend', - () async { - final server = await LocalPostHogServer.start(); - final entered = Completer(); - final release = Completer(); - final platform = await setUpPlatform(configFor(server) - ..beforeSend = [ - (event) async { - entered.complete(); - await release.future; - return event; - }, - ]); - await platform.addExceptionStep('before capture'); - final pending = platform.captureException(error: StateError('pending')); - await entered.future; - await platform.addExceptionStep('during beforeSend'); - release.complete(); - await pending; - - expect(stepMessagesOf(await server.waitForEvent(r'$exception')), - ['before capture', 'during beforeSend']); - }); - test('normalize non-finite step and event properties identically', () async { final server = await LocalPostHogServer.start(); @@ -1946,44 +1846,6 @@ void main() { await Future.wait([firstClose, repeatedClose]); }); - test( - 'an event whose callbacks finish while close sends the queue reaches ' - 'the next client', () async { - final server = await LocalPostHogServer.start(); - final releaseHook = Completer(); - final config = configFor(server) - ..flushAt = 20 - ..beforeSend = [ - (event) async { - if (event.event == 'slow event') await releaseHook.future; - return event; - }, - ]; - final platform = await setUpPlatform(config); - await platform.capture(eventName: 'queued event'); - final batch = Completer(); - final batchReceived = Completer(); - server.respond = (_) { - if (batchReceived.isCompleted) { - return const PostHogResponse(HttpStatus.ok); - } - batchReceived.complete(); - return batch.future; - }; - - final slowCapture = platform.capture(eventName: 'slow event'); - final close = platform.close(); - final setup = platform.setup(config); - await batchReceived.future; - releaseHook.complete(); - await Future.delayed(const Duration(milliseconds: 50)); - batch.complete(const PostHogResponse(HttpStatus.ok)); - await Future.wait([slowCapture, close, setup]); - await platform.flush(); - - expect(server.eventNames, ['queued event', 'slow event']); - }); - test('close sends the queued events', () async { final server = await LocalPostHogServer.start(); final platform = await setUpPlatform(configFor(server)..flushAt = 20); @@ -2020,30 +1882,6 @@ void main() { ]); }); - test('an event whose callbacks finish after close reaches the next client', - () async { - final server = await LocalPostHogServer.start(); - final release = Completer(); - final config = configFor(server) - ..beforeSend = [ - (event) async { - if (event.event == 'slow event') await release.future; - return event; - }, - ]; - final platform = await setUpPlatform(config); - - final slowCapture = platform.capture(eventName: 'slow event'); - await platform.close(); - await platform.setup(config); - release.complete(); - await slowCapture; - await platform.capture(eventName: 'sentinel event'); - - await server.waitForEvent('sentinel event'); - expect(server.eventNames, ['slow event', 'sentinel event']); - }); - final pendingCalls = (); - final releaseHook = Completer(); - final config = configFor(server) - ..beforeSend = [ - (event) async { - hookStarted.complete(); - await releaseHook.future; - return event; - }, - ]; - final platform = await setUpPlatform(config); - - final pending = entry.value.call(platform); - await hookStarted.future; - await platform.close(); - await platform.setup( - configFor(server, projectToken: 'next_project'), - ); - releaseHook.complete(); - await pending; - await platform.capture(eventName: 'sentinel event'); - - await server.waitForEvent('sentinel event'); - expect(server.eventNames, ['sentinel event']); - }); - } - - for (final entry in pendingCalls.entries) { - test('${entry.key} pending in a hook does not cross host scope', - () async { - final firstServer = await LocalPostHogServer.start(); - final nextServer = await LocalPostHogServer.start(); - final hookStarted = Completer(); - final releaseHook = Completer(); - final config = configFor(firstServer) - ..beforeSend = [ - (event) async { - hookStarted.complete(); - await releaseHook.future; - return event; - }, - ]; - final platform = await setUpPlatform(config); - - final pending = entry.value.call(platform); - await hookStarted.future; - await platform.close(); - await platform.setup(configFor(nextServer)); - releaseHook.complete(); - await pending; - await platform.capture(eventName: 'sentinel event'); - - await nextServer.waitForEvent('sentinel event'); - expect(firstServer.eventNames, isNot(contains(entry.value.eventName))); - expect(nextServer.eventNames, ['sentinel event']); - }); - } - final identityChanges = Function(PosthogFlutterDesktop)>{ 'identify': (platform) => platform.identify(userId: 'next-user'), @@ -2134,62 +1910,26 @@ void main() { for (final identityChange in identityChanges.entries) { for (final entry in pendingCalls.entries) { - test( - '${entry.key} without hooks is sent before an unawaited ' - '${identityChange.key}', () async { - final server = await LocalPostHogServer.start(); - final platform = await setUpPlatform(configFor(server)); - final distinctId = await platform.getDistinctId(); - - final call = entry.value.call(platform); - final change = identityChange.value(platform); - await Future.wait([call, change]); - await platform.capture(eventName: 'sentinel event'); - - await server.waitForEvent('sentinel event'); - final event = server.events - .singleWhere((event) => event['event'] == entry.value.eventName); - expect(event['distinct_id'], distinctId); - }); - } - } - - for (final identityChange in ['identify', 'reset']) { - for (final entry in pendingCalls.entries) { - test('${entry.key} pending in a hook does not cross $identityChange', - () async { - final server = await LocalPostHogServer.start(); - final hookStarted = Completer(); - final releaseHook = Completer(); - final config = configFor(server) - ..beforeSend = [ - (event) async { - if (event.event == entry.value.eventName) { - hookStarted.complete(); - await releaseHook.future; - } - return event; - }, - ]; - final platform = await setUpPlatform(config); - final initialDistinctId = await platform.getDistinctId(); - - final pending = entry.value.call(platform); - await hookStarted.future; - if (identityChange == 'identify') { - await platform.identify(userId: 'identified_user'); - expect(await platform.getDistinctId(), 'identified_user'); - } else { - await platform.reset(); - expect(await platform.getDistinctId(), isNot(initialDistinctId)); - } - releaseHook.complete(); - await pending; - await platform.capture(eventName: 'sentinel event'); - - await server.waitForEvent('sentinel event'); - expect(server.eventNames, isNot(contains(entry.value.eventName))); - }); + for (final hooked in [false, true]) { + test( + '${entry.key} ${hooked ? 'with' : 'without'} hooks is sent before ' + 'an unawaited ${identityChange.key}', () async { + final server = await LocalPostHogServer.start(); + final platform = await setUpPlatform( + configFor(server)..beforeSend = [if (hooked) (event) => event]); + final distinctId = await platform.getDistinctId(); + + final call = entry.value.call(platform); + final change = identityChange.value(platform); + await Future.wait([call, change]); + await platform.capture(eventName: 'sentinel event'); + + await server.waitForEvent('sentinel event'); + final event = server.events.singleWhere( + (event) => event['event'] == entry.value.eventName); + expect(event['distinct_id'], distinctId); + }); + } } } diff --git a/posthog_flutter/test/posthog_flutter_io_test.dart b/posthog_flutter/test/posthog_flutter_io_test.dart index 2ab3166d..86974c1a 100644 --- a/posthog_flutter/test/posthog_flutter_io_test.dart +++ b/posthog_flutter/test/posthog_flutter_io_test.dart @@ -1,5 +1,3 @@ -import 'dart:async'; - import 'package:flutter/foundation.dart'; import 'package:flutter/services.dart'; import 'package:flutter_test/flutter_test.dart'; @@ -972,220 +970,6 @@ isolate_dso_base: 7000000000 final args = Map.from(captureCall.arguments as Map); expect(args.containsKey('userProperties'), isFalse); }); - - test('async beforeSend can modify event', () async { - testConfig = PostHogConfig( - 'test_project_token', - beforeSend: [ - (event) async { - await Future.delayed(const Duration(milliseconds: 10)); - event.event = 'async_modified_event'; - return event; - }, - ], - ); - await posthogFlutterIO.setup(testConfig); - - await posthogFlutterIO.capture(eventName: 'original_event'); - - final captureCall = log.firstWhere((c) => c.method == 'capture'); - final args = Map.from(captureCall.arguments as Map); - expect(args['eventName'], 'async_modified_event'); - }); - - test('async beforeSend can drop event by returning null', () async { - testConfig = PostHogConfig( - 'test_project_token', - beforeSend: [ - (event) async { - await Future.delayed(const Duration(milliseconds: 100)); - return null; - }, - ], - ); - await posthogFlutterIO.setup(testConfig); - - await posthogFlutterIO.capture(eventName: 'dropped_event'); - - final captureCalls = log.where((c) => c.method == 'capture'); - expect(captureCalls, isEmpty); - }); - - test('mixed sync and async beforeSend callbacks work correctly', () async { - final callOrder = []; - - testConfig = PostHogConfig( - 'test_project_token', - beforeSend: [ - (event) { - callOrder.add('sync1'); - event.event = '${event.event}_sync1'; - return event; - }, - (event) async { - await Future.delayed(const Duration(milliseconds: 100)); - callOrder.add('async1'); - event.event = '${event.event}_async1'; - return event; - }, - (event) { - callOrder.add('sync2'); - event.event = '${event.event}_sync2'; - return event; - }, - ], - ); - await posthogFlutterIO.setup(testConfig); - - await posthogFlutterIO.capture(eventName: 'original'); - - final captureCall = log.firstWhere((c) => c.method == 'capture'); - final args = Map.from(captureCall.arguments as Map); - expect(args['eventName'], 'original_sync1_async1_sync2'); - expect(callOrder, ['sync1', 'async1', 'sync2']); - }); - - test('async beforeSend exception drops event without throwing', () async { - testConfig = PostHogConfig( - 'test_project_token', - beforeSend: [ - (event) async { - await Future.delayed(Duration.zero); - throw Exception('Async error'); - }, - ], - ); - await posthogFlutterIO.setup(testConfig); - log.clear(); - - await expectLater( - posthogFlutterIO.capture( - eventName: 'test_event', - properties: {'key': 'value'}, - ), - completes, - ); - - expect(log, isEmpty); - }); - - test( - 'async beforeSend drops event and stops chain when returning null', - () async { - final callOrder = []; - - testConfig = PostHogConfig( - 'test_project_token', - beforeSend: [ - (event) async { - callOrder.add(1); - await Future.delayed(const Duration(milliseconds: 100)); - return null; // Drop event - }, - (event) { - callOrder.add(2); // Should not be called - return event; - }, - ], - ); - await posthogFlutterIO.setup(testConfig); - - await posthogFlutterIO.capture(eventName: 'test_event'); - - final captureCalls = log.where((c) => c.method == 'capture'); - expect(captureCalls, isEmpty); - expect(callOrder, [1]); // Only first callback should have been called - }, - ); - - test( - 'multiple events with async beforeSend are captured in order when capture is awaited', - () async { - testConfig = PostHogConfig( - 'test_project_token', - beforeSend: [ - (event) async { - // Add delay only for second event - if (event.event == 'event_2') { - await Future.delayed(const Duration(milliseconds: 500)); - } - return event; - }, - ], - ); - await posthogFlutterIO.setup(testConfig); - - await posthogFlutterIO.capture(eventName: 'event_1'); - await posthogFlutterIO.capture(eventName: 'event_2'); - await posthogFlutterIO.capture(eventName: 'event_3'); - - final captureCalls = log.where((c) => c.method == 'capture').toList(); - expect(captureCalls.length, 3); - - final event1Args = Map.from( - captureCalls[0].arguments as Map, - ); - final event2Args = Map.from( - captureCalls[1].arguments as Map, - ); - final event3Args = Map.from( - captureCalls[2].arguments as Map, - ); - - final eventOrder = [ - event1Args['eventName'], - event2Args['eventName'], - event3Args['eventName'], - ]; - expect(eventOrder, ['event_1', 'event_2', 'event_3']); - }, - ); - - test( - 'multiple events with async beforeSend are captured out of order when capture is NOT awaited', - () async { - final releaseFirst = Completer(); - testConfig = PostHogConfig( - 'test_project_token', - beforeSend: [ - (event) async { - if (event.event == 'event_1') { - await releaseFirst.future; - } - return event; - }, - ], - ); - await posthogFlutterIO.setup(testConfig); - - final first = posthogFlutterIO.capture(eventName: 'event_1'); - await posthogFlutterIO.capture(eventName: 'event_2'); - await posthogFlutterIO.capture(eventName: 'event_3'); - expect(log.where((c) => c.method == 'capture'), hasLength(2)); - releaseFirst.complete(); - await first; - - final captureCalls = log.where((c) => c.method == 'capture').toList(); - expect(captureCalls.length, 3); - - final event1Args = Map.from( - captureCalls[0].arguments as Map, - ); - final event2Args = Map.from( - captureCalls[1].arguments as Map, - ); - final event3Args = Map.from( - captureCalls[2].arguments as Map, - ); - - final eventOrder = [ - event1Args['eventName'], - event2Args['eventName'], - event3Args['eventName'], - ]; - expect(eventOrder, ['event_2', 'event_3', 'event_1']); - }, - ); }); group('PosthogFlutterIO captureLog', () { @@ -1270,22 +1054,14 @@ isolate_dso_base: 7000000000 }); }); - group('PosthogFlutterIO calls made while an event is in flight', () { - List sentAfterSetup() => - log.map((c) => c.method).where((m) => m != 'setup').toList(); - - for (final slow in [false, true]) { + group('PosthogFlutterIO calls made right after an event', () { + for (final hooked in [false, true]) { test( - 'reach native after events captured before them ' - '(${slow ? 'async' : 'no'} beforeSend)', () async { - await posthogFlutterIO - .setup(PostHogConfig('test_project_token', beforeSend: [ - if (slow) - (event) async { - await Future.delayed(Duration.zero); - return event; - }, - ])); + 'reach native after the event ' + '(${hooked ? 'with' : 'without'} beforeSend)', () async { + await posthogFlutterIO.setup(PostHogConfig('test_project_token', + beforeSend: [if (hooked) (event) => event])); + log.clear(); final sent = [ posthogFlutterIO.capture(eventName: 'checkout'), @@ -1293,18 +1069,10 @@ isolate_dso_base: 7000000000 posthogFlutterIO.captureException(error: StateError('boom')), ]; await posthogFlutterIO.reset(); - await posthogFlutterIO.identify(userId: 'new-user'); - await posthogFlutterIO.register('plan', 'pro'); await Future.wait(sent); - expect(sentAfterSetup(), [ - 'capture', - 'screen', - 'captureException', - 'reset', - 'identify', - 'register', - ]); + expect(log.map((c) => c.method), + ['capture', 'screen', 'captureException', 'reset']); }); } }); diff --git a/posthog_flutter/test/posthog_logs_test.dart b/posthog_flutter/test/posthog_logs_test.dart index 624822a8..20c8e147 100644 --- a/posthog_flutter/test/posthog_logs_test.dart +++ b/posthog_flutter/test/posthog_logs_test.dart @@ -218,22 +218,6 @@ void main() { expect(fake.capturedLogs.single.body, 'x-1-2'); }); - - test('async hook is awaited', () async { - final config = PostHogConfig('test_token'); - config.logsConfig.beforeSend = [ - (record) async { - await Future.delayed(Duration.zero); - record.body = 'async'; - return record; - }, - ]; - await setupWith(config); - - await Posthog().captureLog(body: 'x'); - - expect(fake.capturedLogs.single.body, 'async'); - }); }); group('PostHogLogsConfig.toMap', () { diff --git a/posthog_flutter/test/web_before_send_test.dart b/posthog_flutter/test/web_before_send_test.dart index 220e2f7d..ba633255 100644 --- a/posthog_flutter/test/web_before_send_test.dart +++ b/posthog_flutter/test/web_before_send_test.dart @@ -55,179 +55,62 @@ void main() { expect((captures.last['properties'] as Map)[r'$screen_name'], 'Basket'); }); - group('calls made while an event is in flight', () { - late List calls; - - setUp(() { - calls = []; + for (final hooked in [false, true]) { + test( + 'events reach posthog-js before a reset made right after them ' + '(${hooked ? 'with' : 'without'} beforeSend)', () async { + final calls = []; final fake = globalContext.getProperty('posthog'.toJS); fake.setProperty( 'capture'.toJS, ((JSString event, [JSAny? a, JSAny? b]) => calls.add(event.toDart)) .toJS, ); - for (final method in [ - 'captureException', - 'reset', - 'identify', - 'alias', - 'register', - 'unregister', - 'group', - 'opt_in_capturing', - 'opt_out_capturing', - ]) { - fake.setProperty( - method.toJS, - (([JSAny? a, JSAny? b, JSAny? c, JSAny? d]) => calls.add(method)) - .toJS, - ); - } - }); - - Future setUpWeb({bool slowBeforeSend = true}) async { - final web = PosthogFlutterWeb(); - await web.setup(PostHogConfig('test_token', beforeSend: [ - if (slowBeforeSend) - (event) async { - await Future.delayed(Duration.zero); - return event; - }, - ])); - return web; - } - - List> captureAll(PosthogFlutterWeb web) => [ - web.capture(eventName: 'checkout'), - web.screen(screenName: 'Cart'), - web.captureException(error: StateError('boom')), - ]; - - const captured = ['checkout', r'$screen', 'captureException']; - - test('reach posthog-js first without beforeSend', () async { - final web = await setUpWeb(slowBeforeSend: false); - - final sent = captureAll(web); - await web.reset(); - await Future.wait(sent); - - expect(calls, [...captured, 'reset']); - }); - - final followUps = Function(PosthogFlutterWeb)>{ - 'reset': (web) => web.reset(), - 'identify': (web) => web.identify(userId: 'new-user'), - 'alias': (web) => web.alias(alias: 'new-alias'), - 'register': (web) => web.register('plan', 'pro'), - 'unregister': (web) => web.unregister('plan'), - 'group': (web) => web.group(groupType: 'company', groupKey: 'acme'), - 'opt_in_capturing': (web) => web.optIn(), - 'opt_out_capturing': (web) => web.optOut(), - }; - for (final MapEntry(key: method, value: call) in followUps.entries) { - test('$method waits for events whose beforeSend is still running', - () async { - final web = await setUpWeb(); - - final sent = captureAll(web); - await call(web); - await Future.wait(sent); - - expect(calls, [...captured, method]); - }); - } - - test('an account switch does not reach an earlier event', () async { - final web = await setUpWeb(); - - final sent = web.capture(eventName: 'checkout'); - await web.reset(); - await web.identify(userId: 'new-user'); - await web.register('account_email', 'new@example.invalid'); - await web.group(groupType: 'company', groupKey: 'new-company'); - await sent; - - expect(calls, ['checkout', 'reset', 'identify', 'register', 'group']); - }); - - test('a feature event waits for an earlier event', () async { + fake.setProperty( + 'captureException'.toJS, + (([JSAny? a, JSAny? b]) => calls.add('captureException')).toJS, + ); + fake.setProperty('reset'.toJS, (([JSAny? a]) => calls.add('reset')).toJS); final web = PosthogFlutterWeb(); - await web.setup(PostHogConfig('test_token', beforeSend: [ - (event) async { - if (event.event == 'checkout') { - await Future.delayed(Duration.zero); - } - return event; - }, - ])); + await web.setup(PostHogConfig('test_token', + beforeSend: [if (hooked) (event) => event])); final sent = [ web.capture(eventName: 'checkout'), - web.captureFeatureView(flag: 'flag', flagVariant: 'a'), + web.screen(screenName: 'Cart'), + web.captureException(error: StateError('boom')), ]; await web.reset(); await Future.wait(sent); - expect(calls, ['checkout', r'$feature_view', 'reset']); + expect(calls, ['checkout', r'$screen', 'captureException', 'reset']); }); + } - for (final slow in [false, true]) { - test( - 'a feature event looks its flag up after earlier calls ' - '(${slow ? 'async' : 'no'} beforeSend)', () async { - final fake = globalContext.getProperty('posthog'.toJS); - var variant = 'old-user-variant'; - fake.setProperty( - 'reset'.toJS, - (() { - calls.add('reset'); - variant = 'new-user-variant'; - }).toJS, - ); - fake.setProperty( - 'getFeatureFlagResult'.toJS, - ((JSString key, [JSAny? options]) { - calls.add('lookup $variant'); - return {'key': key.toDart, 'enabled': true, 'variant': variant} - .jsify(); - }).toJS, - ); - final web = await setUpWeb(slowBeforeSend: slow); - - final sent = [ - if (slow) web.capture(eventName: 'checkout'), - web.captureFeatureView(flag: 'flag'), - ]; - await web.reset(); - await Future.wait(sent); - - expect(calls, [ - if (slow) 'checkout', - 'lookup old-user-variant', - r'$feature_view', - 'reset', - ]); - }); - } - - test('beforeSend can capture without waiting for itself', () async { - final web = PosthogFlutterWeb(); - await web.setup(PostHogConfig('test_token', beforeSend: [ - (event) async { - if (event.event == 'checkout') { - await web.capture(eventName: 'from_hook'); - } - return event; - }, - ])); + test('a feature event looks up its flag and captures before a reset', + () async { + final calls = []; + final fake = globalContext.getProperty('posthog'.toJS); + fake.setProperty( + 'getFeatureFlagResult'.toJS, + ((JSString key, [JSAny? options]) { + calls.add('getFeatureFlagResult'); + return {'key': key.toDart, 'enabled': true}.jsify(); + }).toJS, + ); + fake.setProperty( + 'capture'.toJS, + ((JSString event, [JSAny? a, JSAny? b]) => calls.add(event.toDart)).toJS, + ); + fake.setProperty('reset'.toJS, (([JSAny? a]) => calls.add('reset')).toJS); + final web = PosthogFlutterWeb(); + await web.setup(PostHogConfig('test_token')); - final sent = web.capture(eventName: 'checkout'); - await web.reset(); - await sent; + final sent = web.captureFeatureView(flag: 'checkout'); + await web.reset(); + await sent; - expect(calls, ['from_hook', 'checkout', 'reset']); - }); + expect(calls, ['getFeatureFlagResult', r'$feature_view', 'reset']); }); test('beforeSend null drops capture on web', () async { From 4517ca1f6995d9433b574bee6abd84b7047b4610 Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Tue, 3 Nov 2026 15:50:31 -0500 Subject: [PATCH 21/28] feat: add an onFeatureFlags listener you can unsubscribe (#670) * chore!: adopt posthog-ios 4.0 - Require posthog-ios 4.x. - Adapt to the reloadFeatureFlags(_:) callback that now passes a PostHogFeatureFlagsLoaded (PostHog/posthog-ios#913). - Note the payload decoding changes from PostHog/posthog-ios#903. Co-Authored-By: Claude Opus 5.5 (1M context) * docs(changeset): note posthog-ios 4.0 drops lifecycle version and build PostHog/posthog-ios#905 removes the legacy version/build properties from lifecycle events in 4.0, so Flutter iOS and macOS apps stop sending them. Co-Authored-By: Claude Opus 5.5 (1M context) * chore(ios): drive onFeatureFlags from the posthog-ios onFeatureFlags listener posthog-ios 4.0 removes the didReceiveFeatureFlags notification. * chore!: adopt posthog-android 4.0 (#663) * chore!: adopt posthog-android 4.0 * chore!: pass the loaded flags to onFeatureFlags and reloadFeatureFlags (#664) * chore!: pass the loaded flags to onFeatureFlags and reloadFeatureFlags onFeatureFlags and reloadFeatureFlags now carry a PostHogFeatureFlagsLoaded with the enabled flags, their values and whether loading failed, matching posthog-ios 4.0 and posthog-android 4.0. On web, reloadFeatureFlags completes right away with the flags loaded so far, because posthog-js doesn't report when a reload finishes. * fix: complete the web reloadFeatureFlags with the reloaded flags Wait for the next posthog-js onFeatureFlags call instead of returning the flags already loaded, so a failed reload reports errorsLoading. Complete right away when flags are disabled, and after twice the flags request timeout when posthog-js skips the request without calling back. * chore: use PostHogFeatureFlagsCallback from posthog-android 4.0 * chore: fix ktlint function-signature * fix: await posthog-js reloadFeatureFlagsAsync on web The next onFeatureFlags callback can carry a response from a request already in flight, so reloadFeatureFlags() could complete with flags from before the reload. posthog-js 1.438.2+ settles reloadFeatureFlagsAsync() after this reload's own request; use it when present and keep the callback path for older posthog-js. * docs: pass the loaded flags in the setup example * docs: drop best-effort web note from the person and group property methods * fix(web): wait for posthog-js flags retries before reporting a reload failure posthog-js retries a timed-out /flags request once by default, 500 ms later, inside the same reload. The older-JS deadline of twice the request timeout reported cached flags with errorsLoading set before a successful retry landed. * docs: note where onFeatureFlags and errorsLoading differ on Android and web * docs: describe the older posthog-js reload timeout as the full retry budget Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 * docs(changeset): fold the posthog-android 4.0 and flags-loaded entries into one changeset Co-Authored-By: Claude Opus 5.5 * feat: add an onFeatureFlags listener you can unsubscribe * fix: isolate failing flag listeners, skip web registration without onFeatureFlags, update API snapshot * fix: deliver flag loads to onFeatureFlags listeners before the config callback A config callback that threw kept listeners from getting the load, and a reset() or close() it started was undone when the load was cached after it. Co-Authored-By: Claude Opus 5.5 * fix(web): stop flag registrations left by close() or the posthog-js loader A registration whose unsubscribe isn't stored yet (close() during the synchronous replay) or never arrives (the loader snippet's stub) now goes inert once setup() or close() runs again. Co-Authored-By: Claude Opus 5.5 * fix: drop native flag loads sent before a reset or close reached native Dart bumps a generation when reset() or close() clears the listener registry and sends it with setup, reset and close. Android and iOS tag each onFeatureFlags notification with the generation they had when it fired, and Dart drops ones from an earlier generation, so the previous user's flags can't repopulate the replay cache. Co-Authored-By: Claude Opus 5.5 * fix: start receiving native flag loads when the first listener is added With native auto-init, Posthog().onFeatureFlags() can be the app's only Dart SDK call, and nothing created the platform that installs the channel handler, so native loads never reached the listener. Co-Authored-By: Claude Opus 5.5 * fix: deliver Android reloadFeatureFlags results to onFeatureFlags listeners posthog-android passes a manual reload only to its completion, so no onFeatureFlagsCallback arrives and listeners missed the load while new ones replayed the older snapshot. A reload that finishes after a reset or close is still dropped. Co-Authored-By: Claude Opus 5.5 * chore: stop passing RRStyle to replay screenshot frames (#684) posthog-android 4.0 drops RRStyle and the wireframe tree fields from the internal RRWireframe; screenshot frames don't need a style. Co-authored-by: Claude Opus 5.5 * fix(web): clear replayed flags when a queued reset reaches posthog-js Co-Authored-By: Claude Opus 5.5 * docs: fold #670 release notes into the 6.0 docs * fix: don't throw when SDK calls run before the Flutter binding exists Posthog() creates PosthogFlutterIO, whose constructor set the channel handler and aborted without a binding. Retry the install instead, and fail native calls with a PlatformException so each caller's existing fallback applies. * fix: stop delivering a flags load that a listener's reset() or close() cleared The listeners after it and the config callback no longer get the old flags. Claude-Session: https://claude.ai/code/session_019xLynws83apuXa9LfRy9Aq * feat!: remove PostHogConfig.onFeatureFlags in favor of the listener (#695) * feat!: remove PostHogConfig.onFeatureFlags in favor of the listener Posthog().onFeatureFlags() can be registered before setup() and removed, so the config field no longer adds anything. Android now drives Dart from the posthog-android listener like iOS does, which also fires after a manual reload, so the Dart-side Android reload delivery goes away. * docs: fold #695 release notes into the 6.0 docs * test: use the onFeatureFlags listener in desktop tests from the base merge * fix(example): initialize the binding before registering the flags listener * docs: show the removed onFeatureFlags constructor argument in the migration guide * test: use the flags listener in the #694 desktop tests Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 (1M context) --- .changeset/v6-major-release.md | 4 +- api/posthog_flutter.api.json | 72 +++++-- example/lib/main.dart | 12 +- posthog_flutter/MIGRATION.md | 17 +- .../posthog/flutter/PosthogFlutterPlugin.kt | 35 +++- .../PosthogFlutterPlugin.swift | 31 ++- posthog_flutter/lib/posthog_flutter_web.dart | 83 ++++++-- .../lib/src/feature_flags_listeners.dart | 68 ++++++ .../lib/src/feature_flags_loaded.dart | 43 ++-- posthog_flutter/lib/src/posthog.dart | 48 ++++- posthog_flutter/lib/src/posthog_config.dart | 26 --- .../lib/src/posthog_flutter_desktop.dart | 9 +- .../lib/src/posthog_flutter_io.dart | 68 +++++- .../lib/src/posthog_flutter_web_handler.dart | 5 +- ...feature_flags_listener_auto_init_test.dart | 34 +++ ...re_flags_listener_before_binding_test.dart | 30 +++ .../test/feature_flags_listeners_test.dart | 104 ++++++++++ .../test/posthog_before_binding_test.dart | 32 +++ .../test/posthog_flutter_desktop_test.dart | 167 ++++++++------- .../test/posthog_flutter_io_test.dart | 194 +++++++++++++----- ...sthog_flutter_platform_interface_fake.dart | 2 - .../test/posthog_flutter_web_setup_test.dart | 126 ++++++++++++ posthog_flutter/test/posthog_test.dart | 33 ++- .../test/snapshots/setup_request.json | 3 +- 24 files changed, 988 insertions(+), 258 deletions(-) create mode 100644 posthog_flutter/lib/src/feature_flags_listeners.dart create mode 100644 posthog_flutter/test/feature_flags_listener_auto_init_test.dart create mode 100644 posthog_flutter/test/feature_flags_listener_before_binding_test.dart create mode 100644 posthog_flutter/test/feature_flags_listeners_test.dart create mode 100644 posthog_flutter/test/posthog_before_binding_test.dart diff --git a/.changeset/v6-major-release.md b/.changeset/v6-major-release.md index 726f1e95..56a21d4d 100644 --- a/.changeset/v6-major-release.md +++ b/.changeset/v6-major-release.md @@ -18,7 +18,7 @@ - **Breaking:** rename `enable()` and `disable()` to `optIn()` and `optOut()` on `PosthogFlutterPlatformInterface`, `PosthogFlutterIO` and `PosthogFlutterWeb` - **Breaking:** adopt `posthog-ios` 4.x, which requires Xcode 26 - **Breaking:** adopt `posthog-android` 4.x -- **Breaking:** pass a `PostHogFeatureFlagsLoaded` with the enabled flags, their values and whether loading failed to `PostHogConfig.onFeatureFlags` — update callbacks from `() { ... }` to `(loaded) { ... }` or `(_) { ... }` +- **Breaking:** remove `PostHogConfig.onFeatureFlags` — call `Posthog().onFeatureFlags((loaded) { ... })` before `setup()` instead, which also covers the first load - **Breaking:** return the reloaded flags from `reloadFeatureFlags()` as a `Future` - **Breaking:** return `null` instead of the raw string for a malformed, empty or whitespace-only `getFeatureFlagResult()` payload on iOS, macOS and Android - **Breaking:** keep string payloads passed to `PostHogBootstrapConfig.featureFlagPayloads`, such as `"123"`, as strings on iOS and macOS instead of decoding them to numbers or booleans @@ -32,6 +32,8 @@ - **Breaking:** send person processing as the `process_person_profile: false` option on Windows and Linux, only while it's off, instead of a `$process_person_profile` property on every event - Add an `options` parameter to `capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group` and `captureException`, and `PostHogEvent.options` for `beforeSend` callbacks - Add `captureAi` for AI observability events, a no-op that returns `null` on web +- Add `Posthog().onFeatureFlags()` to get notified after every feature flags load, returning a `PostHogFeatureFlagsSubscription` you can `unsubscribe()` +- Skip SDK calls with a warning instead of throwing when they run before the Flutter binding is initialized on iOS, macOS and Android - Add `PostHogConfig.captureAiCompression`, `captureAiMaxQueueSize`, `captureAiTimeout` and `captureAiMaxEventBytes` - Apply a `$process_person_profile` property or `process_person_profile` option passed with an event to that event on Windows and Linux - Skip `setup()` with one log line when `projectToken` is a personal API key (`phx_`), so the key is never sent diff --git a/api/posthog_flutter.api.json b/api/posthog_flutter.api.json index 628dffe4..8eee77bc 100644 --- a/api/posthog_flutter.api.json +++ b/api/posthog_flutter.api.json @@ -2554,15 +2554,6 @@ "relativePath": "lib/src/posthog_config.dart", "typeName": "String" }, - { - "isDeprecated": false, - "isExperimental": false, - "isNamed": true, - "isRequired": false, - "name": "onFeatureFlags", - "relativePath": "lib/src/posthog_config.dart", - "typeName": "void Function(PostHogFeatureFlagsLoaded)?" - }, { "isDeprecated": false, "isExperimental": false, @@ -2877,17 +2868,6 @@ "relativePath": "lib/src/posthog_config.dart", "typeName": "PostHogBootstrapConfig?" }, - { - "entryPoints": [], - "isDeprecated": false, - "isExperimental": false, - "isReadable": true, - "isStatic": false, - "isWriteable": true, - "name": "onFeatureFlags", - "relativePath": "lib/src/posthog_config.dart", - "typeName": "void Function(PostHogFeatureFlagsLoaded)?" - }, { "entryPoints": [], "isDeprecated": false, @@ -4942,6 +4922,28 @@ "type": "method", "typeParameterNames": [] }, + { + "entryPoints": [], + "isDeprecated": false, + "isExperimental": false, + "isStatic": false, + "name": "onFeatureFlags", + "parameters": [ + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": false, + "isRequired": true, + "name": "callback", + "relativePath": "lib/src/posthog.dart", + "typeName": "void Function(PostHogFeatureFlagsLoaded)" + } + ], + "relativePath": "lib/src/posthog.dart", + "returnTypeName": "PostHogFeatureFlagsSubscription", + "type": "method", + "typeParameterNames": [] + }, { "entryPoints": [], "isDeprecated": false, @@ -6564,6 +6566,36 @@ ], "typeParameterNames": [] }, + { + "entryPoints": [ + "posthog_flutter.dart" + ], + "executableDeclarations": [ + { + "entryPoints": [], + "isDeprecated": false, + "isExperimental": false, + "isStatic": false, + "name": "unsubscribe", + "parameters": [], + "relativePath": "lib/src/feature_flags_loaded.dart", + "returnTypeName": "void", + "type": "method", + "typeParameterNames": [] + } + ], + "fieldDeclarations": [], + "isDeprecated": false, + "isExperimental": false, + "isRequired": false, + "isSealed": false, + "name": "PostHogFeatureFlagsSubscription", + "relativePath": "lib/src/feature_flags_loaded.dart", + "superTypeNames": [ + "Object" + ], + "typeParameterNames": [] + }, { "entryPoints": [ "posthog_flutter.dart" diff --git a/example/lib/main.dart b/example/lib/main.dart index e4599572..fdca02af 100644 --- a/example/lib/main.dart +++ b/example/lib/main.dart @@ -21,12 +21,6 @@ Future main() async { final config = PostHogConfig( 'phc_6lqCaCDCBEWdIGieihq5R2dZpPVbAUFISA75vFZow06', ); - config.onFeatureFlags = (loaded) { - debugPrint( - '[PostHog] Feature flags loaded: ${loaded.variants}, ' - 'errorsLoading: ${loaded.errorsLoading}', - ); - }; config.beforeSend = [ (event) { @@ -84,6 +78,12 @@ Future main() async { Future _initAndRun(PostHogConfig config) async { WidgetsFlutterBinding.ensureInitialized(); + Posthog().onFeatureFlags((loaded) { + debugPrint( + '[PostHog] Feature flags loaded: ${loaded.variants}, ' + 'errorsLoading: ${loaded.errorsLoading}', + ); + }); await Posthog().setup(config); runApp(const MyApp()); } diff --git a/posthog_flutter/MIGRATION.md b/posthog_flutter/MIGRATION.md index be8ea86c..fc39ac48 100644 --- a/posthog_flutter/MIGRATION.md +++ b/posthog_flutter/MIGRATION.md @@ -213,22 +213,28 @@ Future disable() async {} Future optOut() async {} ``` -### `onFeatureFlags` and `reloadFeatureFlags()` +### `PostHogConfig.onFeatureFlags` is removed -`PostHogConfig.onFeatureFlags` now receives a `PostHogFeatureFlagsLoaded`, and `reloadFeatureFlags()` returns a `Future`. It has `flags`, `variants` and `errorsLoading`. +Call `Posthog().onFeatureFlags()` before `setup()`, which also covers the first load. The callback receives a `PostHogFeatureFlagsLoaded`, with `flags`, `variants` and `errorsLoading`, and `reloadFeatureFlags()` now returns a `Future`. ```dart // Before +final config = PostHogConfig('', onFeatureFlags: () { + // ... +}); +// or config.onFeatureFlags = () { // ... }; +await Posthog().setup(config); // After -config.onFeatureFlags = (loaded) { +Posthog().onFeatureFlags((loaded) { if (!loaded.errorsLoading) { // Use loaded.variants } -}; +}); +await Posthog().setup(config); ``` ## Behavior changes @@ -290,6 +296,7 @@ On web, `PostHogConfig.sendFeatureFlagEvent` is not applied to posthog-js, so an - An `options` argument on `capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group` and `captureException`, and `PostHogEvent.options` in `beforeSend`. `process_person_profile`, `cookieless_mode`, `disable_skew_correction` and `product_tour_id` win over their legacy `$` properties. On web, known keys are sent as those legacy properties and other keys are dropped. - `captureAi` for `$ai_*` events. It returns the event's UUID, or `null` when the event isn't admitted. On web it sends nothing and returns `null`. +- `Posthog().onFeatureFlags()` to get notified after every feature flags load. It returns a `PostHogFeatureFlagsSubscription` you can `unsubscribe()`. You can register it before `WidgetsFlutterBinding.ensureInitialized()`, but other SDK calls, including `setup()`, are skipped with a warning until the binding is initialized. ## Upgrade checklist @@ -299,7 +306,7 @@ On web, `PostHogConfig.sendFeatureFlagEvent` is not applied to posthog-js, so an - [ ] Rename `com.posthog.posthog.API_KEY` to `com.posthog.posthog.PROJECT_TOKEN` in `AndroidManifest.xml` and `Info.plist`. - [ ] Use Xcode 26 or later. - [ ] If you run your own reverse proxy or self-host, serve `/i/v1/analytics/events` and `/i/v1/ai/events` first. -- [ ] Update `onFeatureFlags` callbacks to take a `PostHogFeatureFlagsLoaded`. +- [ ] Replace `PostHogConfig.onFeatureFlags` with `Posthog().onFeatureFlags()` before `setup()`. - [ ] Move anything that reads `version` or `build` on iOS and macOS lifecycle events to `$app_version` and `$app_build`. - [ ] If you set `sendFeatureFlagEvent = false`, check whether anything relies on `$feature_flag_called` from `getFeatureFlagResult()`. - [ ] Add `sendFeatureFlagEvent: false` wherever you replace `getFeatureFlagPayload()`. diff --git a/posthog_flutter/android/src/main/kotlin/com/posthog/flutter/PosthogFlutterPlugin.kt b/posthog_flutter/android/src/main/kotlin/com/posthog/flutter/PosthogFlutterPlugin.kt index 0e9add08..4b16c282 100644 --- a/posthog_flutter/android/src/main/kotlin/com/posthog/flutter/PosthogFlutterPlugin.kt +++ b/posthog_flutter/android/src/main/kotlin/com/posthog/flutter/PosthogFlutterPlugin.kt @@ -28,8 +28,8 @@ import com.posthog.PostHogBeforeSend import com.posthog.PostHogBootstrapConfig import com.posthog.PostHogCompression import com.posthog.PostHogConfig -import com.posthog.PostHogFeatureFlagsCallback import com.posthog.PostHogFeatureFlagsLoaded +import com.posthog.PostHogFeatureFlagsSubscription import com.posthog.android.PostHogAndroid import com.posthog.android.PostHogAndroidConfig import com.posthog.android.internal.getApplicationInfo @@ -94,6 +94,12 @@ class PosthogFlutterPlugin : @Volatile private var isHostActivityStopped = false + // Dart's feature flags lifecycle, sent with setup, reset and close. Each + // flags notification carries the one current when it fired, so Dart can + // drop loads from before a reset or close. + @Volatile + private var flagsGeneration = 0 + // A count, not a boolean: under multi-resume (Android 10+ split-screen) // two non-host activities can be resumed at once, and pausing one must // not read as "nothing covers the host" while the other still does. @@ -162,6 +168,8 @@ class PosthogFlutterPlugin : private var flutterSurveysDelegate: PostHogFlutterSurveysDelegate? = null + private var featureFlagsSubscription: PostHogFeatureFlagsSubscription? = null + override fun onAttachedToEngine(flutterPluginBinding: FlutterPlugin.FlutterPluginBinding) { if (bitmapExportExecutor.isShutdown) { bitmapExportExecutor = Executors.newSingleThreadExecutor() @@ -172,6 +180,16 @@ class PosthogFlutterPlugin : channel = MethodChannel(flutterPluginBinding.binaryMessenger, "posthog_flutter") this.applicationContext = flutterPluginBinding.applicationContext + // Before initPlugin, so this also catches the first load of a native auto-init. + featureFlagsSubscription?.unsubscribe() + featureFlagsSubscription = + PostHog.onFeatureFlags { loaded -> + Log.i("PostHogFlutter", "Android onFeatureFlags triggered. Notifying Dart.") + invokeFlutterMethod( + "onFeatureFlagsCallback", + loaded.toFlutterMap() + ("generation" to flagsGeneration), + ) + } initPlugin() channel.setMethodCallHandler(this) @@ -278,6 +296,7 @@ class PosthogFlutterPlugin : } "reset" -> { + updateFlagsGeneration(call) reset(result) } @@ -358,6 +377,7 @@ class PosthogFlutterPlugin : } "close" -> { + updateFlagsGeneration(call) close(result) } @@ -554,6 +574,7 @@ class PosthogFlutterPlugin : return } + updateFlagsGeneration(call) setupPostHog(args) result.success(null) @@ -841,12 +862,6 @@ class PosthogFlutterPlugin : ) } } - - onFeatureFlags = - PostHogFeatureFlagsCallback { loaded -> - Log.i("PostHogFlutter", "Android onFeatureFlags triggered. Notifying Dart.") - invokeFlutterMethod("onFeatureFlagsCallback", loaded.toFlutterMap()) - } } lastBuiltConfig = config @@ -987,6 +1002,8 @@ class PosthogFlutterPlugin : override fun onDetachedFromEngine(binding: FlutterPlugin.FlutterPluginBinding) { stopOcclusionDetector() + featureFlagsSubscription?.unsubscribe() + featureFlagsSubscription = null channel.setMethodCallHandler(null) pushChannelCandidates.remove(channel) if (activeChannel === channel) { @@ -2226,6 +2243,10 @@ class PosthogFlutterPlugin : } } + private fun updateFlagsGeneration(call: MethodCall) { + call.argument("flagsGeneration")?.let { flagsGeneration = it } + } + private fun close(result: Result) { try { PostHog.close() diff --git a/posthog_flutter/darwin/posthog_flutter/Sources/posthog_flutter/PosthogFlutterPlugin.swift b/posthog_flutter/darwin/posthog_flutter/Sources/posthog_flutter/PosthogFlutterPlugin.swift index e2e2308e..e65aa02d 100644 --- a/posthog_flutter/darwin/posthog_flutter/Sources/posthog_flutter/PosthogFlutterPlugin.swift +++ b/posthog_flutter/darwin/posthog_flutter/Sources/posthog_flutter/PosthogFlutterPlugin.swift @@ -45,6 +45,24 @@ public class PosthogFlutterPlugin: NSObject, FlutterPlugin { private var channel: FlutterMethodChannel? private var featureFlagsSubscription: PostHogFeatureFlagsSubscription? + // Dart's feature flags lifecycle, sent with setup, reset and close. Each + // flags notification carries the one current when it fired, so Dart can + // drop loads from before a reset or close. + private let flagsGenerationLock = NSLock() + private var flagsGenerationValue = 0 + private var flagsGeneration: Int { + get { + flagsGenerationLock.lock() + defer { flagsGenerationLock.unlock() } + return flagsGenerationValue + } + set { + flagsGenerationLock.lock() + flagsGenerationValue = newValue + flagsGenerationLock.unlock() + } + } + // Mint route for pushIdentityProvider, anchored to the engine whose setup() // installed the provider. A live owner is never displaced; provider-enabled // engines stay candidates so detach promotes the most recent survivor instead @@ -88,7 +106,15 @@ public class PosthogFlutterPlugin: NSObject, FlutterPlugin { } func featureFlagsDidUpdate(_ loaded: PostHogFeatureFlagsLoaded) { - invokeFlutterMethod("onFeatureFlagsCallback", arguments: Self.featureFlagsLoadedMap(loaded)) + var arguments = Self.featureFlagsLoadedMap(loaded) + arguments["generation"] = flagsGeneration + invokeFlutterMethod("onFeatureFlagsCallback", arguments: arguments) + } + + private func updateFlagsGeneration(_ call: FlutterMethodCall) { + if let generation = (call.arguments as? [String: Any])?["flagsGeneration"] as? Int { + flagsGeneration = generation + } } private static func featureFlagsLoadedMap(_ loaded: PostHogFeatureFlagsLoaded) -> [String: Any] { @@ -485,6 +511,7 @@ public class PosthogFlutterPlugin: NSObject, FlutterPlugin { public func handle(_ call: FlutterMethodCall, result: @escaping FlutterResult) { switch call.method { case "setup": + updateFlagsGeneration(call) setup(call, result: result) case "getFeatureFlag": getFeatureFlag(call, result: result) @@ -515,6 +542,7 @@ public class PosthogFlutterPlugin: NSObject, FlutterPlugin { case "distinctId": distinctId(result) case "reset": + updateFlagsGeneration(call) reset(result) case "enable": enable(result) @@ -547,6 +575,7 @@ public class PosthogFlutterPlugin: NSObject, FlutterPlugin { case "addExceptionStep": addExceptionStep(call, result: result) case "close": + updateFlagsGeneration(call) close(result) case "sendMetaEvent": sendMetaEvent(call, result: result) diff --git a/posthog_flutter/lib/posthog_flutter_web.dart b/posthog_flutter/lib/posthog_flutter_web.dart index 994a2779..aebc8567 100644 --- a/posthog_flutter/lib/posthog_flutter_web.dart +++ b/posthog_flutter/lib/posthog_flutter_web.dart @@ -2,6 +2,7 @@ // of your plugin as a separate package, instead of inlining it in the same // package as the core of your plugin. import 'dart:js_interop'; +import 'dart:js_interop_unsafe'; import 'package:flutter/services.dart'; import 'package:flutter_web_plugins/flutter_web_plugins.dart'; @@ -11,6 +12,7 @@ import 'package:posthog_flutter/src/utils/channel_serialization.dart'; import 'package:posthog_flutter/src/utils/property_normalizer.dart'; import 'src/feature_flag_result.dart'; +import 'src/feature_flags_listeners.dart'; import 'src/feature_flags_loaded.dart'; import 'src/logs/posthog_log_severity.dart'; import 'src/posthog_config.dart'; @@ -35,6 +37,11 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { /// Copied at setup. Event beforeSend runs here, before posthog-js, the same /// way [PosthogFlutterIO] runs it before the platform channel. List _beforeSendCallbacks = []; + JSFunction? _featureFlagsUnsubscribe; + + /// Bumped by each setup() and close(), so a posthog-js registration from an + /// earlier one stops delivering even when it can't be unsubscribed. + int _featureFlagsGeneration = 0; // posthog-js has no current screen, so the feature events get it from here // the way native SDKs stamp it: the last screen beforeSend accepted, under @@ -67,8 +74,10 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { Map? options, ) { if (cleanEventOptions(options) == null) return; - printIfDebug('[PostHog] $method options are not supported on web and ' - 'were dropped.'); + printIfDebug( + '[PostHog] $method options are not supported on web and ' + 'were dropped.', + ); } static void registerWith(Registrar registrar) { @@ -140,19 +149,34 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { WebCanvasMaskProvider(config).register(); - if (config.onFeatureFlags != null && ph != null) { - final dartCallback = config.onFeatureFlags!; + // Skipped for a posthog-js stub without onFeatureFlags. + if (ph != null && (ph as JSObject).has('onFeatureFlags')) { + // Repeated setup would otherwise deliver each load twice. + _featureFlagsUnsubscribe?.callAsFunction(); + _featureFlagsUnsubscribe = null; + final generation = ++_featureFlagsGeneration; // JS SDK calls with: (flags: string[], variants: Record, context?: {errorsLoading}) final jsCallback = (JSArray jsFlags, JSObject jsFlagVariants, [JSObject? jsContext]) { - dartCallback(featureFlagsLoadedFromMap({ + // The posthog-js loader snippet queues the registration and returns + // no unsubscribe, so a later setup() or close() can't remove it. + if (generation != _featureFlagsGeneration) return; + final loaded = featureFlagsLoadedFromMap({ 'variants': jsFlagVariants.dartify(), 'errorsLoading': (jsContext?.dartify() as Map?)?['errorsLoading'], - })); + }); + FeatureFlagsListeners.instance.deliver(loaded); }.toJS; - ph.onFeatureFlags(jsCallback); + // posthog-js replays loaded flags synchronously, and a callback may call + // close() or setup() before this returns the unsubscribe. + final unsubscribe = ph.onFeatureFlags(jsCallback); + if (generation == _featureFlagsGeneration) { + _featureFlagsUnsubscribe = unsubscribe; + } else { + unsubscribe?.callAsFunction(); + } } } @@ -262,8 +286,10 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { Map? userPropertiesSetOnce, Map? options, }) async { - printIfDebug('[PostHog] captureAi is not supported on web. ' - 'The event "$eventName" was not sent.'); + printIfDebug( + '[PostHog] captureAi is not supported on web. ' + 'The event "$eventName" was not sent.', + ); return null; } @@ -274,8 +300,10 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { Map? options, String eventName, ) { - final optionProperties = - eventOptionsToLegacyProperties(options, method: eventName); + final optionProperties = eventOptionsToLegacyProperties( + options, + method: eventName, + ); if (optionProperties.isEmpty) return properties; return {...?properties, ...optionProperties}; } @@ -400,7 +428,10 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { ) : null; final captured = featureEvent( - event, flag, flagVariant ?? result?.variant ?? result?.enabled); + event, + flag, + flagVariant ?? result?.variant ?? result?.enabled, + ); if (captured == null) return; await capture( eventName: event, @@ -451,8 +482,11 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { } @override - Future isFeatureEnabled(String key, - {bool? sendFeatureFlagEvent, bool? defaultValue}) async { + Future isFeatureEnabled( + String key, { + bool? sendFeatureFlagEvent, + bool? defaultValue, + }) async { final result = await handleWebMethodCall( MethodCall('isFeatureEnabled', { 'key': key, @@ -466,7 +500,8 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { @override Future reloadFeatureFlags() async { return featureFlagsLoadedFromMap( - await handleWebMethodCall(const MethodCall('reloadFeatureFlags'))); + await handleWebMethodCall(const MethodCall('reloadFeatureFlags')), + ); } @override @@ -531,10 +566,12 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { required String key, bool? sendFeatureFlagEvent, }) async { - return handleWebMethodCall(MethodCall('getFeatureFlag', { - 'key': key, - if (sendFeatureFlagEvent != null) 'sendEvent': sendFeatureFlagEvent, - })); + return handleWebMethodCall( + MethodCall('getFeatureFlag', { + 'key': key, + if (sendFeatureFlagEvent != null) 'sendEvent': sendFeatureFlagEvent, + }), + ); } @override @@ -555,8 +592,9 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { @override Future?> getAllFeatureFlags() async { - final results = - await handleWebMethodCall(const MethodCall('getAllFeatureFlags')); + final results = await handleWebMethodCall( + const MethodCall('getAllFeatureFlags'), + ); if (results is! List) return null; return results .map((result) => featureFlagResultFromMap(result, '')) @@ -572,6 +610,9 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { @override Future close() async { _currentScreen = null; + _featureFlagsUnsubscribe?.callAsFunction(); + _featureFlagsUnsubscribe = null; + _featureFlagsGeneration++; return handleWebMethodCall(const MethodCall('close')); } diff --git a/posthog_flutter/lib/src/feature_flags_listeners.dart b/posthog_flutter/lib/src/feature_flags_listeners.dart new file mode 100644 index 00000000..b65dff06 --- /dev/null +++ b/posthog_flutter/lib/src/feature_flags_listeners.dart @@ -0,0 +1,68 @@ +import 'dart:async'; + +import 'package:meta/meta.dart'; + +import 'feature_flags_loaded.dart'; +import 'posthog_flutter_platform_interface.dart'; +import 'util/logging.dart'; + +/// Delivers each feature flags load to the listeners added with +/// [Posthog.onFeatureFlags]. +@internal +class FeatureFlagsListeners { + FeatureFlagsListeners._(); + + static final instance = FeatureFlagsListeners._(); + + final _listeners = {}; + PostHogFeatureFlagsLoaded? _last; + int _generation = 0; + + /// Bumped by [clear]. The native SDKs tag each load with the generation + /// they last got, so a load sent before a `reset()` or `close()` reached + /// them can be told apart. + int get generation => _generation; + + PostHogFeatureFlagsSubscription add(OnFeatureFlagsCallback listener) { + final token = Object(); + _listeners[token] = listener; + final current = _last; + if (current != null) { + // Skipped if a newer load already reached the listener. + scheduleMicrotask(() { + if (_listeners.containsKey(token) && identical(_last, current)) { + _notify(listener, current); + } + }); + } + return PostHogFeatureFlagsSubscription(() => _listeners.remove(token)); + } + + void deliver(PostHogFeatureFlagsLoaded loaded) { + _last = loaded; + final generation = _generation; + for (final entry in _listeners.entries.toList()) { + // A listener's reset() or close() cleared this load. + if (generation != _generation) return; + // An earlier listener may have unsubscribed this one. + if (_listeners.containsKey(entry.key)) _notify(entry.value, loaded); + } + } + + // A throwing listener must not stop the others from getting the load. + void _notify( + OnFeatureFlagsCallback listener, PostHogFeatureFlagsLoaded loaded) { + try { + listener(loaded); + } catch (e) { + printIfDebug('onFeatureFlags listener threw: $e'); + } + } + + /// Forgets the last load, so new listeners don't get the previous user's + /// flags after `reset()` or `close()`. + void clear() { + _last = null; + _generation++; + } +} diff --git a/posthog_flutter/lib/src/feature_flags_loaded.dart b/posthog_flutter/lib/src/feature_flags_loaded.dart index 0a8c196b..0b6e108c 100644 --- a/posthog_flutter/lib/src/feature_flags_loaded.dart +++ b/posthog_flutter/lib/src/feature_flags_loaded.dart @@ -1,5 +1,7 @@ -/// The feature flags passed to [PostHogConfig.onFeatureFlags] and returned by -/// [Posthog.reloadFeatureFlags]. +import 'package:meta/meta.dart'; + +/// The feature flags passed to [Posthog.onFeatureFlags] listeners and returned +/// by [Posthog.reloadFeatureFlags]. /// /// Only enabled flags are included. When the latest load failed, /// [errorsLoading] is `true` and the flags are the last known values, which @@ -7,15 +9,14 @@ /// /// **Example:** /// ```dart -/// final config = PostHogConfig('') -/// ..onFeatureFlags = (loaded) { -/// if (loaded.errorsLoading) { -/// // The values are the last known (cached) flags. -/// } -/// if (loaded.variants['new-checkout'] == 'test') { -/// // Show the test variant. -/// } -/// }; +/// Posthog().onFeatureFlags((loaded) { +/// if (loaded.errorsLoading) { +/// // The values are the last known (cached) flags. +/// } +/// if (loaded.variants['new-checkout'] == 'test') { +/// // Show the test variant. +/// } +/// }); /// ``` class PostHogFeatureFlagsLoaded { /// The keys of the enabled feature flags. @@ -31,9 +32,8 @@ class PostHogFeatureFlagsLoaded { /// /// When it did, [flags] and [variants] hold the last known values. /// - /// **Flutter web:** when [PostHogConfig.onFeatureFlags] is first set, it is - /// called right away with the current flags and `false`, even if - /// posthog-js's last load before that failed. + /// **Flutter web:** the first load after [Posthog.setup] can be the current + /// flags with `false`, even if posthog-js's last load before that failed. final bool errorsLoading; /// Creates the loaded feature flags from [variants], keeping only enabled @@ -51,3 +51,18 @@ class PostHogFeatureFlagsLoaded { String toString() => 'PostHogFeatureFlagsLoaded(variants: $variants, errorsLoading: $errorsLoading)'; } + +/// A listener added with [Posthog.onFeatureFlags]. +/// +/// Call [unsubscribe] to stop receiving feature flags updates. +class PostHogFeatureFlagsSubscription { + final void Function() _unsubscribe; + + /// Not part of the public API. + @internal + PostHogFeatureFlagsSubscription(this._unsubscribe); + + /// Stops the listener from receiving further updates. Calling it again has + /// no effect. + void unsubscribe() => _unsubscribe(); +} diff --git a/posthog_flutter/lib/src/posthog.dart b/posthog_flutter/lib/src/posthog.dart index 9570a60d..472ec804 100644 --- a/posthog_flutter/lib/src/posthog.dart +++ b/posthog_flutter/lib/src/posthog.dart @@ -5,6 +5,7 @@ import 'package:meta/meta.dart'; import 'package:posthog_flutter/src/error_tracking/posthog_error_tracking_autocapture_integration.dart'; import 'package:posthog_flutter/src/error_tracking/posthog_exception.dart'; import 'feature_flag_result.dart'; +import 'feature_flags_listeners.dart'; import 'feature_flags_loaded.dart'; import 'logs/posthog_log_record.dart'; import 'logs/posthog_log_severity.dart'; @@ -45,8 +46,8 @@ class Posthog { /// the SDK for tracking events and feature flags. /// /// The [config] object contains your project token, host, and other settings. - /// To listen for feature flag load events, provide an `onFeatureFlags` - /// callback in the [PostHogConfig]. + /// To listen for feature flag load events, call [onFeatureFlags] before this + /// method. /// /// Repeated setup reapplies Dart-side settings such as the error-tracking /// hooks. Most native settings still require [close] before setup because @@ -58,9 +59,9 @@ class Posthog { /// ```dart /// final config = PostHogConfig('YOUR_PROJECT_TOKEN'); /// config.host = 'YOUR_POSTHOG_HOST'; - /// config.onFeatureFlags = (loaded) { + /// Posthog().onFeatureFlags((loaded) { /// // Feature flags are now loaded, you can read flag values here - /// }; + /// }); /// await Posthog().setup(config); /// ``` /// @@ -495,6 +496,7 @@ class Posthog { // Bumped before the platform call because native rotates inside that round // trip. PostHogInternalEvents.requestReplaySessionReset(); + FeatureFlagsListeners.instance.clear(); await _posthog.reset(); } @@ -631,6 +633,43 @@ class Posthog { Future reloadFeatureFlags() => _posthog.reloadFeatureFlags(); + /// Registers a [callback] that's invoked whenever feature flags are loaded + /// or updated. + /// + /// It's invoked after the SDK loads flags at startup (including from + /// bootstrap values), after [reloadFeatureFlags], and after calls that + /// reload flags such as [identify], [group] or [reset]. If a load fails, + /// [PostHogFeatureFlagsLoaded.errorsLoading] is `true` and the values are + /// the last known flags. If flags have already loaded when you register, + /// it's also invoked with the current values shortly afterwards. + /// + /// You can register before [setup], even before + /// `WidgetsFlutterBinding.ensureInitialized()`, and the callback stays + /// registered across [close] and [setup]. Treat each invocation as "flags may have + /// changed", not as an exactly-once event. + /// + /// Returns a subscription; call + /// [PostHogFeatureFlagsSubscription.unsubscribe] to stop receiving updates. + /// + /// **Example:** + /// ```dart + /// final subscription = Posthog().onFeatureFlags((loaded) { + /// if (loaded.variants['new-checkout'] == 'test') { + /// // Show the test variant. + /// } + /// }); + /// + /// // Later, stop listening. + /// subscription.unsubscribe(); + /// ``` + PostHogFeatureFlagsSubscription onFeatureFlags( + OnFeatureFlagsCallback callback) { + // Creating the platform installs the channel handler native loads arrive + // on. With native auto-init this can be the app's only Dart SDK call. + _posthog; + return FeatureFlagsListeners.instance.add(callback); + } + /// Sets person properties that are used only for feature flag evaluation. /// /// Docs: https://posthog.com/docs/feature-flags @@ -1170,6 +1209,7 @@ class Posthog { // recording that follows must start clean either way. PostHogInternalEvents.requestReplaySessionReset(); PosthogObserver.clearCurrentContext(); + FeatureFlagsListeners.instance.clear(); // Uninstall Flutter integrations _uninstallFlutterIntegrations(); diff --git a/posthog_flutter/lib/src/posthog_config.dart b/posthog_flutter/lib/src/posthog_config.dart index 2948950e..2f6562c3 100644 --- a/posthog_flutter/lib/src/posthog_config.dart +++ b/posthog_flutter/lib/src/posthog_config.dart @@ -311,28 +311,6 @@ class PostHogConfig { /// call instead. PostHogBootstrapConfig? bootstrap; - /// Callback to be invoked when feature flags are loaded. - /// - /// It receives the enabled flags and whether loading failed. It runs after - /// the flags load at startup, after [Posthog.reloadFeatureFlags], and after - /// calls that reload flags such as `identify()` or `group()`. When a load - /// fails, [PostHogFeatureFlagsLoaded.errorsLoading] is `true` and the flags - /// are the last known values. Defaults to `null`. - /// - /// **Android:** not called after [Posthog.reloadFeatureFlags]. Use the - /// flags that call returns instead. - /// - /// **Example:** - /// ```dart - /// final config = PostHogConfig('') - /// ..onFeatureFlags = (loaded) { - /// if (loaded.variants['new-checkout'] == 'test') { - /// // Show the test variant. - /// } - /// }; - /// ``` - OnFeatureFlagsCallback? onFeatureFlags; - /// Whether to automatically register this device's push token or Firebase /// Installation ID (FID) with PostHog. /// @@ -460,14 +438,10 @@ class PostHogConfig { /// /// The [projectToken] is trimmed before it is stored. /// - /// The optional [onFeatureFlags] callback is invoked when feature flags finish - /// loading. - /// /// The optional [beforeSend] callbacks are copied into [beforeSend] and run in /// order before Dart-captured events are sent. PostHogConfig( String projectToken, { - this.onFeatureFlags, List? beforeSend, }) : projectToken = projectToken.trim(), beforeSend = beforeSend ?? []; diff --git a/posthog_flutter/lib/src/posthog_flutter_desktop.dart b/posthog_flutter/lib/src/posthog_flutter_desktop.dart index 66b82a87..043747a9 100644 --- a/posthog_flutter/lib/src/posthog_flutter_desktop.dart +++ b/posthog_flutter/lib/src/posthog_flutter_desktop.dart @@ -6,6 +6,7 @@ import 'core/file_storage.dart'; import 'core/utils/utils.dart'; import 'error_tracking/dart_exception_processor.dart'; import 'feature_flag_result.dart'; +import 'feature_flags_listeners.dart'; import 'feature_flags_loaded.dart'; import 'logs/posthog_log_severity.dart'; import 'posthog_config.dart'; @@ -66,7 +67,7 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { _ClientScope? _clientScope; /// The configuration of the latest setup(), read by the Dart-side hooks: - /// beforeSend, onFeatureFlags and exception processing. + /// beforeSend and exception processing. PostHogConfig? _config; void Function()? _featureFlagsUnsubscribe; @@ -177,8 +178,10 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { projectToken: config.projectToken, host: removeTrailingSlash(config.host), ); - _featureFlagsUnsubscribe = client.onFeatureFlags( - () => _config?.onFeatureFlags?.call(client.featureFlagsLoaded())); + _featureFlagsUnsubscribe = client.onFeatureFlags(() { + final loaded = client.featureFlagsLoaded(); + FeatureFlagsListeners.instance.deliver(loaded); + }); final stepsConfig = config.errorTrackingConfig.exceptionSteps; _exceptionSteps = stepsConfig.enabled diff --git a/posthog_flutter/lib/src/posthog_flutter_io.dart b/posthog_flutter/lib/src/posthog_flutter_io.dart index 239f123b..18da22b0 100644 --- a/posthog_flutter/lib/src/posthog_flutter_io.dart +++ b/posthog_flutter/lib/src/posthog_flutter_io.dart @@ -3,6 +3,7 @@ import 'dart:async'; import 'util/platform_io_stub.dart' if (dart.library.io) 'util/platform_io_real.dart'; +import 'package:flutter/foundation.dart'; import 'package:flutter/services.dart'; import 'package:posthog_flutter/src/surveys/survey_service.dart'; @@ -19,6 +20,7 @@ import 'utils/flutter_version.dart'; import 'utils/property_normalizer.dart'; import 'feature_flag_result.dart'; +import 'feature_flags_listeners.dart'; import 'feature_flags_loaded.dart'; import 'logs/posthog_log_severity.dart'; import 'posthog_config.dart'; @@ -30,13 +32,17 @@ import 'posthog_internal_events.dart'; /// An implementation of [PosthogFlutterPlatformInterface] that uses method channels. class PosthogFlutterIO extends PosthogFlutterPlatformInterface { PosthogFlutterIO() { - _methodChannel.setMethodCallHandler(_handleMethodCall); + _installMethodCallHandler(); } + static const _handlerRetryInterval = Duration(milliseconds: 500); + static const _maxHandlerRetries = 120; + /// The method channel used to interact with the native platform. final _methodChannel = const MethodChannel('posthog_flutter'); - OnFeatureFlagsCallback? _onFeatureFlagsCallback; + bool _handlerInstalled = false; + Timer? _handlerRetry; PushIdentityProvider? _pushIdentityProvider; @@ -48,8 +54,41 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { final _order = CallOrder(); - Future _invoke(String method, [Object? arguments]) => - _order.run(() => _methodChannel.invokeMethod(method, arguments)); + Future _invoke(String method, [Object? arguments]) { + if (!_installMethodCallHandler()) { + // Callers already fall back on a PlatformException. Waiting for the + // binding instead would hang an app awaiting setup() before creating it. + return Future.error(PlatformException( + code: 'binding_not_initialized', + message: 'Skipped $method: the Flutter binding is not initialized.', + )); + } + return _order.run(() => _methodChannel.invokeMethod(method, arguments)); + } + + /// Returns whether the channel is ready. Without a binding it isn't, and the + /// timer covers apps whose native SDK auto-inits and that make no later call. + /// Native loads sent in the meantime wait in the channel's buffer. + bool _installMethodCallHandler() { + if (_handlerInstalled) return true; + try { + _methodChannel.setMethodCallHandler(_handleMethodCall); + _handlerInstalled = true; + _handlerRetry?.cancel(); + } catch (_) { + if (_handlerRetry == null) { + debugPrint( + '[PostHog] Call WidgetsFlutterBinding.ensureInitialized() before ' + 'setup(). SDK calls are skipped until the binding is initialized.', + ); + _handlerRetry = Timer.periodic(_handlerRetryInterval, (timer) { + if (timer.tick >= _maxHandlerRetries) timer.cancel(); + _installMethodCallHandler(); + }); + } + } + return _handlerInstalled; + } /// Applies the beforeSend callbacks to an event in order. /// Returns the possibly modified event, or null if any callback drops it. @@ -83,8 +122,16 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { await cleanupSurveys(); return null; case 'onFeatureFlagsCallback': - _onFeatureFlagsCallback - ?.call(featureFlagsLoadedFromMap(call.arguments)); + final arguments = call.arguments; + // Sent before the native SDK got the latest reset() or close(), so + // these may be the previous user's flags. + if (arguments is! Map || + arguments['generation'] != + FeatureFlagsListeners.instance.generation) { + break; + } + FeatureFlagsListeners.instance + .deliver(featureFlagsLoadedFromMap(call.arguments)); break; case 'pushIdentityProvider': // Returning a value here is the reply the native SDK awaits. @@ -201,6 +248,9 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { SurveyService().hideSurvey(); } + Map _flagsGenerationArguments() => + {'flagsGeneration': FeatureFlagsListeners.instance.generation}; + /// Flutter to Native Calls /// @override @@ -212,7 +262,6 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { return; } - _onFeatureFlagsCallback = config.onFeatureFlags; _pushIdentityProvider = config.pushIdentityProvider; _beforeSendCallbacks = config.beforeSend; @@ -220,6 +269,7 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { await _invoke('setup', { ...config.toMap(), ...flutterVersionSetupArguments(), + ..._flagsGenerationArguments(), }); } on PlatformException catch (exception) { printIfDebug('Exeption on setup: $exception'); @@ -602,7 +652,7 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { } try { - await _invoke('reset'); + await _invoke('reset', _flagsGenerationArguments()); } on PlatformException catch (exception) { printIfDebug('Exeption on reset: $exception'); } @@ -1006,7 +1056,7 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { } try { - return await _invoke('close'); + return await _invoke('close', _flagsGenerationArguments()); } on PlatformException catch (exception) { printIfDebug('Exeption on close: $exception'); } diff --git a/posthog_flutter/lib/src/posthog_flutter_web_handler.dart b/posthog_flutter/lib/src/posthog_flutter_web_handler.dart index 2772007e..1f070ad7 100644 --- a/posthog_flutter/lib/src/posthog_flutter_web_handler.dart +++ b/posthog_flutter/lib/src/posthog_flutter_web_handler.dart @@ -67,7 +67,8 @@ extension PostHogExtension on PostHog { external void unregister(JSAny key); // ignore: non_constant_identifier_names external JSAny? get_session_id(); - external JSFunction onFeatureFlags(JSFunction callback); + // The loader snippet's stub returns undefined until posthog-js loads. + external JSFunction? onFeatureFlags(JSFunction callback); external void startSessionRecording(); external void stopSessionRecording(); external bool sessionRecordingStarted(); @@ -292,7 +293,7 @@ Future> _reloadFeatureFlags(PostHog? ph) async { onTimeout: () => currentFlags(errorsLoading: true), ); } finally { - unsubscribe.callAsFunction(); + unsubscribe?.callAsFunction(); } } diff --git a/posthog_flutter/test/feature_flags_listener_auto_init_test.dart b/posthog_flutter/test/feature_flags_listener_auto_init_test.dart new file mode 100644 index 00000000..fc5061cb --- /dev/null +++ b/posthog_flutter/test/feature_flags_listener_auto_init_test.dart @@ -0,0 +1,34 @@ +import 'package:flutter/services.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:posthog_flutter/posthog_flutter.dart'; + +// Its own file so no earlier test has created the platform instance, as in an +// app where native auto-init ran and onFeatureFlags is the first Dart call. +void main() { + TestWidgetsFlutterBinding.ensureInitialized(); + + test('onFeatureFlags as the first SDK call receives native loads', () async { + const channel = MethodChannel('posthog_flutter'); + TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger + .setMockMethodCallHandler(channel, (_) async => null); + final received = []; + final subscription = Posthog().onFeatureFlags(received.add); + addTearDown(subscription.unsubscribe); + + ServicesBinding.instance.channelBuffers.push( + channel.name, + channel.codec + .encodeMethodCall(const MethodCall('onFeatureFlagsCallback', { + 'generation': 0, + 'variants': {'auto-init-flag': true}, + 'errorsLoading': false, + })), + (_) {}, + ); + await pumpEventQueue(); + + expect(received.map((loaded) => loaded.variants), [ + {'auto-init-flag': true} + ]); + }); +} diff --git a/posthog_flutter/test/feature_flags_listener_before_binding_test.dart b/posthog_flutter/test/feature_flags_listener_before_binding_test.dart new file mode 100644 index 00000000..ae49c754 --- /dev/null +++ b/posthog_flutter/test/feature_flags_listener_before_binding_test.dart @@ -0,0 +1,30 @@ +import 'package:flutter/services.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:posthog_flutter/posthog_flutter.dart'; + +// Its own file so the binding and the platform instance don't exist yet. +void main() { + test('listener added before the binding receives native loads', () async { + final received = []; + final subscription = Posthog().onFeatureFlags(received.add); + addTearDown(subscription.unsubscribe); + + TestWidgetsFlutterBinding.ensureInitialized(); + const channel = MethodChannel('posthog_flutter'); + ServicesBinding.instance.channelBuffers.push( + channel.name, + channel.codec + .encodeMethodCall(const MethodCall('onFeatureFlagsCallback', { + 'generation': 0, + 'variants': {'early-flag': true}, + 'errorsLoading': false, + })), + (_) {}, + ); + await Future.delayed(const Duration(seconds: 1)); + + expect(received.map((loaded) => loaded.variants), [ + {'early-flag': true} + ]); + }); +} diff --git a/posthog_flutter/test/feature_flags_listeners_test.dart b/posthog_flutter/test/feature_flags_listeners_test.dart new file mode 100644 index 00000000..3761a7b0 --- /dev/null +++ b/posthog_flutter/test/feature_flags_listeners_test.dart @@ -0,0 +1,104 @@ +import 'package:flutter_test/flutter_test.dart'; +import 'package:posthog_flutter/src/feature_flags_listeners.dart'; +import 'package:posthog_flutter/src/feature_flags_loaded.dart'; + +PostHogFeatureFlagsLoaded loaded(String variant) => PostHogFeatureFlagsLoaded( + variants: {'flag': variant}, errorsLoading: false); + +void main() { + final listeners = FeatureFlagsListeners.instance; + final subscriptions = []; + + PostHogFeatureFlagsSubscription listen( + List received) { + final subscription = listeners.add(received.add); + subscriptions.add(subscription); + return subscription; + } + + tearDown(() { + for (final subscription in subscriptions) { + subscription.unsubscribe(); + } + subscriptions.clear(); + listeners.clear(); + }); + + test('delivers each load until unsubscribed', () { + final received = []; + final subscription = listen(received); + final first = loaded('a'); + + listeners.deliver(first); + subscription.unsubscribe(); + listeners.deliver(loaded('b')); + + expect(received, [first]); + }); + + test('replays the last load to a new listener once', () async { + final last = loaded('a'); + listeners.deliver(last); + final received = []; + listen(received); + + await pumpEventQueue(); + + expect(received, [last]); + }); + + test('skips the replay when a newer load arrives first', () async { + listeners.deliver(loaded('a')); + final received = []; + listen(received); + final newer = loaded('b'); + listeners.deliver(newer); + + await pumpEventQueue(); + + expect(received, [newer]); + }); + + test('does not replay after clear', () async { + listeners.deliver(loaded('a')); + listeners.clear(); + final received = []; + listen(received); + + await pumpEventQueue(); + + expect(received, isEmpty); + }); + + test('delivers to the other listeners when one throws', () { + subscriptions.add(listeners.add((_) => throw StateError('listener'))); + final received = []; + listen(received); + final load = loaded('a'); + + listeners.deliver(load); + + expect(received, [load]); + }); + + test('skips a listener unsubscribed by an earlier one during delivery', () { + late PostHogFeatureFlagsSubscription second; + subscriptions.add(listeners.add((_) => second.unsubscribe())); + final received = []; + second = listen(received); + + listeners.deliver(loaded('a')); + + expect(received, isEmpty); + }); + + test('stops delivering a load cleared by an earlier listener', () { + subscriptions.add(listeners.add((_) => listeners.clear())); + final received = []; + listen(received); + + listeners.deliver(loaded('a')); + + expect(received, isEmpty); + }); +} diff --git a/posthog_flutter/test/posthog_before_binding_test.dart b/posthog_flutter/test/posthog_before_binding_test.dart new file mode 100644 index 00000000..109325da --- /dev/null +++ b/posthog_flutter/test/posthog_before_binding_test.dart @@ -0,0 +1,32 @@ +import 'package:flutter/services.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:posthog_flutter/posthog_flutter.dart'; + +// Its own file so the binding and the platform instance don't exist yet. +void main() { + test('calls before the binding fall back, then setup reaches native', + () async { + final posthog = Posthog(); + final config = PostHogConfig('test-token'); + + await posthog.setup(config); + await posthog.capture(eventName: 'early'); + await posthog.identify(userId: 'early'); + await posthog.captureException(error: StateError('early')); + expect(await posthog.isFeatureEnabled('flag'), isFalse); + expect(await posthog.getFeatureFlag('flag'), isNull); + + TestWidgetsFlutterBinding.ensureInitialized(); + const channel = MethodChannel('posthog_flutter'); + final methods = []; + TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger + .setMockMethodCallHandler(channel, (call) async { + methods.add(call.method); + return null; + }); + + await posthog.setup(config); + + expect(methods, ['setup']); + }); +} diff --git a/posthog_flutter/test/posthog_flutter_desktop_test.dart b/posthog_flutter/test/posthog_flutter_desktop_test.dart index 01541050..172ec20a 100644 --- a/posthog_flutter/test/posthog_flutter_desktop_test.dart +++ b/posthog_flutter/test/posthog_flutter_desktop_test.dart @@ -6,6 +6,7 @@ import 'package:flutter_test/flutter_test.dart'; import 'package:posthog_flutter/src/core/queue_worker.dart'; import 'package:posthog_flutter/src/error_tracking/posthog_error_tracking_autocapture_integration.dart'; import 'package:posthog_flutter/src/feature_flag_result.dart'; +import 'package:posthog_flutter/src/feature_flags_listeners.dart'; import 'package:posthog_flutter/src/feature_flags_loaded.dart'; import 'package:posthog_flutter/src/posthog_config.dart'; import 'package:posthog_flutter/src/posthog_desktop_app_info.dart'; @@ -841,7 +842,7 @@ void main() { test('properties the callbacks remove stay removed', () async { final server = await LocalPostHogServer.start(); server.respond = _answerFlags(_variantFlagResponse()); - final flagsLoaded = Completer(); + final flagsLoaded = _firstFlagsLoad(); Map? seen; final removed = [ r'$feature/variant-flag', @@ -849,9 +850,6 @@ void main() { r'$recording_status', ]; final config = configFor(server) - ..onFeatureFlags = (_) { - if (!flagsLoaded.isCompleted) flagsLoaded.complete(); - } ..beforeSend = [ (event) { seen = {...?event.properties}; @@ -861,7 +859,7 @@ void main() { }, ]; final platform = await setUpPlatform(config); - await flagsLoaded.future; + await flagsLoaded; await platform.capture(eventName: 'scrubbed'); @@ -897,12 +895,9 @@ void main() { test('SDK-internal events bypass the callbacks', () async { final server = await LocalPostHogServer.start(); server.respond = _answerFlags(_variantFlagResponse()); - final flagsLoaded = Completer(); + final flagsLoaded = _firstFlagsLoad(); final seenEventNames = []; final config = configFor(server) - ..onFeatureFlags = (_) { - if (!flagsLoaded.isCompleted) flagsLoaded.complete(); - } ..beforeSend = [ (event) { seenEventNames.add(event.event); @@ -910,7 +905,7 @@ void main() { }, ]; final platform = await setUpPlatform(config); - await flagsLoaded.future; + await flagsLoaded; await platform.getFeatureFlagResult(key: 'variant-flag'); await platform.capture(eventName: 'user event'); @@ -2062,13 +2057,10 @@ void main() { () async { final server = await LocalPostHogServer.start(); server.respond = _answerFlags(_variantFlagResponse()); - final flagsLoaded = Completer(); - final config = configFor(server) - ..onFeatureFlags = (_) { - if (!flagsLoaded.isCompleted) flagsLoaded.complete(); - }; + final flagsLoaded = _firstFlagsLoad(); + final config = configFor(server); final platform = await setUpPlatform(config); - await flagsLoaded.future; + await flagsLoaded; final silent = await platform.getFeatureFlagResult( key: 'variant-flag', @@ -2092,13 +2084,10 @@ void main() { () async { final server = await LocalPostHogServer.start(); server.respond = _answerFlags(_variantFlagResponse()); - final flagsLoaded = Completer(); - final config = configFor(server) - ..onFeatureFlags = (_) { - if (!flagsLoaded.isCompleted) flagsLoaded.complete(); - }; + final flagsLoaded = _firstFlagsLoad(); + final config = configFor(server); final platform = await setUpPlatform(config); - await flagsLoaded.future; + await flagsLoaded; await platform.captureFeatureView(flag: 'variant-flag'); await platform.captureFeatureInteraction( @@ -2128,13 +2117,10 @@ void main() { () async { final server = await LocalPostHogServer.start(); server.respond = _answerFlags(_variantFlagResponse()); - final flagsLoaded = Completer(); - final config = configFor(server) - ..onFeatureFlags = (_) { - if (!flagsLoaded.isCompleted) flagsLoaded.complete(); - }; + final flagsLoaded = _firstFlagsLoad(); + final config = configFor(server); final platform = await setUpPlatform(config); - await flagsLoaded.future; + await flagsLoaded; final distinctId = await platform.getDistinctId(); unawaited(platform.captureFeatureView(flag: 'variant-flag')); @@ -2153,13 +2139,9 @@ void main() { 'off-flag': {'key': 'off-flag', 'enabled': false}, }, }); - final flagsLoaded = Completer(); - final config = configFor(server) - ..onFeatureFlags = (_) { - if (!flagsLoaded.isCompleted) flagsLoaded.complete(); - }; - final platform = await setUpPlatform(config); - await flagsLoaded.future; + final flagsLoaded = _firstFlagsLoad(); + final platform = await setUpPlatform(configFor(server)); + await flagsLoaded; expect(await platform.isFeatureEnabled('missing', defaultValue: true), isTrue); @@ -2175,13 +2157,9 @@ void main() { test(r'$feature_flag_called does not report the defaultValue', () async { final server = await LocalPostHogServer.start(); server.respond = (_) => PostHogResponse.json(_variantFlagResponse()); - final flagsLoaded = Completer(); - final config = configFor(server) - ..onFeatureFlags = (_) { - if (!flagsLoaded.isCompleted) flagsLoaded.complete(); - }; - final platform = await setUpPlatform(config); - await flagsLoaded.future; + final flagsLoaded = _firstFlagsLoad(); + final platform = await setUpPlatform(configFor(server)); + await flagsLoaded; await platform.isFeatureEnabled('missing', defaultValue: true); @@ -2204,13 +2182,10 @@ void main() { test(r'sendFeatureFlagEvent false skips $feature_flag_called', () async { final server = await LocalPostHogServer.start(); server.respond = _answerFlags(_variantFlagResponse()); - final flagsLoaded = Completer(); - final config = configFor(server) - ..onFeatureFlags = (_) { - if (!flagsLoaded.isCompleted) flagsLoaded.complete(); - }; + final flagsLoaded = _firstFlagsLoad(); + final config = configFor(server); final platform = await setUpPlatform(config); - await flagsLoaded.future; + await flagsLoaded; expect( await platform.isFeatureEnabled('variant-flag', @@ -2230,14 +2205,10 @@ void main() { () async { final server = await LocalPostHogServer.start(); server.respond = _answerFlags(_variantFlagResponse()); - final flagsLoaded = Completer(); - final config = configFor(server) - ..sendFeatureFlagEvent = false - ..onFeatureFlags = (_) { - if (!flagsLoaded.isCompleted) flagsLoaded.complete(); - }; + final flagsLoaded = _firstFlagsLoad(); + final config = configFor(server)..sendFeatureFlagEvent = false; final platform = await setUpPlatform(config); - await flagsLoaded.future; + await flagsLoaded; expect( await platform.getFeatureFlag(key: 'variant-flag'), 'test-variant'); @@ -2290,9 +2261,10 @@ void main() { final server = await LocalPostHogServer.start(); server.respond = _answerFlags(_variantFlagResponse()); final announced = []; - final platform = await setUpPlatform(configFor(server) - ..preloadFeatureFlags = false - ..onFeatureFlags = announced.add); + final subscription = FeatureFlagsListeners.instance.add(announced.add); + addTearDown(subscription.unsubscribe); + final platform = + await setUpPlatform(configFor(server)..preloadFeatureFlags = false); final loaded = await platform.reloadFeatureFlags(); expect(loaded.variants, {'variant-flag': 'test-variant'}); @@ -2310,14 +2282,10 @@ void main() { () async { final server = await LocalPostHogServer.start(); server.respond = _answerFlags(_variantFlagResponse()); - final flagsLoaded = Completer(); - final config = configFor(server) - ..sendFeatureFlagEvent = false - ..onFeatureFlags = (_) { - if (!flagsLoaded.isCompleted) flagsLoaded.complete(); - }; + final flagsLoaded = _firstFlagsLoad(); + final config = configFor(server)..sendFeatureFlagEvent = false; final platform = await setUpPlatform(config); - await flagsLoaded.future; + await flagsLoaded; expect( (await platform.getFeatureFlagResult(key: 'variant-flag'))?.variant, @@ -2338,9 +2306,10 @@ void main() { final server = await LocalPostHogServer.start(); server.respond = (_) => PostHogResponse.json(_variantFlagResponse()); final announced = []; - final platform = await setUpPlatform(configFor(server) - ..preloadFeatureFlags = false - ..onFeatureFlags = announced.add); + final subscription = FeatureFlagsListeners.instance.add(announced.add); + addTearDown(subscription.unsubscribe); + final platform = + await setUpPlatform(configFor(server)..preloadFeatureFlags = false); final loaded = await platform.reloadFeatureFlags(); expect(loaded.variants, {'variant-flag': 'test-variant'}); @@ -2353,6 +2322,40 @@ void main() { expect(announced.last.errorsLoading, isTrue); }); + test('onFeatureFlags listeners receive each load', () async { + final server = await LocalPostHogServer.start(); + server.respond = (_) => PostHogResponse.json(_variantFlagResponse()); + final received = []; + final subscription = FeatureFlagsListeners.instance.add(received.add); + addTearDown(subscription.unsubscribe); + final platform = + await setUpPlatform(configFor(server)..preloadFeatureFlags = false); + + await platform.reloadFeatureFlags(); + + expect(received.last.variants, {'variant-flag': 'test-variant'}); + }); + + test('a reset started by a listener is not undone by the load', () async { + final server = await LocalPostHogServer.start(); + server.respond = (_) => PostHogResponse.json(_variantFlagResponse()); + FeatureFlagsListeners.instance.clear(); + // What reset() and close() do before reaching the platform. + final starter = FeatureFlagsListeners.instance + .add((_) => FeatureFlagsListeners.instance.clear()); + addTearDown(starter.unsubscribe); + final platform = + await setUpPlatform(configFor(server)..preloadFeatureFlags = false); + + await platform.reloadFeatureFlags(); + final received = []; + final subscription = FeatureFlagsListeners.instance.add(received.add); + addTearDown(subscription.unsubscribe); + await Future.delayed(Duration.zero); + + expect(received, isEmpty); + }); + test('onFeatureFlags reports the flags cached by the previous launch', () async { final server = await LocalPostHogServer.start(); @@ -2367,15 +2370,15 @@ void main() { final platform = createPlatform(appDirectory: appDirectory); final payloads = >[]; final announced = Completer(); - await platform.setup(configFor(server) - ..preloadFeatureFlags = false - ..onFeatureFlags = (_) { - payloads.add(platform - .getFeatureFlagResult( - key: 'variant-flag', sendFeatureFlagEvent: false) - .then((result) => result?.payload)); - if (!announced.isCompleted) announced.complete(); - }); + final subscription = FeatureFlagsListeners.instance.add((_) { + payloads.add(platform + .getFeatureFlagResult( + key: 'variant-flag', sendFeatureFlagEvent: false) + .then((result) => result?.payload)); + if (!announced.isCompleted) announced.complete(); + }); + addTearDown(subscription.unsubscribe); + await platform.setup(configFor(server)..preloadFeatureFlags = false); await announced.future; expect(await Future.wait(payloads), [ @@ -2387,6 +2390,16 @@ void main() { }); } +Future _firstFlagsLoad() { + FeatureFlagsListeners.instance.clear(); + final loaded = Completer(); + final subscription = FeatureFlagsListeners.instance.add((_) { + if (!loaded.isCompleted) loaded.complete(); + }); + addTearDown(subscription.unsubscribe); + return loaded.future; +} + Map _propertiesOf(Map event) => Map.from(event['properties']! as Map); diff --git a/posthog_flutter/test/posthog_flutter_io_test.dart b/posthog_flutter/test/posthog_flutter_io_test.dart index af8dfb1c..e4b59c14 100644 --- a/posthog_flutter/test/posthog_flutter_io_test.dart +++ b/posthog_flutter/test/posthog_flutter_io_test.dart @@ -3,10 +3,13 @@ import 'package:flutter/services.dart'; import 'package:flutter_test/flutter_test.dart'; import 'package:posthog_flutter/src/feature_flag_result.dart'; import 'package:posthog_flutter/src/logs/posthog_log_severity.dart'; +import 'package:posthog_flutter/src/feature_flags_listeners.dart'; import 'package:posthog_flutter/src/feature_flags_loaded.dart'; import 'package:posthog_flutter/src/posthog_config.dart'; import 'package:posthog_flutter/src/posthog_event.dart'; +import 'package:posthog_flutter/src/posthog.dart'; import 'package:posthog_flutter/src/posthog_flutter_io.dart'; +import 'package:posthog_flutter/src/posthog_flutter_platform_interface.dart'; import 'package:posthog_flutter/src/posthog_internal_events.dart'; // Simplified void callback for feature flags @@ -242,33 +245,13 @@ isolate_dso_base: 7000000000 }); group('PosthogFlutterIO onFeatureFlags via setup', () { - test( - 'setup initializes method call handler and registers callback if provided', - () async { - bool callbackInvoked = false; - void testCallback(PostHogFeatureFlagsLoaded _) { - callbackInvoked = true; - } - - testConfig = PostHogConfig( - 'test_project_token', - onFeatureFlags: testCallback, - ); - await posthogFlutterIO.setup(testConfig); - - // To verify handler is set, we trigger the callback from native side - await TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger - .handlePlatformMessage( - channel.name, - channel.codec.encodeMethodCall( - const MethodCall('onFeatureFlagsCallback', {}), - ), - (ByteData? data) {}, - ); - expect(callbackInvoked, isTrue); - expect(log.any((call) => call.method == 'setup'), isTrue); - }, - ); + // The native SDKs tag each load with the generation they last got. + Map nativeFlagsArgs(Map args, + {int? generation}) => + { + ...args, + 'generation': generation ?? FeatureFlagsListeners.instance.generation, + }; test('setup sends projectToken', () async { testConfig = PostHogConfig(' \n test_project_token\t '); @@ -296,20 +279,42 @@ isolate_dso_base: 7000000000 }, ); - test('passes the native flags to the callback', () async { + test('passes empty flags to listeners for malformed native args', () async { + FeatureFlagsListeners.instance.clear(); final received = []; - await posthogFlutterIO.setup( - PostHogConfig('test_project_token', onFeatureFlags: received.add)); + final subscription = FeatureFlagsListeners.instance.add(received.add); + addTearDown(subscription.unsubscribe); + await posthogFlutterIO.setup(PostHogConfig('test_project_token')); await TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger .handlePlatformMessage( channel.name, - channel.codec.encodeMethodCall(const MethodCall( + channel.codec.encodeMethodCall( + MethodCall( + 'onFeatureFlagsCallback', nativeFlagsArgs({'variants': 123})), + ), + (ByteData? data) {}, + ); + + expect(received.single.variants, isEmpty); + }); + + test('passes the native flags to onFeatureFlags listeners', () async { + FeatureFlagsListeners.instance.clear(); + final received = []; + final subscription = FeatureFlagsListeners.instance.add(received.add); + addTearDown(subscription.unsubscribe); + await posthogFlutterIO.setup(PostHogConfig('test_project_token')); + + await TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger + .handlePlatformMessage( + channel.name, + channel.codec.encodeMethodCall(MethodCall( 'onFeatureFlagsCallback', - { + nativeFlagsArgs({ 'variants': {'on': true, 'variant': 'test', 'off': false}, 'errorsLoading': true, - }, + }), )), (ByteData? data) {}, ); @@ -319,25 +324,118 @@ isolate_dso_base: 7000000000 expect(received.single.errorsLoading, isTrue); }); - test('passes empty flags to the callback for malformed native args', - () async { + Future sendNativeFlags({int? generation}) => + TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger + .handlePlatformMessage( + channel.name, + channel.codec.encodeMethodCall(MethodCall( + 'onFeatureFlagsCallback', + nativeFlagsArgs({ + 'variants': {'old-user-only': true}, + 'errorsLoading': false, + }, generation: generation), + )), + (ByteData? data) {}, + ); + + for (final (name, transition) in <(String, Future Function())>[ + ('reset', () => Posthog().reset()), + ('close', () => Posthog().close()), + ]) { + test('drops a native load sent before the $name reached native', + () async { + FeatureFlagsListeners.instance.clear(); + PosthogFlutterPlatformInterface.instance = posthogFlutterIO; + final received = []; + final subscription = FeatureFlagsListeners.instance.add(received.add); + addTearDown(subscription.unsubscribe); + await posthogFlutterIO.setup(PostHogConfig('test_project_token')); + final before = FeatureFlagsListeners.instance.generation; + + await transition(); + await sendNativeFlags(generation: before); + await Future.delayed(Duration.zero); + + expect(received, isEmpty); + expect((log.last.arguments as Map)['flagsGeneration'], + FeatureFlagsListeners.instance.generation); + }); + } + + for (final (name, transition) in <(String, Future Function())>[ + ('reset', () => Posthog().reset()), + ('close', () => Posthog().close()), + ]) { + test('a $name started by a listener is not undone by the load', () async { + FeatureFlagsListeners.instance.clear(); + PosthogFlutterPlatformInterface.instance = posthogFlutterIO; + Future? pending; + final starter = + FeatureFlagsListeners.instance.add((_) => pending ??= transition()); + addTearDown(starter.unsubscribe); + await posthogFlutterIO.setup(PostHogConfig('test_project_token')); + + await sendNativeFlags(); + await pending; + final received = []; + final subscription = FeatureFlagsListeners.instance.add(received.add); + addTearDown(subscription.unsubscribe); + await Future.delayed(Duration.zero); + + expect(received, isEmpty); + }); + } + + for (final (name, transition) in <(String, Future Function())>[ + ('reset', () => Posthog().reset()), + ('close', () => Posthog().close()), + ]) { + test('a $name started by a listener keeps the load from the rest', + () async { + FeatureFlagsListeners.instance.clear(); + PosthogFlutterPlatformInterface.instance = posthogFlutterIO; + final received = []; + await posthogFlutterIO.setup(PostHogConfig('test_project_token')); + Future? pending; + final first = + FeatureFlagsListeners.instance.add((_) => pending ??= transition()); + final second = FeatureFlagsListeners.instance.add(received.add); + addTearDown(first.unsubscribe); + addTearDown(second.unsubscribe); + + await sendNativeFlags(); + await pending; + + expect(received, isEmpty); + }); + } + + void mockReload(Future Function() reload) { + TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger + .setMockMethodCallHandler(channel, (call) async { + log.add(call); + return call.method == 'reloadFeatureFlags' ? reload() : null; + }); + } + + const reloaded = { + 'variants': {'manual': true}, + 'errorsLoading': false, + }; + + test('reload result is left to the native notification', () async { + FeatureFlagsListeners.instance.clear(); + mockReload(() async => reloaded); final received = []; - await posthogFlutterIO.setup( - PostHogConfig('test_project_token', onFeatureFlags: received.add)); + final subscription = FeatureFlagsListeners.instance.add(received.add); + addTearDown(subscription.unsubscribe); - await TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger - .handlePlatformMessage( - channel.name, - channel.codec.encodeMethodCall( - const MethodCall('onFeatureFlagsCallback', {'variants': 123}), - ), - (ByteData? data) {}, - ); + await posthogFlutterIO.reloadFeatureFlags(); - expect(received.single.variants, isEmpty); + expect(received, isEmpty); }); - test('does not invoke callback when no callback is registered', () async { + test('replies to a native load with no listener registered', () async { // Setup without callback testConfig = PostHogConfig('test_project_token'); await posthogFlutterIO.setup(testConfig); @@ -347,7 +445,7 @@ isolate_dso_base: 7000000000 .handlePlatformMessage( channel.name, channel.codec.encodeMethodCall( - const MethodCall('onFeatureFlagsCallback', {}), + MethodCall('onFeatureFlagsCallback', nativeFlagsArgs({})), ), (ByteData? data) => reply = data, ); diff --git a/posthog_flutter/test/posthog_flutter_platform_interface_fake.dart b/posthog_flutter/test/posthog_flutter_platform_interface_fake.dart index 22b064ff..79183964 100644 --- a/posthog_flutter/test/posthog_flutter_platform_interface_fake.dart +++ b/posthog_flutter/test/posthog_flutter_platform_interface_fake.dart @@ -82,7 +82,6 @@ class PosthogFlutterPlatformFake extends PosthogFlutterPlatformInterface { } String? screenName; - OnFeatureFlagsCallback? registeredOnFeatureFlagsCallback; final List capturedExceptions = []; PostHogConfig? receivedConfig; @@ -258,7 +257,6 @@ class PosthogFlutterPlatformFake extends PosthogFlutterPlatformInterface { @override Future setup(PostHogConfig config) async { receivedConfig = config; - registeredOnFeatureFlagsCallback = config.onFeatureFlags; // Simulate async operation if needed, but for fake, direct assignment is often enough. return Future.value(); } diff --git a/posthog_flutter/test/posthog_flutter_web_setup_test.dart b/posthog_flutter/test/posthog_flutter_web_setup_test.dart index 718ad35b..cd0d788e 100644 --- a/posthog_flutter/test/posthog_flutter_web_setup_test.dart +++ b/posthog_flutter/test/posthog_flutter_web_setup_test.dart @@ -2,10 +2,13 @@ library; import 'dart:async'; +import 'dart:js_interop'; +import 'dart:js_interop_unsafe'; import 'package:flutter_test/flutter_test.dart'; import 'package:posthog_flutter/posthog_flutter.dart'; import 'package:posthog_flutter/posthog_flutter_web.dart'; +import 'package:posthog_flutter/src/feature_flags_listeners.dart'; import 'package:posthog_flutter/src/replay/web/web_canvas_mask_provider.dart'; /// posthog-js is initialized by the host app on web, so options the plugin @@ -63,4 +66,127 @@ void main() { expect(logs.where((line) => line.contains('evaluationContexts')), hasLength(1)); }); + + test('delivers posthog-js flag loads to onFeatureFlags listeners once', + () async { + final listeners = []; + globalContext.setProperty( + 'posthog'.toJS, + JSObject() + ..setProperty( + 'onFeatureFlags'.toJS, + ((JSFunction callback) { + listeners.add(callback); + return (() => listeners.remove(callback)).toJS; + }).toJS, + )); + addTearDown(() => globalContext.delete('posthog'.toJS)); + final received = []; + final subscription = FeatureFlagsListeners.instance.add(received.add); + addTearDown(subscription.unsubscribe); + final web = PosthogFlutterWeb(); + + await web.setup(PostHogConfig('test_project_token')); + await web.setup(PostHogConfig('test_project_token')); + for (final listener in listeners.toList()) { + listener.callAsFunction(null, ['on'].jsify(), {'on': true}.jsify(), null); + } + + expect(received.single.variants, {'on': true}); + }); + + List stubPosthogJs() { + final listeners = []; + globalContext.setProperty( + 'posthog'.toJS, + JSObject() + ..setProperty( + 'onFeatureFlags'.toJS, + ((JSFunction callback) { + listeners.add(callback); + return (() => listeners.remove(callback)).toJS; + }).toJS, + )); + addTearDown(() => globalContext.delete('posthog'.toJS)); + return listeners; + } + + void loadFlags(List listeners) { + for (final listener in listeners.toList()) { + listener.callAsFunction(null, ['on'].jsify(), {'on': true}.jsify(), null); + } + } + + test('a reset started by a listener is not undone by the load', () async { + final listeners = stubPosthogJs(); + FeatureFlagsListeners.instance.clear(); + + // What reset() and close() do before reaching the platform. + final starter = FeatureFlagsListeners.instance + .add((_) => FeatureFlagsListeners.instance.clear()); + addTearDown(starter.unsubscribe); + await PosthogFlutterWeb().setup(PostHogConfig('test_project_token')); + loadFlags(listeners); + final received = []; + final subscription = FeatureFlagsListeners.instance.add(received.add); + addTearDown(subscription.unsubscribe); + await Future.delayed(Duration.zero); + + expect(received, isEmpty); + }); + + test('close() during the synchronous flag replay removes the registration', + () async { + final listeners = []; + globalContext.setProperty( + 'posthog'.toJS, + JSObject() + ..setProperty( + 'onFeatureFlags'.toJS, + ((JSFunction callback) { + listeners.add(callback); + // posthog-js calls back right away when flags are loaded. + callback.callAsFunction( + null, ['on'].jsify(), {'on': true}.jsify(), null); + return (() => listeners.remove(callback)).toJS; + }).toJS, + )); + addTearDown(() => globalContext.delete('posthog'.toJS)); + final web = PosthogFlutterWeb(); + + final closer = FeatureFlagsListeners.instance.add((_) => web.close()); + addTearDown(closer.unsubscribe); + await web.setup(PostHogConfig('test_project_token')); + + expect(listeners, isEmpty); + }); + + test('registrations queued by the posthog-js loader stop after close()', + () async { + // The loader snippet queues calls and returns undefined until it loads. + final queued = []; + globalContext.setProperty( + 'posthog'.toJS, + JSObject() + ..setProperty( + 'onFeatureFlags'.toJS, + ((JSFunction callback) { + queued.add(callback); + }).toJS, + )); + addTearDown(() => globalContext.delete('posthog'.toJS)); + FeatureFlagsListeners.instance.clear(); + final received = []; + final subscription = FeatureFlagsListeners.instance.add(received.add); + addTearDown(subscription.unsubscribe); + final web = PosthogFlutterWeb(); + + await web.setup(PostHogConfig('test_project_token')); + await web.setup(PostHogConfig('test_project_token')); + loadFlags(queued); + await web.close(); + loadFlags(queued); + + expect(received.single.variants, {'on': true}); + }); } diff --git a/posthog_flutter/test/posthog_test.dart b/posthog_flutter/test/posthog_test.dart index 6ad2c76c..a6480533 100644 --- a/posthog_flutter/test/posthog_test.dart +++ b/posthog_flutter/test/posthog_test.dart @@ -4,6 +4,7 @@ import 'package:flutter/foundation.dart'; import 'package:flutter/widgets.dart'; import 'package:flutter_test/flutter_test.dart'; import 'package:posthog_flutter/posthog_flutter.dart'; +import 'package:posthog_flutter/src/feature_flags_listeners.dart'; import 'package:posthog_flutter/src/posthog_flutter_platform_interface.dart'; import 'package:posthog_flutter/src/posthog_internal_events.dart'; import 'package:posthog_flutter/src/replay/mask/posthog_mask_controller.dart'; @@ -25,25 +26,35 @@ void main() { }); test( - 'setup passes config and onFeatureFlags callback to platform interface', + 'setup passes config to platform interface', () async { - void testCallback(PostHogFeatureFlagsLoaded _) {} - - final config = PostHogConfig( - 'test_project_token', - onFeatureFlags: testCallback, - ); + final config = PostHogConfig('test_project_token'); await Posthog().setup(config); expect(fakePlatformInterface.receivedConfig, equals(config)); - expect( - fakePlatformInterface.registeredOnFeatureFlagsCallback, - equals(testCallback), - ); }, ); + for (final entry in Function()>{ + 'reset': () => Posthog().reset(), + 'close': () => Posthog().close(), + }.entries) { + test('onFeatureFlags does not replay flags loaded before ${entry.key}', + () async { + FeatureFlagsListeners.instance.deliver(PostHogFeatureFlagsLoaded( + variants: {'flag': true}, errorsLoading: false)); + await entry.value(); + final received = []; + final subscription = Posthog().onFeatureFlags(received.add); + addTearDown(subscription.unsubscribe); + + await pumpEventQueue(); + + expect(received, isEmpty); + }); + } + for (final token in [' \n\t ', 'phx_personal_api_key']) { test('setup is skipped for the project token "$token"', () async { final lines = []; diff --git a/posthog_flutter/test/snapshots/setup_request.json b/posthog_flutter/test/snapshots/setup_request.json index 367138b4..53afe1ce 100644 --- a/posthog_flutter/test/snapshots/setup_request.json +++ b/posthog_flutter/test/snapshots/setup_request.json @@ -77,7 +77,8 @@ "color": "blue" } } - } + }, + "flagsGeneration": 1 } } ] From 0b49d5f3f2b94e808e81c7d4bbd2900ab200ac12 Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Tue, 3 Nov 2026 15:55:48 -0500 Subject: [PATCH 22/28] ci: run the capture v1 compliance suites against the real desktop client (#690) * ci: run the capture v1 compliance suites against the real desktop client The adapter posted events to /batch with its own sender, so the harness never exercised the SDK's capture v1 code. It now captures through DesktopPostHog and records requests with a local forwarding proxy. Co-Authored-By: Claude Opus 5.5 * ci: read the adapter's pending events from the SDK queues Co-Authored-By: Claude Opus 5.5 * ci: keep status and redirects as the SDK would see them in the adapter proxy Co-Authored-By: Claude Opus 5.5 * ci: bound how long the adapter proxy waits for the harness Co-Authored-By: Claude Opus 5.5 * ci: fail the check when the compliance suites fail Co-Authored-By: Claude Opus 5.5 * ci: let the adapter proxy wait as long as the AI client Co-Authored-By: Claude Opus 5.5 * ci: run the compliance suites through the SDK's event and flag code The adapter called captureStateless and sent its own /flags request, so the suites skipped how the SDK builds events and evaluates flags. Events now go through prepareEvent and capturePrepared, and flags through reloadFeatureFlagsAsync and getFeatureFlagResult. Co-Authored-By: Claude Opus 5.5 * ci: keep flag state per user and count captures as they happen Co-Authored-By: Claude Opus 5.5 * ci: skip the anonymous flag reload when the adapter switches users reset() reloads flags for its rotated anonymous id before the adapter sets the requested user. That sent an extra request, and its flags were served if the user's own reload then failed. * ci: pass non-HTTP redirects through the compliance proxy Uri.origin throws for other schemes and hostless URLs, so the proxy answered 502 and the SDK retried a redirect it treats as terminal. * docs: list the recording proxy test in the adapter test command * test: expect a 2xx without readable results to be dropped in the adapter Capture now drops such a batch for good, like posthog-ios and posthog-android. The redirect test answers with per-event results, and the truncated-body test expects a drop with no retry. * test(compliance): declare property_layers, fail_open, generated_payloads and log_capture The adapter now runs the configured beforeSend callbacks with the SDK's applyBeforeSend, registers super_properties, routes /init through the same project-token check Posthog.setup uses (extracted to isUsableProjectToken), pads /capture_ai properties for the event-size tests and records debugPrint lines for /state. Co-Authored-By: Claude Opus 5.5 * test: drive the compliance adapter through the real desktop plugin The adapter hand-copied the plugin's capture steps, so the suites could pass on code apps don't run. PosthogFlutterDesktop now takes an optional test-only client factory, and the adapter captures through the plugin's capture() and captureAi(), with the harness's distinct id and timestamp set on the injected client. Co-Authored-By: Claude Opus 5.5 * test(compliance): admit the trimmed project token, as public setup does Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --- .github/workflows/ci.yml | 2 +- .github/workflows/sdk-compliance.yml | 1 + CONTRIBUTING.md | 2 +- .../lib/src/core/posthog_core_stateless.dart | 4 + posthog_flutter/lib/src/posthog.dart | 14 +- .../lib/src/posthog_flutter_desktop.dart | 33 +- .../lib/src/utils/project_token.dart | 19 + .../lib/adapter_server.dart | 928 +++++++++--------- .../feature_flag_has_experiment_test.dart | 5 +- .../test/flags_retry_test.dart | 72 +- .../test/minimal_flag_called_events_test.dart | 113 ++- .../test/recording_proxy_test.dart | 196 ++++ 12 files changed, 844 insertions(+), 545 deletions(-) create mode 100644 posthog_flutter/lib/src/utils/project_token.dart create mode 100644 sdk_compliance_adapter/test/recording_proxy_test.dart diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 90b5ae42..ebc91dab 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -167,7 +167,7 @@ jobs: - name: Test compliance adapter if: needs.detect-markdown-only.outputs.markdown_only != 'true' working-directory: ./sdk_compliance_adapter - run: flutter test test/feature_flag_has_experiment_test.dart test/flags_retry_test.dart test/minimal_flag_called_events_test.dart test/timestamp_test.dart + run: flutter test test/feature_flag_has_experiment_test.dart test/flags_retry_test.dart test/minimal_flag_called_events_test.dart test/recording_proxy_test.dart test/timestamp_test.dart # Browser-only tests (`@TestOn('browser')`) are skipped by the VM run above. - name: Test (web) diff --git a/.github/workflows/sdk-compliance.yml b/.github/workflows/sdk-compliance.yml index 8dd7ffe7..e6333cf2 100644 --- a/.github/workflows/sdk-compliance.yml +++ b/.github/workflows/sdk-compliance.yml @@ -19,3 +19,4 @@ jobs: adapter-dockerfile: "sdk_compliance_adapter/Dockerfile" adapter-context: "." test-harness-version: "1.26.0" + continue-on-error: false diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 396741f8..e10bd9fd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,7 +20,7 @@ make checkFormatSwift (cd posthog_flutter && flutter test) (cd posthog_flutter && flutter test --platform chrome test/posthog_flutter_web_handler_test.dart test/posthog_flutter_web_setup_test.dart test/posthog_widget_web_test.dart test/posthog_widget_test.dart test/web_before_send_test.dart test/web_canvas_mask_provider_test.dart) (cd posthog_flutter && flutter test --platform chrome --wasm test/posthog_isolate_error_handler_web_test.dart) -(cd sdk_compliance_adapter && flutter test test/feature_flag_has_experiment_test.dart test/flags_retry_test.dart test/minimal_flag_called_events_test.dart test/timestamp_test.dart) +(cd sdk_compliance_adapter && flutter test test/feature_flag_has_experiment_test.dart test/flags_retry_test.dart test/minimal_flag_called_events_test.dart test/recording_proxy_test.dart test/timestamp_test.dart) ``` The adapter's `test/adapter_server_test.dart` is the long-running compliance server, diff --git a/posthog_flutter/lib/src/core/posthog_core_stateless.dart b/posthog_flutter/lib/src/core/posthog_core_stateless.dart index a2f3f81a..89b79d6f 100644 --- a/posthog_flutter/lib/src/core/posthog_core_stateless.dart +++ b/posthog_flutter/lib/src/core/posthog_core_stateless.dart @@ -670,6 +670,10 @@ abstract class PostHogCoreStateless { }); } + /// How many events are waiting to be sent, AI events included. + @protected + int get queuedEventCount => _analytics.queue.length + _ai.queue.length; + /// Flushes the queues of pending events and AI events. /// If a flush is already in progress, returns the existing future to avoid /// concurrent flushes sending duplicate events. diff --git a/posthog_flutter/lib/src/posthog.dart b/posthog_flutter/lib/src/posthog.dart index 472ec804..f262041f 100644 --- a/posthog_flutter/lib/src/posthog.dart +++ b/posthog_flutter/lib/src/posthog.dart @@ -15,6 +15,7 @@ import 'posthog_flutter_platform_interface.dart'; import 'posthog_internal_events.dart'; import 'posthog_observer.dart'; import 'replay/mask/posthog_mask_controller.dart'; +import 'utils/project_token.dart'; /// Entry point for the PostHog Flutter SDK. /// @@ -69,18 +70,7 @@ class Posthog { /// ensure `com.posthog.posthog.AUTO_INIT: false` is set in your native /// configuration. Future setup(PostHogConfig config) { - if (config.projectToken.isEmpty) { - debugPrint( - '[PostHog] projectToken must not be blank. Setup skipped.', - ); - return Future.value(); - } - // Capture rejects a personal API key, so it is never sent. - if (config.projectToken.startsWith('phx_')) { - debugPrint( - '[PostHog] projectToken is a personal API key (phx_), not a project ' - 'token. Setup skipped.', - ); + if (!isUsableProjectToken(config.projectToken)) { return Future.value(); } diff --git a/posthog_flutter/lib/src/posthog_flutter_desktop.dart b/posthog_flutter/lib/src/posthog_flutter_desktop.dart index 043747a9..94b16b02 100644 --- a/posthog_flutter/lib/src/posthog_flutter_desktop.dart +++ b/posthog_flutter/lib/src/posthog_flutter_desktop.dart @@ -28,6 +28,14 @@ import 'utils/property_normalizer.dart'; typedef _ClientScope = ({String projectToken, String host}); +/// Builds the client [PosthogFlutterDesktop] runs on, in place of a plain +/// [DesktopPostHog]. +typedef DesktopClientFactory = DesktopPostHog Function( + PostHogConfig config, + FileStorage storage, + Map staticContext, +); + /// The Windows and Linux implementation, built on the pure-Dart /// [DesktopPostHog] client. /// @@ -42,9 +50,11 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { required Future Function() appDirectory, required DesktopAppInfo appInfo, required String? timezone, + @visibleForTesting DesktopClientFactory? createClient, }) : _appDirectory = appDirectory, _appInfo = appInfo, - _timezone = timezone; + _timezone = timezone, + _createClient = createClient; /// See [DesktopStorage.appDirectory]. final Future Function() _appDirectory; @@ -57,6 +67,8 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { final String? _timezone; + final DesktopClientFactory? _createClient; + DesktopPostHog? _client; /// The close() of the previous client. It keeps the storage directory @@ -165,14 +177,17 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { final storageDirectory = appDirectory == null ? null : DesktopStorage.projectDirectory(appDirectory, config.projectToken); - final client = DesktopPostHog( - config, - staticContext: collectDesktopContext(_appInfo), - timezone: _timezone, - storage: storageDirectory == null - ? FileStorage.memory() - : FileStorage(storageDirectory), - ); + final storage = storageDirectory == null + ? FileStorage.memory() + : FileStorage(storageDirectory); + final staticContext = collectDesktopContext(_appInfo); + final client = _createClient?.call(config, storage, staticContext) ?? + DesktopPostHog( + config, + staticContext: staticContext, + timezone: _timezone, + storage: storage, + ); _client = client; _clientScope = ( projectToken: config.projectToken, diff --git a/posthog_flutter/lib/src/utils/project_token.dart b/posthog_flutter/lib/src/utils/project_token.dart new file mode 100644 index 00000000..da9ff38c --- /dev/null +++ b/posthog_flutter/lib/src/utils/project_token.dart @@ -0,0 +1,19 @@ +import 'package:flutter/foundation.dart'; + +/// Whether `Posthog.setup` can use [projectToken]. When it can't, logs why +/// and returns false, and setup is skipped. +bool isUsableProjectToken(String projectToken) { + if (projectToken.isEmpty) { + debugPrint('[PostHog] projectToken must not be blank. Setup skipped.'); + return false; + } + // Capture rejects a personal API key, so it is never sent. + if (projectToken.startsWith('phx_')) { + debugPrint( + '[PostHog] projectToken is a personal API key (phx_), not a project ' + 'token. Setup skipped.', + ); + return false; + } + return true; +} diff --git a/sdk_compliance_adapter/lib/adapter_server.dart b/sdk_compliance_adapter/lib/adapter_server.dart index 43858465..8e6f0c3f 100644 --- a/sdk_compliance_adapter/lib/adapter_server.dart +++ b/sdk_compliance_adapter/lib/adapter_server.dart @@ -1,28 +1,41 @@ -// ignore_for_file: implementation_imports +// ignore_for_file: implementation_imports, invalid_use_of_visible_for_testing_member import 'dart:async'; import 'dart:convert'; import 'dart:io'; import 'dart:math'; +import 'package:flutter/foundation.dart'; + import 'package:posthog_flutter/posthog_flutter.dart'; -import 'package:posthog_flutter/src/posthog_flutter_platform_interface.dart'; +import 'package:posthog_flutter/src/core/capture_v1.dart'; +import 'package:posthog_flutter/src/core/feature_flags.dart'; +import 'package:posthog_flutter/src/core/file_storage.dart'; +import 'package:posthog_flutter/src/core/persistence.dart'; +import 'package:posthog_flutter/src/core/posthog_core.dart'; +import 'package:posthog_flutter/src/posthog_desktop_app_info.dart'; +import 'package:posthog_flutter/src/posthog_desktop_client.dart'; +import 'package:posthog_flutter/src/posthog_flutter_desktop.dart'; import 'package:posthog_flutter/src/posthog_flutter_version.dart'; +import 'package:posthog_flutter/src/utils/project_token.dart'; const _adapterVersion = '1.0.0'; const _defaultFlushAt = 100; const _defaultFlushIntervalMs = 500; -const _defaultMaxRetries = 3; +// The longest the SDK waits on any lane; it gives up on shorter lanes itself. +const _upstreamTimeout = captureAiDefaultTimeout; class ComplianceAdapter { - ComplianceAdapter() : platform = _CompliancePlatform() { - PosthogFlutterPlatformInterface.instance = platform; - } - - final _CompliancePlatform platform; + final _CompliancePlatform platform = _CompliancePlatform(); HttpServer? _server; + DebugPrintCallback? _debugPrint; Future start({int port = 8080}) async { + final debugPrintBefore = _debugPrint = debugPrint; + debugPrint = (message, {wrapWidth}) { + if (message != null) platform.state.logLines.add(message); + debugPrintBefore(message, wrapWidth: wrapWidth); + }; final server = await HttpServer.bind(InternetAddress.anyIPv4, port); _server = server; unawaited(_serve(server)); @@ -32,6 +45,7 @@ class ComplianceAdapter { Future close() async { await platform.resetAdapterState(); await _server?.close(force: true); + if (_debugPrint case final restored?) debugPrint = restored; } Future _serve(HttpServer server) async { @@ -54,7 +68,16 @@ class ComplianceAdapter { 'sdk_name': postHogFlutterSdkName, 'sdk_version': postHogFlutterVersion, 'adapter_version': _adapterVersion, - 'capabilities': ['capture_v0', 'encoding_gzip'], + 'capabilities': [ + 'capture_v1', + 'capture_ai_v1', + 'encoding_gzip', + 'event_options', + 'fail_open', + 'generated_payloads', + 'log_capture', + 'property_layers', + ], }); return; } @@ -63,13 +86,21 @@ class ComplianceAdapter { final body = await _readJson(request); final apiKey = body['api_key'] as String?; final host = body['host'] as String?; - if (apiKey == null || apiKey.isEmpty) { - await _sendJson(request, {'error': 'api_key is required'}, + if (apiKey == null) { + await _sendJson( + request, + { + 'error': 'api_key is required', + }, statusCode: 400); return; } if (host == null || host.isEmpty) { - await _sendJson(request, {'error': 'host is required'}, + await _sendJson( + request, + { + 'error': 'host is required', + }, statusCode: 400); return; } @@ -77,23 +108,15 @@ class ComplianceAdapter { final flushAt = _readInt(body['flush_at']) ?? _defaultFlushAt; final flushIntervalMs = _readInt(body['flush_interval_ms']) ?? _defaultFlushIntervalMs; - final maxRetries = _readInt(body['max_retries']) ?? _defaultMaxRetries; final enableCompression = body['enable_compression'] == true; - await platform.resetAdapterState(); - platform.configure( - apiKey: apiKey, - host: host, - flushAt: flushAt, - flushIntervalMs: flushIntervalMs, - maxRetries: maxRetries, - enableCompression: enableCompression, - ); - + final compression = + enableCompression ? PostHogCompression.gzip : PostHogCompression.none; final config = PostHogConfig(apiKey) - ..host = host ..flushAt = flushAt ..flushInterval = Duration(milliseconds: flushIntervalMs) + ..compression = compression + ..captureAiCompression = compression ..preloadFeatureFlags = false ..captureApplicationLifecycleEvents = false ..debug = true; @@ -104,24 +127,45 @@ class ComplianceAdapter { distinctId: bootstrap['distinct_id'] as String?, isIdentifiedId: bootstrap['is_identified_id'] == true, featureFlags: _readObjectMap(bootstrap['feature_flags']), - featureFlagPayloads: - _readNullableObjectMap(bootstrap['feature_flag_payloads']), + featureFlagPayloads: _readNullableObjectMap( + bootstrap['feature_flag_payloads'], + ), ); } - await Posthog().setup(config); + final beforeSend = _readNullableObjectMap(body['before_send']); + final setProperties = + _readObjectMap(beforeSend?['set_properties']) ?? const {}; + if (beforeSend != null) { + config.beforeSend = [ + (event) => + event..properties = {...?event.properties, ...setProperties}, + ]; + } + + await platform.resetAdapterState(); + if (isUsableProjectToken(config.projectToken)) { + await platform.configure( + config, + host: host, + superProperties: _readNullableObjectMap(body['super_properties']), + ); + } else { + platform.disable(); + } await _sendJson(request, {'success': true}); return; } - if (method == 'POST' && path == '/capture') { + if (method == 'POST' && (path == '/capture' || path == '/capture_ai')) { if (!platform.isInitialized) { await _sendJson( - request, - {'error': 'SDK not initialized'}, - statusCode: 400, - ); + request, + { + 'error': 'SDK not initialized', + }, + statusCode: 400); return; } @@ -130,37 +174,48 @@ class ComplianceAdapter { final event = body['event'] as String?; if (distinctId == null || distinctId.isEmpty) { await _sendJson( - request, - {'error': 'distinct_id is required'}, - statusCode: 400, - ); + request, + { + 'error': 'distinct_id is required', + }, + statusCode: 400); return; } if (event == null || event.isEmpty) { - await _sendJson(request, {'error': 'event is required'}, + await _sendJson( + request, + { + 'error': 'event is required', + }, statusCode: 400); return; } - final properties = _readObjectMap(body['properties']); - final timestamp = body['timestamp'] as String?; - platform.stageCapture(distinctId: distinctId, timestamp: timestamp); - await Posthog().capture(eventName: event, properties: properties); + final properties = _readNullableObjectMap(body['properties']) ?? {}; + final padToBytes = _readInt(body['pad_properties_to_bytes']); + final uuid = await platform.capture( + distinctId: distinctId, + event: event, + properties: padToBytes == null + ? properties + : _padProperties(properties, padToBytes, body['marker'] as String?), + options: _readNullableObjectMap(body['options']), + timestamp: body['timestamp'] as String?, + ai: path == '/capture_ai', + ); - await _sendJson(request, { - 'success': true, - 'uuid': platform.lastCapturedUuid, - }); + await _sendJson(request, {'success': true, 'uuid': uuid}); return; } if (method == 'POST' && path == '/get_feature_flag') { if (!platform.isInitialized) { await _sendJson( - request, - {'error': 'SDK not initialized'}, - statusCode: 400, - ); + request, + { + 'error': 'SDK not initialized', + }, + statusCode: 400); return; } @@ -173,10 +228,11 @@ class ComplianceAdapter { } if (distinctId == null || distinctId.isEmpty) { await _sendJson( - request, - {'error': 'distinct_id is required'}, - statusCode: 400, - ); + request, + { + 'error': 'distinct_id is required', + }, + statusCode: 400); return; } @@ -196,10 +252,11 @@ class ComplianceAdapter { if (method == 'POST' && path == '/flush') { if (!platform.isInitialized) { await _sendJson( - request, - {'error': 'SDK not initialized'}, - statusCode: 400, - ); + request, + { + 'error': 'SDK not initialized', + }, + statusCode: 400); return; } @@ -213,7 +270,7 @@ class ComplianceAdapter { } if (method == 'GET' && path == '/state') { - await _sendJson(request, platform.state.toJson()); + await _sendJson(request, platform.stateJson()); return; } @@ -227,455 +284,425 @@ class ComplianceAdapter { } } -class _CompliancePlatform extends PosthogFlutterPlatformInterface { - _AdapterState state = _AdapterState(); - final _random = Random.secure(); - - String? _apiKey; - String? _host; - int _flushAt = _defaultFlushAt; - int _flushIntervalMs = _defaultFlushIntervalMs; - int _maxRetries = _defaultMaxRetries; - bool _enableCompression = false; - bool _autoFlushPaused = false; - Timer? _flushTimer; - Future? _activeFlush; - String? _nextDistinctId; - String? _nextTimestamp; - - bool get isInitialized => _apiKey != null && _host != null; - String? lastCapturedUuid; - - void configure({ - required String apiKey, - required String host, - required int flushAt, - required int flushIntervalMs, - required int maxRetries, - required bool enableCompression, +/// The real client, run by the real desktop plugin, so the harness tests the +/// SDK's own event building, beforeSend, queue, flags and requests. The +/// harness sends a distinct id and a timestamp per call, which the plugin's +/// capture() doesn't take: the id would need identify(), which adds +/// `$identify` events to the batches the suites count. +class _CaptureClient extends DesktopPostHog { + _CaptureClient(PostHogConfig config, FileStorage storage) + : super( + config, + storage: storage, + staticContext: const {}, + timezone: null, + ); + + String? nextTimestamp; + String? lastUuid; + Map _flagsRequestFields = const {}; + String? _flagsUser; + bool _switchingFlagsUser = false; + void Function()? onCaptured; + + @override + ({String uuid, Future queued}) captureStateless( + String distinctId, + String event, { + required Map properties, + Map? options, + String? timestamp, }) { - _apiKey = apiKey; - _host = host; - _flushAt = max(1, flushAt); - _flushIntervalMs = max(1, flushIntervalMs); - _maxRetries = max(0, maxRetries); - _enableCompression = enableCompression; - _autoFlushPaused = false; - _flushTimer?.cancel(); - _flushTimer = Timer.periodic( - Duration(milliseconds: _flushIntervalMs), - (_) => unawaited(_flushFromTimer()), + final queued = super.captureStateless( + distinctId, + event, + properties: properties, + options: options, + timestamp: timestamp, ); + onCaptured?.call(); + return queued; } - void stageCapture({required String distinctId, String? timestamp}) { - _nextDistinctId = distinctId; - final parsedTimestamp = - timestamp == null ? null : DateTime.tryParse(timestamp); - _nextTimestamp = parsedTimestamp?.toUtc().toIso8601String(); + @override + Future captureAiStateless( + String distinctId, + String event, { + required Map properties, + Map? options, + String? timestamp, + }) async { + final uuid = await super.captureAiStateless( + distinctId, + event, + properties: properties, + options: options, + timestamp: timestamp, + ); + if (uuid != null) onCaptured?.call(); + return uuid; } - @override - Future setup(PostHogConfig config) async {} + void _actAs(String distinctId) { + setPersistedProperty(PostHogPersistedProperty.distinctId, distinctId); + setPersistedProperty(PostHogPersistedProperty.personMode, 'identified'); + } @override - Future reset() => resetAdapterState(); + PostHogPreparedEvent? prepareEvent( + String event, { + Map? properties, + Map? options, + }) { + final prepared = + super.prepareEvent(event, properties: properties, options: options); + final timestamp = nextTimestamp; + if (prepared == null || timestamp == null) return prepared; + return ( + properties: prepared.properties, + options: prepared.options, + timestamp: timestamp, + ); + } @override - Future capture({ - required String eventName, - Map? properties, - Map? userProperties, - Map? userPropertiesSetOnce, - Map? options, + Future capturePrepared( + String event, + PostHogPreparedEvent prepared, + ) => + super.capturePrepared(event, prepared).then((uuid) => lastUuid = uuid); + + Future evaluateFlag( + String key, { + required String distinctId, + required Map personProperties, + required Map groups, + required Map> groupProperties, + required bool disableGeoip, }) async { - if (!isInitialized) { - throw StateError('SDK not initialized'); + // A user's cached flags and reported flag calls must not serve the next. + if (_flagsUser != null && _flagsUser != distinctId) { + _switchingFlagsUser = true; + reset(); + _switchingFlagsUser = false; } - - final distinctId = _nextDistinctId; - if (distinctId == null || distinctId.isEmpty) { - throw StateError('distinct_id was not staged by the adapter'); + _flagsUser = distinctId; + _actAs(distinctId); + if (groups.isEmpty) { + unregister(r'$groups'); + } else { + register({r'$groups': groups}); } - - final stagedTimestamp = _nextTimestamp; - _nextDistinctId = null; - _nextTimestamp = null; - - final uuid = _uuidV4(); - lastCapturedUuid = uuid; - - final eventProperties = { - ...?properties, - 'distinct_id': distinctId, - 'token': _apiKey, - '\$lib': postHogFlutterSdkName, - '\$lib_version': postHogFlutterVersion, - if (userProperties != null && userProperties.isNotEmpty) - '\$set': userProperties, - if (userPropertiesSetOnce != null && userPropertiesSetOnce.isNotEmpty) - '\$set_once': userPropertiesSetOnce, + resetPersonPropertiesForFlags(); + setPersonPropertiesForFlags(personProperties); + resetGroupPropertiesForFlags(); + setGroupPropertiesForFlags(groupProperties); + _flagsRequestFields = { + 'geoip_disable': disableGeoip, + 'flag_keys_to_evaluate': [key], }; - - _autoFlushPaused = false; - state.queue.add({ - 'uuid': uuid, - 'event': eventName, - 'distinct_id': distinctId, - 'properties': eventProperties, - 'timestamp': stagedTimestamp ?? DateTime.now().toUtc().toIso8601String(), - }); - state.totalEventsCaptured++; - state.pendingEvents = state.queue.length; - - if (state.queue.length >= _flushAt) { - unawaited(flush()); - } + await reloadFeatureFlagsAsync(); + return getFeatureFlagResult(key, sendEvent: true); } - Future _flushFromTimer() { - if (_autoFlushPaused) { - return Future.value(); + // The harness tests these server-SDK fields, which the client doesn't send. + @override + Future getFlags( + String distinctId, { + required Map groups, + required Map personProperties, + required Map> groupProperties, + required Map extraPayload, + }) { + // reset() reloads for an anonymous id nobody asked about. Its answer could + // outlive a failed reload for the requested user, so no request is sent. + if (_switchingFlagsUser) { + return Future.value(GetFlagsFailure(const FeatureFlagRequestError( + type: FeatureFlagRequestErrorType.unknownError))); } - return flush(); + return super.getFlags( + distinctId, + groups: groups, + personProperties: personProperties, + groupProperties: groupProperties, + extraPayload: {...extraPayload, ..._flagsRequestFields}, + ); } @override - Future flush() { - final activeFlush = _activeFlush; - if (activeFlush != null) { - return activeFlush; - } + int get queuedEventCount => super.queuedEventCount; - final flushFuture = _flushInternal(); - _activeFlush = flushFuture; - return flushFuture.whenComplete(() { - if (identical(_activeFlush, flushFuture)) { - _activeFlush = null; - } - }); + void Function() onSent(void Function(int count) listener) => + events.on('flush', (sent) => listener((sent! as List).length)); + + void Function() onError(void Function(Object error) listener) => + events.on('error', (error) => listener(error!)); +} + +/// Forwards the SDK's capture requests to the harness and records them for +/// `/state`: the SDK doesn't expose what it sent. +class _RecordingProxy { + _RecordingProxy._(this._server, this._target, this._state); + + final HttpServer _server; + final Uri _target; + final _AdapterState _state; + final _client = HttpClient()..autoUncompress = false; + + String get url => 'http://127.0.0.1:${_server.port}'; + + static Future<_RecordingProxy> start(String host, _AdapterState state) async { + final server = await HttpServer.bind(InternetAddress.loopbackIPv4, 0); + final proxy = _RecordingProxy._(server, Uri.parse(host), state); + unawaited(proxy._serve()); + return proxy; } - Future _flushInternal() async { - final flushState = state; - final apiKey = _apiKey; - final host = _host; - final maxRetries = _maxRetries; - final enableCompression = _enableCompression; - if (apiKey == null || host == null || flushState.queue.isEmpty) { - return; + Future close() async { + _client.close(force: true); + await _server.close(force: true); + } + + Future _serve() async { + await for (final request in _server) { + unawaited(_forward(request)); } + } - final batch = List>.from(flushState.queue); - final success = await _sendBatchWithRetries( - flushState, - batch, - apiKey: apiKey, - host: host, - maxRetries: maxRetries, - enableCompression: enableCompression, - ); - if (success) { - final sentUuids = batch.map((event) => event['uuid']).toSet(); - flushState.queue - .removeWhere((event) => sentUuids.contains(event['uuid'])); - flushState.pendingEvents = flushState.queue.length; - flushState.totalEventsSent += batch.length; - if (identical(state, flushState)) { - _autoFlushPaused = false; - } - } else { - flushState.pendingEvents = flushState.queue.length; - if (identical(state, flushState)) { - _autoFlushPaused = true; + Future _forward(HttpRequest request) async { + final response = request.response; + var headersSent = false; + try { + final body = await request.fold>( + [], + (bytes, chunk) => bytes..addAll(chunk), + ); + final upstream = await _client.openUrl( + request.method, + _target.replace( + path: request.uri.path, + query: request.uri.hasQuery ? request.uri.query : null, + ), + ); + request.headers.forEach((name, values) { + if (name != HttpHeaders.hostHeader && + name != HttpHeaders.contentLengthHeader) { + upstream.headers.set(name, values); + } + }); + // Redirects are the SDK's to follow or refuse. + upstream.followRedirects = false; + upstream.contentLength = body.length; + upstream.add(body); + final result = await upstream.close().timeout( + _upstreamTimeout, + onTimeout: () { + upstream.abort(); + throw TimeoutException('No response from the harness'); + }, + ); + _record(request, body, result.statusCode); + + response.statusCode = result.statusCode; + result.headers.forEach((name, values) { + if (name == HttpHeaders.locationHeader) { + response.headers.set(name, values.map(_proxyLocation).toList()); + } else if (name != HttpHeaders.contentLengthHeader && + name != HttpHeaders.transferEncodingHeader) { + response.headers.set(name, values); + } + }); + headersSent = true; + // Not addStream: a failing body would take the response down with it. + await for (final chunk in result) { + response.add(chunk); } + } catch (error) { + _state.lastError = error.toString(); + // After the headers the status stands: the SDK drops a 2xx whose body + // fails for good, so it must not turn into a retry here. + if (!headersSent) response.statusCode = HttpStatus.badGateway; } + await response.close(); } - Future _sendBatchWithRetries( - _AdapterState flushState, - List> batch, { - required String apiKey, - required String host, - required int maxRetries, - required bool enableCompression, - }) async { - for (var attempt = 0; attempt <= maxRetries; attempt++) { - final result = await _postBatch( - flushState, - batch, - attempt, - apiKey: apiKey, - host: host, - enableCompression: enableCompression, - ); - flushState.requestsMade.add(_RequestRecord( + /// The SDK only follows a redirect within the origin it was configured + /// with, which is this proxy's and not the harness's. + String _proxyLocation(String location) { + final uri = Uri.tryParse(location); + if (uri == null || + uri.scheme != _target.scheme || + uri.host != _target.host || + uri.port != _target.port) { + return location; + } + return uri.replace(host: '127.0.0.1', port: _server.port).toString(); + } + + void _record(HttpRequest request, List body, int statusCode) { + if (request.uri.path != captureV1Path && + request.uri.path != captureV1AiPath) { + return; + } + final gzipped = + request.headers.value(HttpHeaders.contentEncodingHeader) == 'gzip'; + final decoded = + jsonDecode(utf8.decode(gzipped ? gzip.decode(body) : body)) as Map; + final batch = decoded['batch'] as List; + final attempt = + int.tryParse(request.headers.value('PostHog-Attempt') ?? '') ?? 1; + if (attempt > 1) _state.totalRetries++; + if (statusCode < 200 || statusCode >= 300) { + _state.lastError = 'Capture request failed with HTTP $statusCode'; + } + _state.requestsMade.add( + _RequestRecord( timestampMs: DateTime.now().millisecondsSinceEpoch, - statusCode: result.statusCode, - retryAttempt: attempt, + statusCode: statusCode, + retryAttempt: attempt - 1, eventCount: batch.length, - uuidList: batch.map((event) => event['uuid']! as String).toList(), - )); + uuidList: [for (final event in batch) (event as Map)['uuid'] as String], + ), + ); + } +} - if (attempt > 0) { - flushState.totalRetries++; - } +class _CompliancePlatform { + _AdapterState state = _AdapterState(); - if (result.statusCode >= 200 && result.statusCode < 300) { - return true; - } + PosthogFlutterDesktop? _plugin; + _CaptureClient? _client; + _RecordingProxy? _proxy; + bool _initialized = false; - flushState.lastError = - 'Batch request failed with HTTP ${result.statusCode}'; - if (attempt < maxRetries && _shouldRetry(result.statusCode)) { - await Future.delayed( - Duration(milliseconds: result.retryAfterMs ?? 100), - ); - continue; - } - return false; - } - return false; - } + bool get isInitialized => _initialized; - bool _shouldRetry(int statusCode) => - statusCode == 408 || statusCode == 429 || statusCode >= 500; + /// Initialized as an app whose setup was skipped: every call is a no-op. + void disable() => _initialized = true; - Future<_PostResult> _postBatch( - _AdapterState flushState, - List> batch, - int attempt, { - required String apiKey, + Future configure( + PostHogConfig config, { required String host, - required bool enableCompression, + Map? superProperties, }) async { - final client = HttpClient(); - try { - final uri = Uri.parse(host).resolve( - attempt > 0 ? '/batch?retry_count=$attempt' : '/batch', - ); - final request = await client.postUrl(uri); - request.headers.contentType = ContentType.json; - request.headers.set( - HttpHeaders.userAgentHeader, - '$postHogFlutterSdkName/$postHogFlutterVersion', - ); - - final payload = jsonEncode({ - 'api_key': apiKey, - 'batch': batch, - 'sent_at': DateTime.now().toUtc().toIso8601String(), - }); - final body = utf8.encode(payload); - final bytesToSend = enableCompression ? gzip.encode(body) : body; - if (enableCompression) { - request.headers.set(HttpHeaders.contentEncodingHeader, 'gzip'); - } - request.contentLength = bytesToSend.length; - request.add(bytesToSend); - - final response = await request.close(); - final retryAfterMs = _retryAfterMs(response.headers); - await response.drain(); - return _PostResult(response.statusCode, retryAfterMs: retryAfterMs); - } catch (error) { - flushState.lastError = error.toString(); - return const _PostResult(500); - } finally { - client.close(force: true); + final proxy = await _RecordingProxy.start(host, state); + config.host = proxy.url; + _CaptureClient? created; + final plugin = PosthogFlutterDesktop( + appDirectory: () async => null, + appInfo: const DesktopAppInfo(), + timezone: null, + // No OS or app context: the suites expect exact property sets. + createClient: (config, storage, _) => + created = _CaptureClient(config, storage), + ); + await plugin.setup(config); + final client = created; + if (client == null) { + await proxy.close(); + throw StateError('The plugin did not start a client'); } + final clientState = state; + client.onCaptured = () => clientState.totalEventsCaptured++; + client.onSent((count) => clientState.totalEventsSent += count); + client.onError((error) => clientState.lastError = error.toString()); + if (superProperties != null) client.register(superProperties); + _proxy = proxy; + _plugin = plugin; + _client = client; + _initialized = true; } - Future evaluateFeatureFlag({ - required String key, + Future capture({ required String distinctId, - Map? personProperties, - Map? groups, - Map>? groupProperties, - required bool disableGeoip, + required String event, + required Map properties, + Map? options, + String? timestamp, + bool ai = false, }) async { - final payload = { - 'api_key': _apiKey, - 'distinct_id': distinctId, - 'person_properties': { - ...?personProperties, - 'distinct_id': distinctId, - }, - 'groups': groups ?? {}, - 'group_properties': groupProperties ?? >{}, - 'geoip_disable': disableGeoip, - 'flag_keys_to_evaluate': [key], + final plugin = _plugin; + final client = _client; + if (plugin == null || client == null) return null; + client._actAs(distinctId); + client.nextTimestamp = + DateTime.tryParse(timestamp ?? '')?.toUtc().toIso8601String(); + client.lastUuid = null; + final nonNull = { + for (final MapEntry(:key, :value) in properties.entries) + if (value != null) key: value, }; - - final client = HttpClient(); - Object? value = false; - bool? hasExperiment; - var minimalFlagCalledEvents = false; try { - final uri = Uri.parse(_host!).resolve('/flags/?v=2'); - for (var attempt = 0; attempt <= _maxRetries; attempt++) { - final request = await client.postUrl(uri); - request.headers.contentType = ContentType.json; - request.write(jsonEncode(payload)); - final response = await request.close(); - final retryAfterMs = _retryAfterMs(response.headers); - final body = await utf8.decoder.bind(response).join(); - final statusCode = response.statusCode; - if (attempt > 0) { - state.totalRetries++; - } - if (statusCode < 200 || statusCode >= 300) { - if (attempt < _maxRetries && _shouldRetryFlags(statusCode)) { - await Future.delayed( - Duration(milliseconds: retryAfterMs ?? 100), - ); - continue; - } - state.lastError = 'Feature flag request failed with HTTP $statusCode'; - throw HttpException(state.lastError!, uri: uri); - } - final decoded = body.isEmpty ? null : jsonDecode(body); - if (decoded is Map) { - final flags = decoded['featureFlags'] ?? decoded['flags']; - if (flags is Map && flags.containsKey(key)) { - final flag = flags[key]; - value = flag is Map ? flag['variant'] ?? flag['enabled'] : flag; - } - hasExperiment = _flagHasExperiment(decoded['flags'], key); - minimalFlagCalledEvents = decoded['minimalFlagCalledEvents'] == true; - } - break; + if (ai) { + return await plugin.captureAi( + eventName: event, + properties: nonNull, + options: options, + ); } + await plugin.capture( + eventName: event, + properties: nonNull, + options: options, + ); + return client.lastUuid; } finally { - client.close(force: true); + client.nextTimestamp = null; } + } - state.queue.add({ - 'uuid': _uuidV4(), - 'event': r'$feature_flag_called', - 'distinct_id': distinctId, - 'properties': _featureFlagCalledProperties( - key: key, - value: value, - distinctId: distinctId, - hasExperiment: hasExperiment, - minimalFlagCalledEvents: minimalFlagCalledEvents, - ), - 'timestamp': DateTime.now().toUtc().toIso8601String(), - }); - state.totalEventsCaptured++; - state.pendingEvents = state.queue.length; + Map stateJson() => + state.toJson(pendingEvents: _client?.queuedEventCount ?? 0); - return value; + Future flush() async { + try { + await _client?.flush(); + } catch (error) { + state.lastError = error.toString(); + } } - /// Builds the `$feature_flag_called` properties. - /// - /// When the `/flags?v=2` response carries top-level - /// `minimalFlagCalledEvents == true` and the flag is not linked to an - /// experiment (`has_experiment == false`), only the cross-SDK minimal - /// allowlist is sent. Any missing signal (either field absent, a legacy - /// response shape, or `has_experiment` unreported) falls back to the full - /// legacy shape. `distinct_id` and `token` are transport fields this - /// adapter carries in every event's properties and stay in both shapes. - Map _featureFlagCalledProperties({ + Future evaluateFeatureFlag({ required String key, - required Object? value, required String distinctId, - required bool? hasExperiment, - required bool minimalFlagCalledEvents, - }) { - final allowlisted = { - 'distinct_id': distinctId, - 'token': _apiKey, - r'$lib': postHogFlutterSdkName, - r'$lib_version': postHogFlutterVersion, - r'$feature_flag': key, - r'$feature_flag_response': value, - }; - if (minimalFlagCalledEvents && hasExperiment == false) { - return { - ...allowlisted, - r'$feature_flag_has_experiment': false, - }; - } - return { - ...allowlisted, - if (hasExperiment != null) r'$feature_flag_has_experiment': hasExperiment, - r'$feature/' + key: value, - }; - } - - /// Reads `metadata.has_experiment` from the `/flags?v=2` entry for [key]. - /// - /// Returns `null` when the server does not report it (e.g. legacy - /// `featureFlags` responses or metadata without a boolean value). - bool? _flagHasExperiment(Object? flags, String key) { - if (flags is! Map) return null; - final details = flags[key]; - if (details is! Map) return null; - final metadata = details['metadata']; - if (metadata is! Map) return null; - final hasExperiment = metadata['has_experiment']; - return hasExperiment is bool ? hasExperiment : null; - } - - bool _shouldRetryFlags(int statusCode) => - statusCode == 502 || statusCode == 504; - - int? _retryAfterMs(HttpHeaders headers) { - final value = headers.value(HttpHeaders.retryAfterHeader); - if (value == null) { - return null; - } - final seconds = int.tryParse(value); - if (seconds != null) { - return seconds * 1000; - } - final date = HttpDate.parse(value); - return date - .difference(DateTime.now().toUtc()) - .inMilliseconds - .clamp(0, 60000); + Map? personProperties, + Map? groups, + Map>? groupProperties, + required bool disableGeoip, + }) async { + final client = _client; + if (client == null) return false; + final result = await client.evaluateFlag( + key, + distinctId: distinctId, + personProperties: personProperties ?? const {}, + groups: groups ?? const {}, + groupProperties: groupProperties ?? const {}, + disableGeoip: disableGeoip, + ); + return result?.variant ?? result?.enabled ?? false; } Future resetAdapterState() async { - _flushTimer?.cancel(); - _flushTimer = null; - _activeFlush = null; - _autoFlushPaused = false; - _apiKey = null; - _host = null; - _nextDistinctId = null; - _nextTimestamp = null; - lastCapturedUuid = null; + unawaited(_plugin?.close()); + _plugin = null; + _client = null; + await _proxy?.close(); + _proxy = null; + _initialized = false; state = _AdapterState(); } - - String _uuidV4() { - final bytes = List.generate(16, (_) => _random.nextInt(256)); - bytes[6] = (bytes[6] & 0x0f) | 0x40; - bytes[8] = (bytes[8] & 0x3f) | 0x80; - String hex(int byte) => byte.toRadixString(16).padLeft(2, '0'); - final value = bytes.map(hex).join(); - return '${value.substring(0, 8)}-' - '${value.substring(8, 12)}-' - '${value.substring(12, 16)}-' - '${value.substring(16, 20)}-' - '${value.substring(20)}'; - } } class _AdapterState { - int pendingEvents = 0; int totalEventsCaptured = 0; int totalEventsSent = 0; int totalRetries = 0; String? lastError; - final queue = >[]; final requestsMade = <_RequestRecord>[]; + final logLines = []; - Map toJson() => { + Map toJson({required int pendingEvents}) => { 'pending_events': pendingEvents, 'total_events_captured': totalEventsCaptured, 'total_events_sent': totalEventsSent, @@ -683,16 +710,10 @@ class _AdapterState { 'last_error': lastError, 'requests_made': requestsMade.map((request) => request.toJson()).toList(), + 'log_lines': logLines, }; } -class _PostResult { - const _PostResult(this.statusCode, {this.retryAfterMs}); - - final int statusCode; - final int? retryAfterMs; -} - class _RequestRecord { _RequestRecord({ required this.timestampMs, @@ -756,6 +777,21 @@ Map>? _readNestedObjectMap(Object? value) { ); } +/// [properties] with a `$test_padding` string, starting with [marker], that +/// makes them exactly [bytes] long as compact UTF-8 JSON. Payloads that big +/// can't pass through the harness's request to the adapter. +Map _padProperties( + Map properties, + int bytes, + String? marker, +) { + final prefix = marker ?? ''; + final padded = {...properties, r'$test_padding': prefix}; + final missing = bytes - utf8.encode(jsonEncode(padded)).length; + padded[r'$test_padding'] = prefix + 'x' * max(0, missing); + return padded; +} + int? _readInt(Object? value) { if (value is int) { return value; diff --git a/sdk_compliance_adapter/test/feature_flag_has_experiment_test.dart b/sdk_compliance_adapter/test/feature_flag_has_experiment_test.dart index 0b20bbba..1163f25d 100644 --- a/sdk_compliance_adapter/test/feature_flag_has_experiment_test.dart +++ b/sdk_compliance_adapter/test/feature_flag_has_experiment_test.dart @@ -157,7 +157,7 @@ Future> _postJson( } /// Serves `/flags/?v=2` with [flagsResponse] and records events posted to -/// `/batch`. +/// the capture v1 endpoint. class _MockPostHogServer { _MockPostHogServer._(this._server, this._flagsResponse); @@ -190,7 +190,8 @@ class _MockPostHogServer { continue; } - if (request.method == 'POST' && request.uri.path == '/batch') { + if (request.method == 'POST' && + request.uri.path == '/i/v1/analytics/events') { final decoded = jsonDecode(body) as Map; for (final event in decoded['batch'] as List) { batchedEvents.add(Map.from(event as Map)); diff --git a/sdk_compliance_adapter/test/flags_retry_test.dart b/sdk_compliance_adapter/test/flags_retry_test.dart index 5edec0d4..9ed2a3e1 100644 --- a/sdk_compliance_adapter/test/flags_retry_test.dart +++ b/sdk_compliance_adapter/test/flags_retry_test.dart @@ -36,24 +36,12 @@ void main() { expect(response['success'], isTrue); expect(response['value'], 'retry-success'); expect(flagsServer.flagsRequestCount, 2); - - final state = await _getJson('$adapterBase/state'); - expect(state['total_retries'], 1); }, ); } - for (final (status, retries) in [ - (400, 1), - (401, 1), - (408, 1), - (429, 1), - (500, 1), - (503, 1), - (502, 0), - (504, 0), - ]) { - test('does not retry HTTP $status with max_retries=$retries', () async { + for (final status in [400, 401, 408, 429, 500, 503]) { + test('does not retry HTTP $status', () async { final flagsServer = await _FlagsServer.start([status, HttpStatus.ok]); addTearDown(flagsServer.close); final adapter = ComplianceAdapter(); @@ -63,24 +51,18 @@ void main() { await _postJson('$base/init', { 'api_key': 'test-api-key', 'host': flagsServer.url, - 'max_retries': retries, 'flush_interval_ms': 60000, }); - await expectLater( - _postJson('$base/get_feature_flag', { - 'key': 'retry-flag', - 'distinct_id': 'test-user', - }), - throwsA(isA())); + final response = await _postJson('$base/get_feature_flag', { + 'key': 'retry-flag', + 'distinct_id': 'test-user', + }); + expect(response['value'], isFalse); expect(flagsServer.flagsRequestCount, 1); - final state = await _getJson('$base/state'); - expect(state['total_retries'], 0); - expect( - state['last_error'], 'Feature flag request failed with HTTP $status'); }); } - test('propagates error after /flags retries are exhausted', () async { + test('answers false after the /flags retry fails too', () async { final flagsServer = await _FlagsServer.start([ HttpStatus.badGateway, HttpStatus.badGateway, @@ -95,29 +77,16 @@ void main() { await _postJson('$adapterBase/init', { 'api_key': 'test-api-key', 'host': flagsServer.url, - 'max_retries': 1, 'flush_interval_ms': 60000, }); - await expectLater( - _postJson('$adapterBase/get_feature_flag', { - 'key': 'retry-flag', - 'distinct_id': 'test-user', - }), - throwsA( - isA().having( - (error) => error.message, - 'message', - contains('HTTP 500'), - ), - ), - ); + final response = await _postJson('$adapterBase/get_feature_flag', { + 'key': 'retry-flag', + 'distinct_id': 'test-user', + }); + expect(response['value'], isFalse); expect(flagsServer.flagsRequestCount, 2); - - final state = await _getJson('$adapterBase/state'); - expect(state['total_retries'], 1); - expect(state['last_error'], 'Feature flag request failed with HTTP 502'); }); } @@ -141,21 +110,6 @@ Future> _postJson( } } -Future> _getJson(String url) async { - final client = HttpClient(); - try { - final request = await client.getUrl(Uri.parse(url)); - final response = await request.close(); - final body = await utf8.decoder.bind(response).join(); - if (response.statusCode < 200 || response.statusCode >= 300) { - throw HttpException('HTTP ${response.statusCode}: $body'); - } - return Map.from(jsonDecode(body) as Map); - } finally { - client.close(force: true); - } -} - class _FlagsServer { _FlagsServer._(this._server, this._statuses); diff --git a/sdk_compliance_adapter/test/minimal_flag_called_events_test.dart b/sdk_compliance_adapter/test/minimal_flag_called_events_test.dart index b7f425ae..8a7c9f08 100644 --- a/sdk_compliance_adapter/test/minimal_flag_called_events_test.dart +++ b/sdk_compliance_adapter/test/minimal_flag_called_events_test.dart @@ -30,17 +30,11 @@ void main() { expect( properties.keys, unorderedEquals([ - 'distinct_id', - 'token', - r'$lib', - r'$lib_version', r'$feature_flag', r'$feature_flag_response', r'$feature_flag_has_experiment', ]), ); - expect(properties['distinct_id'], 'test-user'); - expect(properties['token'], 'test-api-key'); expect(properties[r'$feature_flag'], 'plain-flag'); expect(properties[r'$feature_flag_response'], isTrue); expect(properties[r'$feature_flag_has_experiment'], isFalse); @@ -148,12 +142,77 @@ void main() { final gated = await harness.captureFeatureFlagCalled('plain-flag'); expect(gated, isNot(contains(r'$feature/plain-flag'))); - mockServer.flagsResponse = Map.of(mockServer.flagsResponse) - ..remove('minimalFlagCalledEvents'); + // A new value, as the SDK reports each value of a flag only once. + mockServer.flagsResponse = { + 'flags': { + 'plain-flag': { + 'key': 'plain-flag', + 'enabled': true, + 'variant': 'test', + 'metadata': {'has_experiment': false}, + }, + }, + 'featureFlags': {'plain-flag': 'test'}, + }; final ungated = await harness.captureFeatureFlagCalled('plain-flag'); expect(ungated, contains(r'$feature/plain-flag')); }); + + group('switching users', () { + late _MockPostHogServer mockServer; + late _AdapterHarness harness; + + setUp(() async { + mockServer = await _MockPostHogServer.start({ + 'featureFlags': {'plain-flag': true}, + }); + harness = await _AdapterHarness.start(mockServer); + }); + + tearDown(() async { + await harness.close(); + await mockServer.close(); + }); + + test('reports the flag call of each user', () async { + await harness.captureFeatureFlagCalled('plain-flag'); + await harness.captureFeatureFlagCalled('plain-flag', + distinctId: 'next-user'); + + expect(mockServer.batchedEvents.last['distinct_id'], 'next-user'); + }); + + test('does not serve the flags of the previous user', () async { + await harness.captureFeatureFlagCalled('plain-flag'); + mockServer.flagsStatus = HttpStatus.badRequest; + + final response = await harness.evaluate('plain-flag', 'next-user'); + + expect(response['value'], isFalse); + }); + + test('requests flags only for the requested users', () async { + await harness.evaluate('plain-flag', 'test-user'); + await harness.evaluate('plain-flag', 'next-user'); + + expect(mockServer.flagsDistinctIds, ['test-user', 'next-user']); + }); + }); + + test('counts each captured flag call once', () async { + final mockServer = await _MockPostHogServer.start({ + 'featureFlags': {'plain-flag': true}, + }); + addTearDown(mockServer.close); + final harness = await _AdapterHarness.start(mockServer); + addTearDown(harness.close); + + await harness.captureFeatureFlagCalled('plain-flag'); + + final state = await harness.state(); + expect(state['total_events_captured'], 1); + }); } /// Runs a [ComplianceAdapter] against a [_MockPostHogServer]. @@ -178,14 +237,32 @@ class _AdapterHarness { Future close() => _adapter.close(); + Future> evaluate(String key, String distinctId) => + _postJson('$_baseUrl/get_feature_flag', { + 'key': key, + 'distinct_id': distinctId, + }); + + Future> state() async { + final client = HttpClient(); + try { + final request = await client.getUrl(Uri.parse('$_baseUrl/state')); + final response = await request.close(); + final body = await utf8.decoder.bind(response).join(); + return Map.from(jsonDecode(body) as Map); + } finally { + client.close(force: true); + } + } + /// Evaluates [key], flushes, and returns the properties of the /// `$feature_flag_called` event it produced. - Future> captureFeatureFlagCalled(String key) async { + Future> captureFeatureFlagCalled( + String key, { + String distinctId = 'test-user', + }) async { final alreadyBatched = _mockServer.batchedEvents.length; - final response = await _postJson('$_baseUrl/get_feature_flag', { - 'key': key, - 'distinct_id': 'test-user', - }); + final response = await evaluate(key, distinctId); expect(response['success'], isTrue); await _postJson('$_baseUrl/flush', {}); @@ -218,13 +295,15 @@ Future> _postJson( } /// Serves `/flags/?v=2` with a swappable [flagsResponse] and records events -/// posted to `/batch`. +/// posted to the capture v1 endpoint. class _MockPostHogServer { _MockPostHogServer._(this._server, this.flagsResponse); final HttpServer _server; Map flagsResponse; + int flagsStatus = HttpStatus.ok; final List> batchedEvents = []; + final List flagsDistinctIds = []; String get url => 'http://127.0.0.1:${_server.port}'; @@ -245,13 +324,17 @@ class _MockPostHogServer { if (request.method == 'POST' && request.uri.path == '/flags/' && request.uri.queryParameters['v'] == '2') { + flagsDistinctIds + .add((jsonDecode(body) as Map)['distinct_id'] as String); + request.response.statusCode = flagsStatus; request.response.headers.contentType = ContentType.json; request.response.write(jsonEncode(flagsResponse)); await request.response.close(); continue; } - if (request.method == 'POST' && request.uri.path == '/batch') { + if (request.method == 'POST' && + request.uri.path == '/i/v1/analytics/events') { final decoded = jsonDecode(body) as Map; for (final event in decoded['batch'] as List) { batchedEvents.add(Map.from(event as Map)); diff --git a/sdk_compliance_adapter/test/recording_proxy_test.dart b/sdk_compliance_adapter/test/recording_proxy_test.dart new file mode 100644 index 00000000..d53c4b1e --- /dev/null +++ b/sdk_compliance_adapter/test/recording_proxy_test.dart @@ -0,0 +1,196 @@ +import 'dart:async'; +import 'dart:convert'; +import 'dart:io'; + +import 'package:flutter_test/flutter_test.dart'; +import 'package:posthog_flutter_sdk_compliance_adapter/adapter_server.dart'; + +void main() { + test('pending events leave with a batch the SDK gives up on', () async { + final harness = await _Harness.start((request, _, __) async { + request.response.statusCode = HttpStatus.badRequest; + await request.response.close(); + }); + addTearDown(harness.close); + + await harness.captureAndFlush(); + + final state = await harness.state(); + expect(state['pending_events'], 0); + expect(state['total_events_sent'], 0); + }); + + test('a 303 reaches the SDK instead of being followed', () async { + final harness = await _Harness.start((request, origin, _) async { + request.response + ..statusCode = HttpStatus.seeOther + ..headers.set(HttpHeaders.locationHeader, '$origin/elsewhere'); + await request.response.close(); + }); + addTearDown(harness.close); + + await harness.captureAndFlush(); + + expect(harness.paths, ['/i/v1/analytics/events']); + expect((await harness.state())['total_events_sent'], 0); + }); + + test('the SDK follows a same-origin redirect through the proxy', () async { + final harness = await _Harness.start((request, origin, body) async { + if (request.uri.path == '/moved') { + final batch = (jsonDecode(body) as Map)['batch'] as List; + request.response.write( + jsonEncode({ + 'results': { + for (final event in batch) + (event as Map)['uuid']: {'result': 'ok'}, + }, + }), + ); + } else { + request.response + ..statusCode = HttpStatus.temporaryRedirect + ..headers.set(HttpHeaders.locationHeader, '$origin/moved'); + } + await request.response.close(); + }); + addTearDown(harness.close); + + await harness.captureAndFlush(); + + expect(harness.paths, ['/i/v1/analytics/events', '/moved']); + expect((await harness.state())['total_events_sent'], 1); + }); + + for (final location in ['ftp://example.com/path', 'http:/path']) { + test('a 307 to $location reaches the SDK as a terminal redirect', () async { + final harness = await _Harness.start((request, _, __) async { + request.response + ..statusCode = HttpStatus.temporaryRedirect + ..headers.set(HttpHeaders.locationHeader, location); + await request.response.close(); + }); + addTearDown(harness.close); + + await harness.captureAndFlush(); + + final state = await harness.state(); + expect(harness.paths, ['/i/v1/analytics/events']); + expect(state['total_events_sent'], 0); + expect(state['pending_events'], 0); + }); + } + + test('a 2xx whose body breaks off is dropped without a retry', () async { + final harness = await _Harness.start((request, _, __) async { + final socket = await request.response.detachSocket(writeHeaders: false); + socket.write('HTTP/1.1 200 OK\r\nContent-Length: 100\r\n\r\n{'); + await socket.flush(); + socket.destroy(); + }); + addTearDown(harness.close); + + await harness.captureAndFlush(); + + final state = await harness.state(); + expect(harness.paths, hasLength(1)); + expect(state['total_events_sent'], 0); + expect(state['pending_events'], 0); + }); + + for (final (token, admitted) in [ + (' phx_test ', false), + (' \n\t ', false), + (' phc_test ', true), + ]) { + test('init admits the trimmed token ${jsonEncode(token)}: $admitted', + () async { + final harness = await _Harness.start( + (request, _, body) async { + final batch = (jsonDecode(body) as Map)['batch'] as List; + request.response.write(jsonEncode({ + 'results': { + for (final event in batch) + (event as Map)['uuid']: {'result': 'ok'}, + }, + })); + await request.response.close(); + }, + apiKey: token, + ); + addTearDown(harness.close); + + await harness.captureAndFlush(); + + expect(harness.paths, hasLength(admitted ? 1 : 0)); + expect((await harness.state())['total_events_sent'], admitted ? 1 : 0); + }); + } +} + +class _Harness { + _Harness._(this._ingestion, this._adapter, this._adapterPort, this._client); + + final HttpServer _ingestion; + final ComplianceAdapter _adapter; + final int _adapterPort; + final HttpClient _client; + final paths = []; + + static Future<_Harness> start( + Future Function(HttpRequest request, String origin, String body) + respond, { + String apiKey = 'phc_test', + }) async { + final ingestion = await HttpServer.bind(InternetAddress.loopbackIPv4, 0); + final adapter = ComplianceAdapter(); + final adapterServer = await adapter.start(port: 0); + final harness = + _Harness._(ingestion, adapter, adapterServer.port, HttpClient()); + final origin = 'http://127.0.0.1:${ingestion.port}'; + unawaited(() async { + await for (final request in ingestion) { + harness.paths.add(request.uri.path); + final body = await utf8.decoder.bind(request).join(); + await respond(request, origin, body); + } + }()); + await harness._post('/init', { + 'api_key': apiKey, + 'host': origin, + 'flush_at': 100, + 'flush_interval_ms': 60000, + }); + return harness; + } + + Future captureAndFlush() async { + await _post('/capture', {'distinct_id': 'user-1', 'event': 'evt'}); + await _post('/flush', {}); + } + + Future> state() async { + final request = await _client.get('127.0.0.1', _adapterPort, '/state'); + return _decode(await request.close()); + } + + Future> _post( + String path, + Map body, + ) async { + final request = await _client.post('127.0.0.1', _adapterPort, path); + request.headers.contentType = ContentType.json; + request.write(jsonEncode(body)); + return _decode(await request.close()); + } + + Future> _decode(HttpClientResponse response) async => + jsonDecode(await response.transform(utf8.decoder).join()) + as Map; + + Future close() async { + await _adapter.close(); + _client.close(force: true); + await _ingestion.close(force: true); + } +} From 0d9204ffa231d007903acdc866ec1e515771b88a Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Tue, 3 Nov 2026 18:35:00 -0500 Subject: [PATCH 23/28] feat!: run beforeSend on the native-built event on iOS, macOS and Android (#682) * feat!: run beforeSend on the native-built event on iOS, macOS and Android Dart beforeSend callbacks now get the event the native SDK built, with its system and registered properties, uuid, distinct id and timestamp, and the native SDK sends what they return without adding properties. Without callbacks, events still take one native call. Also adds PosthogFlutterPlugin.addBeforeSend in Swift and Kotlin for events the native SDK captures itself. * fix: import only the PostHogInternal SPI from posthog-ios * fix: drop built events whose beforeSend callbacks never finish * fix: clear pending built events on setup and close * fix: keep primitive arrays when sending built events over the channel * feat(desktop): give beforeSend the full event and add nothing after it - On Windows and Linux, `PostHogEvent` now carries the event's uuid, distinct ID and timestamp, as on iOS, macOS and Android. A callback can change the distinct ID (a blank one keeps the current) and the timestamp; the event keeps its uuid. - `$exception_steps` are attached as the event is built, before the callbacks, as posthog-ios and posthog-android do, so a callback sees and can remove them. Steps recorded while a callback runs, or an event renamed to `$exception`, no longer get them. - The prepared core event carries its uuid and distinct ID, which the queue keeps. Co-Authored-By: Claude Opus 5.5 * style: merge the repeated guards in buildEvent for swiftformat 0.64 Co-Authored-By: Claude Opus 5.5 * fix(desktop): keep another distinct id's person properties out of the current user's flag cache When a beforeSend callback sends the event for another distinct id, its $set and $set_once no longer update the current user's flag person properties or person-properties hash. Co-Authored-By: Claude Opus 5.5 * test: optOut, close and setup wait for an event being sent Native refuses sendBuiltEvent once one of them has reached it, so the event would be lost if they could run between buildEvent and sendBuiltEvent. Co-Authored-By: Claude Opus 5.5 * fix(beforeSend): run the callbacks set when the event was captured setup() replaces the callbacks synchronously, so an event still waiting on its native build ran the next setup's chain, or none, and skipped its filter. Co-Authored-By: Claude Opus 5.5 * fix(beforeSend): keep capture semantics for events named $screen With callbacks set, capture('$screen') reached the native builders' screen() path, which drops an event without a $screen_name and, on iOS, ignores person properties. Build it under another name and restore the name in Dart. Co-Authored-By: Claude Opus 5.5 * fix(desktop): decide person processing before beforeSend Co-Authored-By: Claude Opus 5.5 * docs: fold #682 release notes into the 6.0 docs * fix(desktop): keep another distinct id's person properties from enabling person processing When a beforeSend callback sends an event with person properties for another distinct id, the current user's persisted person processing state stays off, so their later events keep process_person_profile: false. Co-Authored-By: Claude Opus 5.5 * fix(desktop): decide later events' person processing from what the app captured Matches iOS and Android. A callback that adds $set to an anonymous event no longer turns person processing on for later events, and one that strips $set no longer leaves it off after a person-processed event. Co-Authored-By: Claude Opus 5.5 * docs: say person processing is decided before beforeSend on native Co-Authored-By: Claude Opus 5.5 * fix: give beforeSend callbacks typed nested values on iOS, macOS and Android Nested values from the method channel are untyped, so a callback casting $exception_list to List> threw and the event was dropped. Co-Authored-By: Claude Opus 5.5 * fix(darwin): expire built events on a monotonic clock A wall clock jump during a beforeSend callback could evict and lose the event. Android already uses a monotonic clock. Co-Authored-By: Claude Opus 5.5 * docs: say what the one-minute built-event expiry covers now that callbacks are sync Co-Authored-By: Claude Opus 5.5 * fix: keep events and user properties through beforeSend (#698) * feat!: make beforeSend callbacks synchronous Event and log beforeSend callbacks no longer return FutureOr, matching the native SDKs and the before-send-hook spec. The event is handed to the SDK in the same call, so calls made right after an un-awaited capture can no longer reach the SDK first, on every platform including Windows and Linux. Co-Authored-By: Claude Opus 5.5 * fix: keep the call queue on iOS, macOS and Android With #682 and beforeSend set, an event takes two native calls. Without the queue, an optOut(), close() or setup() made right after capture() reaches native between them and the event is lost. Co-Authored-By: Claude Opus 5.5 * test(android): restore the screenshot scale expectation lost in the main merge * fix(web): hand feature events to posthog-js before yielding Without CallOrder the await on the flag lookup let a reset() made right after an un-awaited captureFeatureView or captureFeatureInteraction overtake it, so the event went out as the new anonymous user with the previous user's flag. Co-Authored-By: Claude Opus 5.5 * docs: fold #686 release notes into the 6.0 docs * fix: run a renaming beforeSend once and keep its user properties A hook that renamed a screen or exception ran again through capture() and lost its userProperties on web, iOS, Android and macOS. Also covers calls made from inside a hook and bursts of events, and documents that a hook blocks the UI. Co-Authored-By: Claude Opus 5.5 * fix: keep events when beforeSend resets on desktop or sets user properties on web On Windows and Linux, a callback calling reset() or identify() dropped the event. It now goes out as the user it was prepared for, as on iOS, Android and macOS. On web, userProperties set on a screen or exception that kept its name were lost. Co-Authored-By: Claude Opus 5.5 * fix(web): keep an event on its user when beforeSend changes the user posthog-js builds the event after the callbacks, so one calling reset() or identify() moved the event to the new user. It now stays on the earlier user, as on the other platforms. Co-Authored-By: Claude Opus 5.5 * fix(desktop): keep the prepared user's person and session state when beforeSend changes the user A hook calling reset() or identify() left the event on its original user, but person processing was recomputed from the replacement's state, and a $screen hook calling reset() put the old screen in the new session. Co-Authored-By: Claude Opus 5.5 * fix(web): don't restore the distinct id across a beforeSend consent change Under cookieless_mode on_reject, restoring the id reattached the opted-out user to a cookieless event, or sent the shared cookieless id after opting in. Co-Authored-By: Claude Opus 5.5 * fix(web): drop user properties when beforeSend resets the user posthog-js stores an event's $set as the current user's person properties for flags, so after a reset() in the callback they reached the next user. identify() of an anonymous user links the two, so they stay. Co-Authored-By: Claude Opus 5.5 * docs: note what a web beforeSend calling reset() keeps Co-Authored-By: Claude Opus 5.5 * fix: add exception steps before beforeSend on Windows and Linux beforeSend can now read, change or remove $exception_steps, as on iOS and Android. Claude-Session: https://claude.ai/code/session_019xLynws83apuXa9LfRy9Aq --------- Co-authored-by: Claude Opus 5.5 * fix(compliance): pass uuid and prepared-event identity through the adapter The adapter's captureStateless/captureAiStateless overrides now forward the uuid parameter, and its prepareEvent override copies uuid, distinctId and requestsPersonProcessing, so it compiles against #690's base. Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --- .changeset/v6-major-release.md | 10 +- api/posthog_flutter.api.json | 60 +++ posthog_flutter/MIGRATION.md | 13 +- .../posthog/flutter/PosthogFlutterPlugin.kt | 163 ++++++ .../flutter/PosthogFlutterPluginTest.kt | 33 ++ .../PosthogFlutterPlugin.swift | 140 ++++- posthog_flutter/lib/posthog_flutter_web.dart | 88 ++- .../lib/src/core/posthog_core.dart | 83 ++- .../lib/src/core/posthog_core_stateless.dart | 20 +- posthog_flutter/lib/src/posthog_config.dart | 34 +- posthog_flutter/lib/src/posthog_event.dart | 55 +- .../lib/src/posthog_flutter_desktop.dart | 135 ++--- .../lib/src/posthog_flutter_io.dart | 426 +++++++++------ .../lib/src/posthog_flutter_web_handler.dart | 45 +- posthog_flutter/lib/src/utils/call_order.dart | 7 +- .../test/event_shape_snapshot_test.dart | 36 +- .../test/posthog_flutter_desktop_test.dart | 369 ++++++++++++- .../test/posthog_flutter_io_test.dart | 505 ++++++++++++++++-- posthog_flutter/test/posthog_logs_test.dart | 33 ++ .../test/snapshots/event_channel_shapes.json | 67 ++- .../special_event_channel_shapes.json | 117 +++- .../test/web_before_send_test.dart | 323 +++++++++++ .../lib/adapter_server.dart | 13 +- 23 files changed, 2378 insertions(+), 397 deletions(-) diff --git a/.changeset/v6-major-release.md b/.changeset/v6-major-release.md index 56a21d4d..62ea30bf 100644 --- a/.changeset/v6-major-release.md +++ b/.changeset/v6-major-release.md @@ -13,7 +13,10 @@ - **Breaking:** remove the `PostHogSessionReplayConfig.debouncerDelay` setter — use `throttleDelay` - **Breaking:** remove `PostHogDataMode.cellular` — use `PostHogDataMode.any` - **Breaking:** make `beforeSend` and `logsConfig.beforeSend` callbacks synchronous — load what they need ahead of time instead of using `await` -- Keep a `reset()`, `identify()` or `optOut()` made right after an un-awaited `capture()`, `screen()` or `captureException()` from applying to that event first, and stop dropping that event on Windows and Linux +- Keep a `reset()`, `identify()` or `optOut()` made right after an un-awaited `capture()`, `screen()`, `captureException()`, `captureFeatureView()` or `captureFeatureInteraction()` from applying to that event first, and stop dropping that event on Windows and Linux +- Run a `beforeSend` callback that renames a screen or exception event once, and keep its `userProperties` +- Keep `userProperties` and `userPropertiesSetOnce` that a `beforeSend` callback sets on a screen or exception event on web +- Send an event as its original user when a `beforeSend` callback calls `reset()` or `identify()` on Windows and Linux, instead of dropping it, and on web, instead of sending it as the new user - **Breaking:** remove `toMap()` from the config classes and `PostHogFeatureFlagResult.fromMap()` from the public API - **Breaking:** rename `enable()` and `disable()` to `optIn()` and `optOut()` on `PosthogFlutterPlatformInterface`, `PosthogFlutterIO` and `PosthogFlutterWeb` - **Breaking:** adopt `posthog-ios` 4.x, which requires Xcode 26 @@ -30,6 +33,8 @@ - **Breaking:** apply SDK properties, then registered properties, then event properties on Windows and Linux, so your value wins for that event, and run `beforeSend` after that merge - **Breaking:** always set `$lib` and `$lib_version` from the `PostHog-Sdk-Info` header on Windows and Linux, ignoring changes made in `beforeSend` - **Breaking:** send person processing as the `process_person_profile: false` option on Windows and Linux, only while it's off, instead of a `$process_person_profile` property on every event +- **Breaking:** pass `beforeSend` callbacks the event the native SDK built on iOS, macOS and Android, with its system and registered properties, and make their changes final +- **Breaking:** decide person processing before `beforeSend` runs on iOS, macOS, Android, Windows and Linux — a callback that removes `$set` no longer prevents a person profile, and a callback that adds `$set` to an anonymous event must also set the `process_person_profile: true` option - Add an `options` parameter to `capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group` and `captureException`, and `PostHogEvent.options` for `beforeSend` callbacks - Add `captureAi` for AI observability events, a no-op that returns `null` on web - Add `Posthog().onFeatureFlags()` to get notified after every feature flags load, returning a `PostHogFeatureFlagsSubscription` you can `unsubscribe()` @@ -44,5 +49,8 @@ - Run queued event encoding, file work and request compression on a background isolate on Windows and Linux so they no longer drop frames - Limit AI events waiting to be written on Windows and Linux to about 50 MiB in memory, dropping the oldest first and completing `captureAi` with `null` for them - Take an event's timestamp before the `beforeSend` callbacks run on Windows and Linux +- Add `PostHogEvent.uuid`, `distinctId` and `timestamp`, set on every platform except web — a callback can change the distinct ID and timestamp, and the event keeps its uuid +- Attach `$exception_steps` before `beforeSend` runs on Windows and Linux so callbacks can read or remove them — steps recorded while a callback runs, or an event a callback renames to `$exception`, no longer get them +- Add `PosthogFlutterPlugin.addBeforeSend` in Swift and Kotlin to filter or edit events the native SDK captures itself, such as crashes, app lifecycle and `$feature_flag_called` events - Declare Android `minSdkVersion` 23 to match `posthog-android` - Add a `defaultValue` option to `isFeatureEnabled()`, returned when the flag has no value diff --git a/api/posthog_flutter.api.json b/api/posthog_flutter.api.json index 8eee77bc..89dc0b0d 100644 --- a/api/posthog_flutter.api.json +++ b/api/posthog_flutter.api.json @@ -5671,6 +5671,33 @@ "name": "options", "relativePath": "lib/src/posthog_event.dart", "typeName": "Map?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "uuid", + "relativePath": "lib/src/posthog_event.dart", + "typeName": "String?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "distinctId", + "relativePath": "lib/src/posthog_event.dart", + "typeName": "String?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "timestamp", + "relativePath": "lib/src/posthog_event.dart", + "typeName": "DateTime?" } ], "relativePath": "lib/src/posthog_event.dart", @@ -5734,6 +5761,39 @@ "name": "options", "relativePath": "lib/src/posthog_event.dart", "typeName": "Map?" + }, + { + "entryPoints": [], + "isDeprecated": false, + "isExperimental": false, + "isReadable": true, + "isStatic": false, + "isWriteable": false, + "name": "uuid", + "relativePath": "lib/src/posthog_event.dart", + "typeName": "String?" + }, + { + "entryPoints": [], + "isDeprecated": false, + "isExperimental": false, + "isReadable": true, + "isStatic": false, + "isWriteable": true, + "name": "distinctId", + "relativePath": "lib/src/posthog_event.dart", + "typeName": "String?" + }, + { + "entryPoints": [], + "isDeprecated": false, + "isExperimental": false, + "isReadable": true, + "isStatic": false, + "isWriteable": true, + "name": "timestamp", + "relativePath": "lib/src/posthog_event.dart", + "typeName": "DateTime?" } ], "isDeprecated": false, diff --git a/posthog_flutter/MIGRATION.md b/posthog_flutter/MIGRATION.md index fc39ac48..7e40a1ba 100644 --- a/posthog_flutter/MIGRATION.md +++ b/posthog_flutter/MIGRATION.md @@ -177,7 +177,7 @@ They serialized the internal platform-channel format and have no replacement. `t ### `beforeSend` callbacks are synchronous -`BeforeSendCallback` is now `PostHogEvent? Function(PostHogEvent)`, and `BeforeSendLogCallback` is `PostHogLogRecord? Function(PostHogLogRecord)`. An `async` callback is a compile error. Load what it needs ahead of time and read it synchronously. +`BeforeSendCallback` is now `PostHogEvent? Function(PostHogEvent)`, and `BeforeSendLogCallback` is `PostHogLogRecord? Function(PostHogLogRecord)`. An `async` callback, or one declared to return `FutureOr`, is a compile error. Load what it needs ahead of time and read it synchronously. ```dart // Before @@ -258,6 +258,16 @@ On iOS, macOS and Android, a malformed, empty or whitespace-only payload from `g On iOS and macOS, string values in `PostHogBootstrapConfig.featureFlagPayloads`, such as `"123"`, stay strings instead of being decoded to numbers or booleans. +### `beforeSend` on iOS, macOS and Android + +**This is a silent change.** Callbacks now get the event the native SDK built, including its system properties, such as `$device_type` and `$session_id`, and registered properties. Their changes are final. In 5.x they saw only the properties you passed, so a callback that loops over or strips every property now also touches the SDK's. `PostHogEvent` also has `uuid`, `distinctId` and `timestamp`, set on every platform except web. + +**Person processing is decided before the callbacks run.** In 5.x, a callback that removed `$set` prevented a person profile. Now the event is still person-processed, and so are later events. Return `null` to drop an event that must not create a profile. A callback that adds `$set` to an anonymous event must also set the `process_person_profile: true` option. + +Nested maps are `Map`, and a non-empty list of maps is `List>`. Any other list is `List`, even a `List` you passed to `capture`, so cast its items instead of the list. + +Events the native SDK captures itself don't go through Dart callbacks. Use `PosthogFlutterPlugin.addBeforeSend` in Swift or Kotlin for those. + ### Lifecycle events on iOS and macOS `Application Installed`, `Application Updated` and `Application Opened` no longer include `version` and `build`. Update insights, cohorts and filters that use them to `$app_version` and `$app_build`. Android still sends them. @@ -274,6 +284,7 @@ A personal API key (`phx_...`) in `projectToken` now skips `setup()` with one lo - **Property order:** an event's properties are the SDK's, then registered properties, then the event's own, so your value now wins for that event. `beforeSend` runs after that merge, except that `$lib` and `$lib_version` always come from the `PostHog-Sdk-Info` header. - **Person processing:** it's sent as the `process_person_profile: false` option only while it's off, instead of a `$process_person_profile` property on every event. +- **`beforeSend` and person processing:** person processing is decided before the callbacks run. A callback that adds `$set` to an anonymous event must also set the `process_person_profile: true` option. - **Redirects:** only same-origin 307 and 308 redirects are followed. Any other redirect drops the batch. - **Retries:** a failed batch waits 1 second, doubling up to 30 seconds with ±25% jitter, instead of retrying within the same flush. `Retry-After` is a floor under that wait, capped at 30 seconds. - **Writes to disk:** an event is no longer on disk when `capture`, `screen`, `captureException`, `captureFeatureView`, `captureFeatureInteraction`, `identify`, `alias`, `group` or `setPersonProperties` returns, only when the returned future completes. One you didn't await can be lost if the app crashes or calls `exit()` right after. Await the call, or `Posthog().close()`, before `exit()`. Only `close()` also covers events the SDK captures itself, such as `$feature_flag_called`. An `identify` not awaited before `exit()` can lose its `$identify` event for good, because the new ID is already saved. `close()` can now take up to 4 seconds, and a later `setup()` waits for the queue's file work. diff --git a/posthog_flutter/android/src/main/kotlin/com/posthog/flutter/PosthogFlutterPlugin.kt b/posthog_flutter/android/src/main/kotlin/com/posthog/flutter/PosthogFlutterPlugin.kt index 4b16c282..ad8cdf26 100644 --- a/posthog_flutter/android/src/main/kotlin/com/posthog/flutter/PosthogFlutterPlugin.kt +++ b/posthog_flutter/android/src/main/kotlin/com/posthog/flutter/PosthogFlutterPlugin.kt @@ -14,6 +14,7 @@ import android.os.Build import android.os.Bundle import android.os.Handler import android.os.Looper +import android.os.SystemClock import android.util.Log import android.view.PixelCopy import android.view.SurfaceView @@ -28,6 +29,7 @@ import com.posthog.PostHogBeforeSend import com.posthog.PostHogBootstrapConfig import com.posthog.PostHogCompression import com.posthog.PostHogConfig +import com.posthog.PostHogEvent import com.posthog.PostHogFeatureFlagsLoaded import com.posthog.PostHogFeatureFlagsSubscription import com.posthog.android.PostHogAndroid @@ -63,6 +65,8 @@ private const val END_DEBOUNCE_TICKS = 1 private const val BRIDGE_FAILURE_STRIKE_LIMIT = 3 +private const val BUILT_EVENT_TIMEOUT_MS = 60_000L + /** PosthogFlutterPlugin */ class PosthogFlutterPlugin : FlutterPlugin, @@ -81,6 +85,14 @@ class PosthogFlutterPlugin : private var postHogConfig: PostHogAndroidConfig? = null + // Events built for the Dart beforeSend callbacks, keyed by uuid, until Dart + // sends or drops them. Main-thread confined, like the channel callbacks. + // An event whose callbacks haven't finished after BUILT_EVENT_TIMEOUT_MS is + // dropped on the next build, so a callback that never completes can't keep + // it in memory. + // setup and close clear it, so a build can't be sent through a reconfigured SDK. + private val builtEvents = mutableMapOf>() + // Test seam: captures the built config even if setup() throws (mock Context in // unit tests). postHogConfig is only published on success, so production readers // never see an uninstalled config. @@ -283,6 +295,18 @@ class PosthogFlutterPlugin : screen(call, result) } + "buildEvent" -> { + buildEvent(call, result) + } + + "sendBuiltEvent" -> { + sendBuiltEvent(call, result) + } + + "discardBuiltEvent" -> { + discardBuiltEvent(call, result) + } + "captureLog" -> { captureLog(call, result) } @@ -574,6 +598,7 @@ class PosthogFlutterPlugin : return } + builtEvents.clear() updateFlagsGeneration(call) setupPostHog(args) @@ -862,6 +887,7 @@ class PosthogFlutterPlugin : ) } } + nativeBeforeSendSnapshot().forEach { this.addBeforeSend(it) } } lastBuiltConfig = config @@ -1862,6 +1888,91 @@ class PosthogFlutterPlugin : } } + /** + * Builds the event a capture, screen or captureException call would send, for the + * Dart beforeSend callbacks, and returns it to Dart. Returns null when the SDK skips it. + */ + private fun buildEvent( + call: MethodCall, + result: Result, + ) { + try { + val timestampMs: Long? = call.argument("timestamp")?.toLong() + val built = + PostHog.buildEventForWrapper( + call.argument("eventName")!!, + properties = call.argument("properties"), + userProperties = call.argument("userProperties"), + userPropertiesSetOnce = call.argument("userPropertiesSetOnce"), + options = call.argument("options"), + ai = call.argument("ai") ?: false, + timestamp = timestampMs?.let { Date(it) }, + ) + val uuid = built?.uuid?.toString() + if (built == null || uuid == null) { + result.success(null) + return + } + val now = SystemClock.elapsedRealtime() + builtEvents.values.removeAll { (_, builtAt) -> now - builtAt >= BUILT_EVENT_TIMEOUT_MS } + builtEvents[uuid] = built to now + result.success( + mapOf( + "event" to built.event, + "uuid" to uuid, + "distinctId" to built.distinctId, + "timestamp" to built.timestamp.time, + "properties" to built.properties?.let(::toChannelValue), + "options" to built.options?.let(::toChannelValue), + ), + ) + } catch (e: Throwable) { + result.error("PosthogFlutterException", e.localizedMessage, null) + } + } + + /** + * Sends an event from [buildEvent] as the Dart beforeSend callbacks left it. + * Returns its uuid once queued, or null. + */ + private fun sendBuiltEvent( + call: MethodCall, + result: Result, + ) { + try { + val uuid: String = call.argument("uuid")!! + val built = builtEvents.remove(uuid)?.first + if (built == null) { + result.success(null) + return + } + val properties: Map? = call.argument("properties") + val options: Map? = call.argument("options") + val timestampMs: Long? = call.argument("timestamp")?.toLong() + val event = + built.copy( + event = call.argument("event")!!, + distinctId = call.argument("distinctId")?.takeIf { it.isNotBlank() } ?: built.distinctId, + properties = properties?.toMutableMap() ?: mutableMapOf(), + timestamp = timestampMs?.let { Date(it) } ?: built.timestamp, + options = options?.toMutableMap() ?: mutableMapOf(), + ) + val sent = PostHog.sendBuiltEventForWrapper(event, ai = call.argument("ai") ?: false) + result.success(sent?.toString()) + } catch (e: Throwable) { + result.error("PosthogFlutterException", e.localizedMessage, null) + } + } + + /** Drops an event from [buildEvent] that a Dart beforeSend callback dropped. */ + private fun discardBuiltEvent( + call: MethodCall, + result: Result, + ) { + call.argument("uuid")?.let { builtEvents.remove(it) } + result.success(null) + } + private fun captureLog( call: MethodCall, result: Result, @@ -2249,6 +2360,7 @@ class PosthogFlutterPlugin : private fun close(result: Result) { try { + builtEvents.clear() PostHog.close() result.success(null) } catch (e: Throwable) { @@ -2351,6 +2463,42 @@ class PosthogFlutterPlugin : } companion object { + private val nativeBeforeSend = mutableListOf() + + /** + * Adds a native `beforeSend` hook that runs on every event the PostHog Android + * SDK sends, including the ones Dart never sees. + * + * Dart `PostHogConfig.beforeSend` callbacks run only on events captured from + * Dart. Events the native SDK captures itself, such as crashes, app lifecycle + * events, `$feature_flag_called`, `$identify` and session replay, reach only + * native hooks. Hooks run in the order they're added, after the Dart callbacks. + * Return the event, changed or not, to send it, or `null` to drop it. No hooks + * are added by default. + * + * Add hooks before the SDK is set up: before `Posthog().setup()` runs in Dart, + * or in `Application.onCreate` when the SDK is set up from the manifest + * (`com.posthog.posthog.AUTO_INIT`). Hooks added later apply from the next setup. + * + * ```kotlin + * // MainApplication.onCreate + * PosthogFlutterPlugin.addBeforeSend { event -> + * if (event.event == "Application Backgrounded") null else event + * } + * ``` + */ + @JvmStatic + fun addBeforeSend(beforeSend: PostHogBeforeSend) { + synchronized(nativeBeforeSend) { nativeBeforeSend.add(beforeSend) } + } + + private fun nativeBeforeSendSnapshot(): List = synchronized(nativeBeforeSend) { nativeBeforeSend.toList() } + + @VisibleForTesting + internal fun resetNativeBeforeSendForTesting() { + synchronized(nativeBeforeSend) { nativeBeforeSend.clear() } + } + // Mint route for pushIdentityProvider, anchored to the engine whose setup() // installed the provider. A live owner is never displaced; provider-enabled // engines stay candidates so detach promotes the most recent survivor instead @@ -2394,6 +2542,21 @@ class PosthogFlutterPlugin : } } +/** + * Copies [value] into the types the Flutter channel codec can send. Values the + * codec can't send, such as a `Date` registered natively, are sent as strings. + */ +internal fun toChannelValue(value: Any?): Any? = + when (value) { + null, is String, is Boolean, is Int, is Long, is Double -> value + is ByteArray, is IntArray, is LongArray, is FloatArray, is DoubleArray -> value + is Number -> value.toDouble() + is Map<*, *> -> value.entries.associate { (k, v) -> k.toString() to toChannelValue(v) } + is Iterable<*> -> value.map(::toChannelValue) + is Array<*> -> value.map(::toChannelValue) + else -> value.toString() + } + @Suppress("UNCHECKED_CAST") internal fun bootstrapConfigFromMap(bootstrap: Map): PostHogBootstrapConfig = PostHogBootstrapConfig( diff --git a/posthog_flutter/android/src/test/kotlin/com/posthog/flutter/PosthogFlutterPluginTest.kt b/posthog_flutter/android/src/test/kotlin/com/posthog/flutter/PosthogFlutterPluginTest.kt index 2026e8cc..9734070a 100644 --- a/posthog_flutter/android/src/test/kotlin/com/posthog/flutter/PosthogFlutterPluginTest.kt +++ b/posthog_flutter/android/src/test/kotlin/com/posthog/flutter/PosthogFlutterPluginTest.kt @@ -7,6 +7,7 @@ import android.os.BadParcelableException import android.view.Window import android.view.WindowManager import com.google.firebase.FirebaseApp +import com.posthog.PostHogBeforeSend import com.posthog.PostHogCompression import com.posthog.PostHogConfig import com.posthog.PostHogEvent @@ -42,6 +43,7 @@ internal class PosthogFlutterPluginTest { @BeforeTest fun resetSharedRoute() { PosthogFlutterPlugin.resetPushIdentityRouteForTesting() + PosthogFlutterPlugin.resetNativeBeforeSendForTesting() } @Test @@ -292,6 +294,30 @@ internal class PosthogFlutterPluginTest { assertNull(propertiesOf("custom")?.get("\$flutter_version")) } + @Test + fun setup_addBeforeSend_runsAfterTheFlutterVersionHook() { + val seen = mutableListOf() + PosthogFlutterPlugin.addBeforeSend { event -> + seen.add(event.properties?.get("\$flutter_version")) + null + } + val plugin = PosthogFlutterPlugin() + attach(plugin, Mockito.mock(BinaryMessenger::class.java)) + plugin.onMethodCall( + MethodCall("setup", mapOf("projectToken" to "test-token", "flutterVersion" to "3.35.0")), + Mockito.mock(MethodChannel.Result::class.java), + ) + val beforeSend = assertNotNull(plugin.lastBuiltConfig).beforeSendList + + val result = + beforeSend.fold( + PostHogEvent("Application Installed", "id", properties = mutableMapOf()), + ) { event, hook -> event?.let { hook.run(it) } } + + assertNull(result) + assertEquals(listOf("3.35.0"), seen) + } + @Test fun setup_screenshotControls_preserveDefaults() { val plugin = PosthogFlutterPlugin() @@ -1038,4 +1064,11 @@ internal class PosthogFlutterPluginTest { .verify(backgroundMessenger, Mockito.never()) .send(Mockito.any(), Mockito.any(), Mockito.any()) } + + @Test + fun `toChannelValue keeps primitive arrays the codec can send`() { + val values = listOf(intArrayOf(1), longArrayOf(2L), floatArrayOf(3f), doubleArrayOf(4.0), byteArrayOf(5)) + + values.forEach { assertSame(it, toChannelValue(it)) } + } } diff --git a/posthog_flutter/darwin/posthog_flutter/Sources/posthog_flutter/PosthogFlutterPlugin.swift b/posthog_flutter/darwin/posthog_flutter/Sources/posthog_flutter/PosthogFlutterPlugin.swift index e65aa02d..8d55ae92 100644 --- a/posthog_flutter/darwin/posthog_flutter/Sources/posthog_flutter/PosthogFlutterPlugin.swift +++ b/posthog_flutter/darwin/posthog_flutter/Sources/posthog_flutter/PosthogFlutterPlugin.swift @@ -43,6 +43,18 @@ public class PosthogFlutterPlugin: NSObject, FlutterPlugin { private static var instance: PosthogFlutterPlugin? private var channel: FlutterMethodChannel? + + // Events built for the Dart beforeSend callbacks, keyed by uuid, until Dart + // sends or drops them. Main-thread confined, like the channel callbacks. + // An event whose callbacks haven't finished after builtEventTimeout is + // dropped on the next build, so a callback that never completes can't + // keep it in memory. + // setup and close clear it, so a build can't be sent through a reconfigured SDK. + private var builtEvents: [String: (event: PostHogEvent, builtAt: TimeInterval)] = [:] + private static let builtEventTimeout: TimeInterval = 60 + + private static let nativeBeforeSendLock = NSLock() + private static var nativeBeforeSend: [BeforeSendBlock] = [] private var featureFlagsSubscription: PostHogFeatureFlagsSubscription? // Dart's feature flags lifecycle, sent with setup, reset and close. Each @@ -74,6 +86,32 @@ public class PosthogFlutterPlugin: NSObject, FlutterPlugin { private static var pushChannelCandidates: [FlutterMethodChannel] = [] private static var pushChannel: FlutterMethodChannel? + /// Adds a native `beforeSend` block that runs on every event the PostHog iOS + /// or macOS SDK sends, including the ones Dart never sees. + /// + /// Dart `PostHogConfig.beforeSend` callbacks run only on events captured from + /// Dart. Events the native SDK captures itself, such as crashes, app + /// lifecycle events, `$feature_flag_called`, `$identify` and session replay, + /// reach only native blocks. Blocks run in the order they're added, after the + /// Dart callbacks. Return the event, changed or not, to send it, or `nil` to + /// drop it. No blocks are added by default. + /// + /// Add blocks before the SDK is set up: before `Posthog().setup()` runs in + /// Dart, or before the plugin registers when the SDK is set up from + /// `Info.plist`. Blocks added later apply from the next setup. + /// + /// ```swift + /// // AppDelegate.swift, before GeneratedPluginRegistrant.register(with: self) + /// PosthogFlutterPlugin.addBeforeSend { event in + /// event.event == "Application Backgrounded" ? nil : event + /// } + /// ``` + public static func addBeforeSend(_ block: @escaping BeforeSendBlock) { + nativeBeforeSendLock.lock() + defer { nativeBeforeSendLock.unlock() } + nativeBeforeSend.append(block) + } + public static func getInstance() -> PosthogFlutterPlugin? { instance } @@ -491,8 +529,11 @@ public class PosthogFlutterPlugin: NSObject, FlutterPlugin { } } - if let flutterVersionBeforeSend = flutterVersionBeforeSend(posthogConfig) { - config.setBeforeSend(flutterVersionBeforeSend) + nativeBeforeSendLock.lock() + let beforeSend = [flutterVersionBeforeSend(posthogConfig)].compactMap { $0 } + nativeBeforeSend + nativeBeforeSendLock.unlock() + if !beforeSend.isEmpty { + config.setBeforeSend(beforeSend) } // Update SDK name and version @@ -531,6 +572,12 @@ public class PosthogFlutterPlugin: NSObject, FlutterPlugin { captureAi(call, result: result) case "screen": screen(call, result: result) + case "buildEvent": + buildEvent(call, result: result) + case "sendBuiltEvent": + sendBuiltEvent(call, result: result) + case "discardBuiltEvent": + discardBuiltEvent(call, result: result) case "captureLog": captureLog(call, result: result) case "alias": @@ -1385,6 +1432,7 @@ extension PosthogFlutterPlugin { result: @escaping FlutterResult ) { if let args = call.arguments as? [String: Any] { + builtEvents.removeAll() PosthogFlutterPlugin.setupPostHog(args, anchor: self) result(nil) } else { @@ -1584,6 +1632,93 @@ extension PosthogFlutterPlugin { } } + /// Builds the event a capture, screen or captureException call would send, + /// for the Dart beforeSend callbacks, and returns it to Dart. Returns nil + /// when the SDK skips it. + private func buildEvent( + _ call: FlutterMethodCall, + result: @escaping FlutterResult + ) { + guard let args = call.arguments as? [String: Any], + let eventName = args["eventName"] as? String + else { + _badArgumentError(result) + return + } + let timestamp = (args["timestamp"] as? Int64).map { + Date(timeIntervalSince1970: TimeInterval($0) / 1000.0) + } + let built = PostHogSDK.shared.buildEventForWrapper( + event: eventName, + distinctId: nil, + properties: args["properties"] as? [String: Any], + userProperties: args["userProperties"] as? [String: Any], + userPropertiesSetOnce: args["userPropertiesSetOnce"] as? [String: Any], + groups: nil, + options: args["options"] as? [String: Any], + timestamp: timestamp, + ai: args["ai"] as? Bool ?? false + ) + guard let built else { + result(nil) + return + } + let uuid = built.uuid.uuidString.lowercased() + let now = ProcessInfo.processInfo.systemUptime + builtEvents = builtEvents.filter { now - $0.value.builtAt < Self.builtEventTimeout } + builtEvents[uuid] = (built, now) + result([ + "event": built.event, + "uuid": uuid, + "distinctId": built.distinctId, + "timestamp": Int64((built.timestamp.timeIntervalSince1970 * 1000).rounded()), + "properties": built.properties, + "options": built.options, + ]) + } + + /// Sends an event from `buildEvent` as the Dart beforeSend callbacks left + /// it. Returns its uuid once queued, or nil. + private func sendBuiltEvent( + _ call: FlutterMethodCall, + result: @escaping FlutterResult + ) { + guard let args = call.arguments as? [String: Any], + let uuid = args["uuid"] as? String, + let eventName = args["event"] as? String + else { + _badArgumentError(result) + return + } + guard let built = builtEvents.removeValue(forKey: uuid)?.event else { + result(nil) + return + } + built.event = eventName + built.properties = args["properties"] as? [String: Any] ?? [:] + built.options = args["options"] as? [String: Any] ?? [:] + if let distinctId = args["distinctId"] as? String, + !distinctId.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty + { + built.distinctId = distinctId + } + if let timestampMs = args["timestamp"] as? Int64 { + built.timestamp = Date(timeIntervalSince1970: TimeInterval(timestampMs) / 1000.0) + } + result(PostHogSDK.shared.sendBuiltEventForWrapper(built, ai: args["ai"] as? Bool ?? false)) + } + + /// Drops an event from `buildEvent` that a Dart beforeSend callback dropped. + private func discardBuiltEvent( + _ call: FlutterMethodCall, + result: @escaping FlutterResult + ) { + if let uuid = (call.arguments as? [String: Any])?["uuid"] as? String { + builtEvents.removeValue(forKey: uuid) + } + result(nil) + } + private func captureLog( _ call: FlutterMethodCall, result: @escaping FlutterResult @@ -1910,6 +2045,7 @@ extension PosthogFlutterPlugin { } private func close(_ result: @escaping FlutterResult) { + builtEvents.removeAll() PostHogSDK.shared.close() result(nil) } diff --git a/posthog_flutter/lib/posthog_flutter_web.dart b/posthog_flutter/lib/posthog_flutter_web.dart index aebc8567..cc96fe4b 100644 --- a/posthog_flutter/lib/posthog_flutter_web.dart +++ b/posthog_flutter/lib/posthog_flutter_web.dart @@ -55,7 +55,10 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { Map? userPropertiesSetOnce, Map? options, }) { - return applyBeforeSend( + final distinctId = + _beforeSendCallbacks.isEmpty ? null : currentWebDistinctId(); + final wasIdentified = distinctId != null && currentWebUserIdentified(); + final processed = applyBeforeSend( _beforeSendCallbacks, PostHogEvent( event: eventName, @@ -65,6 +68,35 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { options: options == null ? null : {...options}, ), ); + if (processed == null || + distinctId == null || + distinctId == currentWebDistinctId()) { + return processed; + } + // posthog-js stores an event's `$set` as the current user's person + // properties for flags, so after a reset() they would reach the next user. + // identify() of an anonymous user links the two, so they stay. + if (wasIdentified || !currentWebUserIdentified()) { + processed + ..userProperties = null + ..userPropertiesSetOnce = null + ..properties = {...?processed.properties} + ..properties!.remove(r'$set') + ..properties!.remove(r'$set_once'); + } + // posthog-js builds the event only after the callbacks, so one calling + // reset() or identify() would otherwise move the event to the new user. + // Event properties win over the stored distinct id. A callback changing + // consent under cookieless_mode swaps the id on purpose: neither the user + // who opted out nor the shared cookieless id may come back. + if (distinctId != r'$posthog_cookieless' && + !(posthog?.has_opted_out_capturing() ?? true)) { + processed.properties = { + 'distinct_id': distinctId, + ...?processed.properties, + }; + } + return processed; } /// posthog-js sends these calls' events without event properties, so @@ -240,6 +272,10 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { return; } + return _sendCapture(processedEvent); + } + + Future _sendCapture(PostHogEvent processedEvent) { final extracted = CaptureUtils.extractUserProperties( properties: processedEvent.properties, userProperties: processedEvent.userProperties, @@ -357,11 +393,7 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { } if (processedEvent.event != PostHogEventName.screen) { - await capture( - eventName: processedEvent.event, - properties: processedEvent.properties?.cast(), - options: processedEvent.options, - ); + await _sendCapture(processedEvent); return; } @@ -370,16 +402,28 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { screenName; _currentScreen = finalScreenName; processedEvent.properties?.remove(PostHogPropertyName.screenName); + final extracted = CaptureUtils.extractUserProperties( + properties: processedEvent.properties, + userProperties: processedEvent.userProperties, + userPropertiesSetOnce: processedEvent.userPropertiesSetOnce, + ); final remaining = _withOptionProperties( - processedEvent.properties, + extracted.properties, processedEvent.options, PostHogEventName.screen, ); + final userProperties = extracted.userProperties; + final userPropertiesSetOnce = extracted.userPropertiesSetOnce; return handleWebMethodCall( MethodCall('screen', { 'screenName': finalScreenName, if (remaining != null && remaining.isNotEmpty) 'properties': remaining, + if (userProperties != null) + 'userProperties': PropertyNormalizer.normalize(userProperties), + if (userPropertiesSetOnce != null) + 'userPropertiesSetOnce': + PropertyNormalizer.normalize(userPropertiesSetOnce), }), ); } @@ -686,22 +730,28 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { } if (processedEvent.event != PostHogEventName.exception) { - await capture( - eventName: processedEvent.event, - properties: processedEvent.properties?.cast(), - options: processedEvent.options, - ); + await _sendCapture(processedEvent); return; } - final normalizedData = PropertyNormalizer.normalize( - _withOptionProperties( - processedEvent.properties?.cast(), - processedEvent.options, - PostHogEventName.exception, - ) ?? - {}, + final extracted = CaptureUtils.extractUserProperties( + properties: processedEvent.properties?.cast(), + userProperties: processedEvent.userProperties, + userPropertiesSetOnce: processedEvent.userPropertiesSetOnce, ); + final userProperties = extracted.userProperties; + final userPropertiesSetOnce = extracted.userPropertiesSetOnce; + // posthog-js's captureException takes no capture options, but capture + // merges `$set` and `$set_once` from the event's properties. + final normalizedData = PropertyNormalizer.normalize({ + ...?_withOptionProperties( + extracted.properties, + processedEvent.options, + PostHogEventName.exception, + ), + if (userProperties != null) r'$set': userProperties, + if (userPropertiesSetOnce != null) r'$set_once': userPropertiesSetOnce, + }); return await handleWebMethodCall( MethodCall('captureException', {'properties': normalizedData}), diff --git a/posthog_flutter/lib/src/core/posthog_core.dart b/posthog_flutter/lib/src/core/posthog_core.dart index 1448388a..ba1141e9 100644 --- a/posthog_flutter/lib/src/core/posthog_core.dart +++ b/posthog_flutter/lib/src/core/posthog_core.dart @@ -17,11 +17,16 @@ import 'utils/utils.dart'; import 'uuid.dart'; /// An event built by [PostHogCore.prepareEvent]: its properties, its -/// capture v1 options and the time it happened, as an ISO 8601 string. +/// capture v1 options, the time it happened as an ISO 8601 string, its uuid, +/// the id of the person it is captured for, and whether it was captured with +/// person properties. typedef PostHogPreparedEvent = ({ Map properties, Map? options, String timestamp, + String uuid, + String distinctId, + bool requestsPersonProcessing, }); /// Stateful PostHog client with session management, identity, and feature flags. @@ -492,20 +497,34 @@ abstract class PostHogCore extends PostHogCoreStateless { if (_ignoredWhileOptedOut('posthog.capture')) { return SynchronousFuture(null); } - final (:properties, :options, :timestamp) = prepared; + final ( + :properties, + :options, + :timestamp, + :uuid, + :distinctId, + :requestsPersonProcessing, + ) = prepared; + final queued = captureAiStateless(distinctId, event, + properties: properties, + options: options, + timestamp: timestamp, + uuid: uuid); + // Sent for another distinct id, its person properties belong to that + // person, not to the current user. + if (distinctId != getDistinctId()) return queued; final generation = _resetGeneration; final capturedAt = ++_personPropertyClock; - final queued = captureAiStateless(getDistinctId(), event, - properties: properties, options: options, timestamp: timestamp); - final requestsPerson = _requestsPersonProcessing(properties); - if (requestsPerson) _aiEventsRequestingPerson++; + if (requestsPersonProcessing) _aiEventsRequestingPerson++; return queued.then((uuid) { if (uuid != null && generation == _resetGeneration) { - _applyPersonProperties(properties, capturedAt: capturedAt); + _applyPersonProperties(properties, + requestsPersonProcessing: requestsPersonProcessing, + capturedAt: capturedAt); } return uuid; }).whenComplete(() { - if (requestsPerson && generation == _resetGeneration) { + if (requestsPersonProcessing && generation == _resetGeneration) { _aiEventsRequestingPerson--; } }); @@ -513,16 +532,6 @@ abstract class PostHogCore extends PostHogCoreStateless { return queued ?? SynchronousFuture(null); } - /// [options] with `process_person_profile: false` added when person - /// processing is off and [properties] neither ask for it nor set - /// `$process_person_profile`, as [prepareEvent] decides it. - Map? personProcessingOptions( - Map? options, - Map properties, - ) => - _personProcessingOptions(options, properties, - requested: _requestsPersonProcessing(properties)); - PostHogPreparedEvent? _prepareEvent( String event, { Map? properties, @@ -531,6 +540,7 @@ abstract class PostHogCore extends PostHogCoreStateless { if (_ignoredWhileOptedOut('posthog.capture')) return null; final allProperties = _enrichProperties(properties); + final requestsPersonProcessing = _requestsPersonProcessing(properties); // Once an event is person-processed, all later ones are too. A value // passed for this event alone doesn't count. if (_hasPersonProcessing()) { @@ -541,9 +551,12 @@ abstract class PostHogCore extends PostHogCoreStateless { options: _personProcessingOptions( options, allProperties, - requested: _requestsPersonProcessing(properties), + requested: requestsPersonProcessing, ), timestamp: currentISOTime(), + uuid: generateUuidV7(), + distinctId: getDistinctId(), + requestsPersonProcessing: requestsPersonProcessing, ); } @@ -551,10 +564,25 @@ abstract class PostHogCore extends PostHogCoreStateless { String event, PostHogPreparedEvent prepared, ) { - final (:properties, :options, :timestamp) = prepared; - final queued = captureStateless(getDistinctId(), event, - properties: properties, options: options, timestamp: timestamp); - _applyPersonProperties(properties); + final ( + :properties, + :options, + :timestamp, + :uuid, + :distinctId, + :requestsPersonProcessing, + ) = prepared; + final queued = captureStateless(distinctId, event, + properties: properties, + options: options, + timestamp: timestamp, + uuid: uuid); + // A callback can send the event for another distinct id; its person + // properties then belong to that person, not to the current user's + // person processing, flags or person-properties hash. + if (distinctId != getDistinctId()) return queued; + _applyPersonProperties(properties, + requestsPersonProcessing: requestsPersonProcessing); if (event == r'$set' || event == r'$identify') { final set = properties[r'$set']; final setOnce = properties[r'$set_once']; @@ -569,15 +597,18 @@ abstract class PostHogCore extends PostHogCoreStateless { /// Applies the person properties of a queued event with [properties]: /// taken from the event as queued, after the beforeSend callbacks, so a - /// value they removed or an event they or the size limit dropped neither - /// reaches /flags nor turns on person processing for later events. + /// value they removed doesn't reach /flags. Person processing follows + /// [requestsPersonProcessing], what the app captured, like the event itself + /// and the native SDKs. An event they or the size limit dropped does + /// neither. /// /// With [capturedAt], person properties set since then are kept. void _applyPersonProperties( Map properties, { + required bool requestsPersonProcessing, int? capturedAt, }) { - if (_requestsPersonProcessing(properties)) _enablePersonProcessing(); + if (requestsPersonProcessing) _enablePersonProcessing(); final set = _asPropertyMap(properties[r'$set']); final setOnce = _asPropertyMap(properties[r'$set_once']); if (capturedAt == null) { diff --git a/posthog_flutter/lib/src/core/posthog_core_stateless.dart b/posthog_flutter/lib/src/core/posthog_core_stateless.dart index 89b79d6f..6ef448bb 100644 --- a/posthog_flutter/lib/src/core/posthog_core_stateless.dart +++ b/posthog_flutter/lib/src/core/posthog_core_stateless.dart @@ -360,6 +360,7 @@ abstract class PostHogCoreStateless { required Map properties, Map? options, String? timestamp, + String? uuid, }) => _enqueue( _analytics, @@ -371,6 +372,7 @@ abstract class PostHogCoreStateless { ), options: options, timestamp: timestamp, + uuid: uuid, ); /// Queues [event] on the AI queue, and completes with its uuid, or null @@ -382,8 +384,9 @@ abstract class PostHogCoreStateless { required Map properties, Map? options, String? timestamp, + String? uuid, }) { - final (:uuid, :queued) = _enqueue( + final enqueued = _enqueue( _ai, 'capture', _buildPayload( @@ -393,8 +396,9 @@ abstract class PostHogCoreStateless { ), options: options, timestamp: timestamp, + uuid: uuid, ); - return queued.then((kept) => kept ? uuid : null); + return enqueued.queued.then((kept) => kept ? enqueued.uuid : null); } @protected @@ -525,16 +529,18 @@ abstract class PostHogCoreStateless { }); } - /// Queues [message] on [lane] and returns its uuid, with whether the queue - /// keeps it: the AI queue drops an event over its size limit. Its capture - /// v1 [options] are queued with it; the legacy option properties are - /// converted only when the request is built, see [captureV1Event]. + /// Queues [message] on [lane], with [uuid] or a new one, and returns its + /// uuid, with whether the queue keeps it: the AI queue drops an event over + /// its size limit. Its capture v1 [options] are queued with it; the legacy + /// option properties are converted only when the request is built, see + /// [captureV1Event]. ({String uuid, Future queued}) _enqueue( _CaptureLane lane, String type, Map message, { Map? options, String? timestamp, + String? uuid, }) { final prepared = { ...message, @@ -546,7 +552,7 @@ abstract class PostHogCoreStateless { 'library': postHogFlutterSdkName, 'library_version': postHogFlutterVersion, 'timestamp': timestamp ?? currentISOTime(), - 'uuid': generateUuidV7(), + 'uuid': uuid ?? generateUuidV7(), }; final queue = lane.queue; diff --git a/posthog_flutter/lib/src/posthog_config.dart b/posthog_flutter/lib/src/posthog_config.dart index 2f6562c3..20f6c9f9 100644 --- a/posthog_flutter/lib/src/posthog_config.dart +++ b/posthog_flutter/lib/src/posthog_config.dart @@ -415,17 +415,35 @@ class PostHogConfig { /// `config.captureApplicationLifecycleEvents` is enabled /// - Feature flag events (`$feature_flag_called`) when /// `config.sendFeatureFlagEvent` is enabled - /// - Identity events (`$set`) when `identify` is called + /// - Identity events (`$identify`, `$set`, `$create_alias`, + /// `$groupidentify`) from `identify`, `setPersonProperties`, `alias` + /// and `group` /// - Survey events (`survey shown`, etc.) when `config.surveys` is enabled - /// - Only user-provided properties are available; system properties (like - /// `$device_type`, `$session_id`) are added by the native SDK at a later - /// stage. On Windows and Linux, the callbacks see the system properties - /// and the options the SDK adds, and can change them for that event, - /// except `$lib` and `$lib_version`, which PostHog sets from the SDK. + /// On iOS, macOS and Android, add a native hook with + /// `PosthogFlutterPlugin.addBeforeSend` (Swift or Kotlin) to filter or + /// edit those events. + /// - On iOS, macOS, Android, Windows and Linux, the callbacks see the + /// system properties (like `$device_type` and `$session_id`), the + /// registered properties and the options the SDK adds, and can change + /// them for that event, except `$lib` and `$lib_version`, which PostHog + /// sets from the SDK. On iOS, macOS and Android, registering callbacks + /// adds one more call to the native SDK per event. The native SDK keeps + /// each built event until Dart sends it back, and discards one still + /// waiting after a minute (for example, after a hot restart). On web, + /// only the event's own properties are available; posthog-js adds the + /// rest later. /// /// **Note:** - /// - Callbacks are synchronous. Load anything they need (such as remote - /// config) ahead of time. + /// - Callbacks are synchronous and run on the calling isolate, so a slow one + /// blocks the UI. Load anything they need (such as remote config or feature + /// flags) ahead of time; a change made after the callback returns is not + /// sent. + /// - A callback that captures an event must not do so for that event too, or + /// it never finishes. + /// - On web, an event whose callback calls `reset()` stays on its user but + /// joins the next user's session and person processing, and its user + /// properties are dropped, because posthog-js builds the event after the + /// callbacks. /// - If a callback throws, the event is dropped and later callbacks are not /// called. /// - If any callback returns `null`, the event is dropped and subsequent diff --git a/posthog_flutter/lib/src/posthog_event.dart b/posthog_flutter/lib/src/posthog_event.dart index 7063dd89..c8a3e556 100644 --- a/posthog_flutter/lib/src/posthog_event.dart +++ b/posthog_flutter/lib/src/posthog_event.dart @@ -2,17 +2,33 @@ /// /// This class is used in before-send callbacks to allow modification of events /// before they are sent to PostHog. +/// +/// On iOS, macOS, Android, Windows and Linux the callbacks get the event the +/// SDK is about to send, with its system and registered properties already +/// added. It also carries its [uuid], [distinctId] and [timestamp]. +/// +/// ```dart +/// config.beforeSend = [ +/// (event) { +/// event.properties?.remove(r'$device_name'); +/// return event; +/// }, +/// ]; +/// ``` class PostHogEvent { /// The name of the event (e.g., 'button_clicked', '$screen', '$exception') String event; - /// User-provided properties for this event. + /// The event's properties. + /// + /// On iOS, macOS, Android, Windows and Linux, the map already holds the + /// system properties (like `$device_type` and `$session_id`), then the + /// registered properties, then the event's own, and the event is sent as + /// the callbacks leave it. `$set` and `$set_once` are in [userProperties] + /// and [userPropertiesSetOnce] instead. /// - /// On iOS, macOS, Android and web, system properties (like $device_type, - /// $session_id, etc.) are added by the native SDK at a later stage and are - /// not available in this map. On Windows and Linux, the map already holds - /// them, then the registered properties, then the event's own, and the - /// event is sent as the callbacks leave it. + /// On web, only the event's own properties are here; posthog-js adds the + /// rest later. Map? properties; /// User properties to set on the user profile ($set). @@ -32,6 +48,25 @@ class PostHogEvent { /// unset. Map? options; + /// The event's unique id, a lowercase UUID v7. + /// + /// Set on iOS, macOS, Android, Windows and Linux, where the SDK builds the + /// event before the callbacks run. `null` on web. The id is kept even when + /// a callback returns another [PostHogEvent]. + final String? uuid; + + /// The id of the person the event is captured for. + /// + /// Set on iOS, macOS, Android, Windows and Linux, where a callback can + /// change it. `null` on web. + String? distinctId; + + /// When the event happened. + /// + /// Set on iOS, macOS, Android, Windows and Linux, where a callback can + /// change it. `null` on web. + DateTime? timestamp; + /// Creates an event passed to a before-send callback. /// /// The [event] is the event name to capture. @@ -45,16 +80,22 @@ class PostHogEvent { /// `$set_once`. /// /// The optional [options] are the event's per-event options. + /// + /// The optional [uuid], [distinctId] and [timestamp] are set by the SDK on + /// every platform but web. PostHogEvent({ required this.event, this.properties, this.userProperties, this.userPropertiesSetOnce, this.options, + this.uuid, + this.distinctId, + this.timestamp, }); @override String toString() { - return 'PostHogEvent(event: $event, properties: $properties, userProperties: $userProperties, userPropertiesSetOnce: $userPropertiesSetOnce, options: $options)'; + return 'PostHogEvent(event: $event, uuid: $uuid, distinctId: $distinctId, timestamp: $timestamp, properties: $properties, userProperties: $userProperties, userPropertiesSetOnce: $userPropertiesSetOnce, options: $options)'; } } diff --git a/posthog_flutter/lib/src/posthog_flutter_desktop.dart b/posthog_flutter/lib/src/posthog_flutter_desktop.dart index 94b16b02..57378cf3 100644 --- a/posthog_flutter/lib/src/posthog_flutter_desktop.dart +++ b/posthog_flutter/lib/src/posthog_flutter_desktop.dart @@ -3,6 +3,7 @@ import 'dart:async'; import 'package:flutter/widgets.dart'; import 'core/file_storage.dart'; +import 'core/posthog_core.dart' show PostHogPreparedEvent; import 'core/utils/utils.dart'; import 'error_tracking/dart_exception_processor.dart'; import 'feature_flag_result.dart'; @@ -100,18 +101,12 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { return client; } - DesktopPostHog? _clientForContinuation( - String op, - _ClientScope scope, - String distinctId, - ) { + DesktopPostHog? _clientForContinuation(String op, _ClientScope scope) { final client = _clientFor(op); if (client == null) return null; - if (_clientScope != scope || - client.optedOut || - client.getDistinctId() != distinctId) { - printIfDebug('[PostHog] $op dropped: the project, the user or the ' - 'consent changed while beforeSend was running.'); + if (_clientScope != scope || client.optedOut) { + printIfDebug('[PostHog] $op dropped: the project or the consent changed ' + 'while beforeSend was running.'); return null; } return client; @@ -277,8 +272,6 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { if (!_hasName(eventName)) return; final scope = _clientScope; if (scope == null) return; - final distinctId = client.getDistinctId(); - final exceptionSteps = _exceptionSteps; final prepared = _prepare( client, @@ -295,9 +288,9 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { return; } - final current = _clientForContinuation('capture', scope, distinctId); + final current = _clientForContinuation('capture', scope); if (current == null) return; - await _captureProcessed(current, processed, exceptionSteps, prepared); + await _captureProcessed(current, processed, prepared); }); @override @@ -318,8 +311,6 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { if (!_hasName(eventName)) return null; final scope = _clientScope; if (scope == null) return null; - final distinctId = client.getDistinctId(); - final exceptionSteps = _exceptionSteps; final prepared = _prepare( client, @@ -336,10 +327,9 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { return null; } - final current = _clientForContinuation('captureAi', scope, distinctId); + final current = _clientForContinuation('captureAi', scope); if (current == null) return null; - return _captureProcessed(current, processed, exceptionSteps, prepared, - ai: true); + return _captureProcessed(current, processed, prepared, ai: true); }); @override @@ -354,8 +344,6 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { if (client.optedOut) return; final scope = _clientScope; if (scope == null) return; - final distinctId = client.getDistinctId(); - final exceptionSteps = _exceptionSteps; final prepared = _prepare( client, @@ -367,6 +355,7 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { options: options, ); if (prepared == null) return; + final sessionId = client.getSessionId(); final processed = _runBeforeSend(prepared.event); if (processed == null) { printIfDebug( @@ -374,12 +363,12 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { return; } - final current = _clientForContinuation('screen', scope, distinctId); + final current = _clientForContinuation('screen', scope); if (current == null) return; // A renamed event is no longer a screen view. if (processed.event != PostHogEventName.screen) { - await _captureProcessed(current, processed, exceptionSteps, prepared); + await _captureProcessed(current, processed, prepared); return; } @@ -390,12 +379,13 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { return; } - // Later events that set no `$screen_name` of their own carry this one. - if (finalScreenName is String) { + // Later events that set no `$screen_name` of their own carry this one, + // unless a callback's reset() started a session for the next user. + if (finalScreenName is String && current.getSessionId() == sessionId) { current.registerForSession( {PostHogPropertyName.screenName: finalScreenName}); } - await _captureProcessed(current, processed, exceptionSteps, prepared); + await _captureProcessed(current, processed, prepared); }); /// Structured logs are not supported on the desktop implementation. @@ -625,8 +615,6 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { if (client.optedOut) return; final scope = _clientScope; if (scope == null) return; - final distinctId = client.getDistinctId(); - final exceptionSteps = _exceptionSteps; final exceptionProps = DartExceptionProcessor.processException( error: error, @@ -652,10 +640,9 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { return; } - final current = - _clientForContinuation('captureException', scope, distinctId); + final current = _clientForContinuation('captureException', scope); if (current == null) return; - await _captureProcessed(current, processed, exceptionSteps, prepared); + await _captureProcessed(current, processed, prepared); }); @override @@ -757,7 +744,9 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { /// [PostHogEvent.userPropertiesSetOnce]. Legacy `$set` and `$set_once` /// maps in [properties] stay in [PostHogEvent.properties], so a callback /// that removes them there still keeps them off the event. - /// The event's time is taken now, before the callbacks run. + /// The event's time, uuid and distinct id are taken now, before the + /// callbacks run. An `$exception` event gets the exception steps recorded + /// up to now, unless it sets its own. _PreparedEvent? _prepare( DesktopPostHog client, String eventName, @@ -767,10 +756,18 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { Map? options, }) { final callerOptions = cleanEventOptions(options); + final steps = _exceptionSteps?.steps; final prepared = client.prepareEvent( eventName, - properties: - _mergeUserProps(properties, userProperties, userPropertiesSetOnce), + properties: _mergeUserProps( + eventName == PostHogEventName.exception && + steps != null && + steps.isNotEmpty + ? {r'$exception_steps': steps, ...?properties} + : properties, + userProperties, + userPropertiesSetOnce, + ), options: callerOptions, ); if (prepared == null) return null; @@ -794,11 +791,11 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { userProperties: _nonNull(userProperties), userPropertiesSetOnce: _nonNull(userPropertiesSetOnce), options: preparedOptions == null ? null : {...preparedOptions}, + uuid: prepared.uuid, + distinctId: prepared.distinctId, + timestamp: DateTime.parse(prepared.timestamp), ), - timestamp: prepared.timestamp, - implicitPersonProcessing: - callerOptions?['process_person_profile'] == null, - sdkPersonProcessing: preparedOptions?['process_person_profile'], + prepared: prepared, ); } @@ -824,40 +821,40 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { /// Queues [event] as the beforeSend callbacks left it, on the AI queue /// with [ai], and returns its uuid, or null when it is not queued. The - /// client adds nothing to it; an `$exception` event gets the exception - /// steps recorded up to now. + /// client adds nothing to it. The event keeps the uuid it was prepared + /// with; a blank distinct id or a missing timestamp falls back to the + /// prepared one. FutureOr _captureProcessed( DesktopPostHog client, PostHogEvent event, - ExceptionStepsBuffer? exceptionSteps, _PreparedEvent prepared, { bool ai = false, }) { if (!_hasName(event.event)) return null; - final properties = _withExceptionSteps( - event.event, - exceptionSteps, - _mergeUserProps( - event.properties, - event.userProperties, - event.userPropertiesSetOnce, - ), + final properties = _mergeUserProps( + event.properties, + event.userProperties, + event.userPropertiesSetOnce, ) ?? const {}; // Options are sent as they are, unknown keys included. An option wins // over its legacy property on the event. - Map? options = cleanEventOptions(event.options); - // Person properties the callbacks added or removed decide person - // processing again, unless a callback changed the SDK's option. - if (prepared.implicitPersonProcessing && - options?['process_person_profile'] == prepared.sdkPersonProcessing) { - options = client.personProcessingOptions( - {...?options}..remove('process_person_profile'), properties); - } + final options = cleanEventOptions(event.options); + final base = prepared.prepared; + final distinctId = event.distinctId; + final timestamp = event.timestamp; final queued = ( properties: properties, options: options, - timestamp: prepared.timestamp, + timestamp: timestamp == null || + timestamp.isAtSameMomentAs(DateTime.parse(base.timestamp)) + ? base.timestamp + : timestamp.toUtc().toIso8601String(), + uuid: base.uuid, + distinctId: distinctId == null || distinctId.trim().isEmpty + ? base.distinctId + : distinctId, + requestsPersonProcessing: base.requestsPersonProcessing, ); return ai ? client.captureAiPrepared(event.event, queued) @@ -871,20 +868,6 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { return false; } - /// Uses the originating client's steps even when a same-scope restart - /// happened during beforeSend. Explicit event steps take precedence. - Map? _withExceptionSteps( - String event, - ExceptionStepsBuffer? exceptionSteps, - Map? properties, - ) { - final steps = exceptionSteps?.steps; - if (event != PostHogEventName.exception || steps == null || steps.isEmpty) { - return properties; - } - return {r'$exception_steps': steps, ...?properties}; - } - Map? _mergeUserProps( Map? properties, Map? userProperties, @@ -916,12 +899,8 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { } } -/// An event built for the beforeSend callbacks, with the time it happened, -/// whether its person processing was left to its properties, and the -/// `process_person_profile` option the SDK gave it. +/// An event built for the beforeSend callbacks, and what it was built from. typedef _PreparedEvent = ({ PostHogEvent event, - String timestamp, - bool implicitPersonProcessing, - Object? sdkPersonProcessing, + PostHogPreparedEvent prepared, }); diff --git a/posthog_flutter/lib/src/posthog_flutter_io.dart b/posthog_flutter/lib/src/posthog_flutter_io.dart index 18da22b0..6ba50646 100644 --- a/posthog_flutter/lib/src/posthog_flutter_io.dart +++ b/posthog_flutter/lib/src/posthog_flutter_io.dart @@ -1,4 +1,5 @@ import 'dart:async'; +import 'dart:typed_data'; import 'util/platform_io_stub.dart' if (dart.library.io) 'util/platform_io_real.dart'; @@ -52,6 +53,10 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { /// Stored beforeSend callbacks for dropping/modifying events List _beforeSendCallbacks = []; + /// Starts with `$` so the native SDKs treat it like `$screen` in every other + /// respect. Never sent: sendBuiltEvent sets the event's real name. + static const _capturedScreenBuildName = r'$captured_screen'; + final _order = CallOrder(); Future _invoke(String method, [Object? arguments]) { @@ -90,27 +95,152 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { return _handlerInstalled; } - /// Applies the beforeSend callbacks to an event in order. - /// Returns the possibly modified event, or null if any callback drops it. - PostHogEvent? _runBeforeSend( - String eventName, - Map? properties, { - Map? userProperties, - Map? userPropertiesSetOnce, - Map? options, + /// Builds the event in the native SDK, runs the beforeSend callbacks on + /// the built event, then has the native SDK send what they return, so the + /// callbacks see what the SDK adds. [build] holds the `buildEvent` + /// arguments. + /// + /// Returns the native send result (the uuid on the AI lane), or null when + /// the native SDK skips the event or a callback drops it. + Future _buildRunBeforeSendAndSend( + Map build, { + bool ai = false, + String? eventName, + }) async { + // setup() replaces the callbacks at once but reaches native after this + // event, which must not run under the next setup's filters. + final callbacks = _beforeSendCallbacks; + Object? result; + await _order.event<({String uuid, Map? send})?>( + () => _buildAndRunBeforeSend(build, ai, callbacks, eventName), + (built) async { + if (built == null) return; + final send = built.send; + if (send == null) { + await _methodChannel + .invokeMethod('discardBuiltEvent', {'uuid': built.uuid}); + return; + } + result = await _methodChannel.invokeMethod( + 'sendBuiltEvent', + {...send, 'uuid': built.uuid, 'ai': ai}, + ); + }, + ); + return result; + } + + /// Has the native SDK build the event and runs the beforeSend callbacks on + /// it. Returns null when the native SDK skips the event; `send` is null when + /// a callback drops it. + Future<({String uuid, Map? send})?> _buildAndRunBeforeSend( + Map build, + bool ai, + List callbacks, + String? eventName, + ) async { + final built = await _methodChannel.invokeMapMethod( + 'buildEvent', + {...build, 'ai': ai}, + ); + final uuid = built?['uuid']; + if (built == null || uuid is! String) return null; + + Map? send; + try { + final processed = applyBeforeSend( + callbacks, + _eventFromNative(built, eventName: eventName), + ); + if (processed == null) { + printIfDebug( + '[PostHog] Event dropped by beforeSend: ${eventName ?? built['event']}'); + } else { + send = _eventToNative(processed); + } + } catch (e) { + printIfDebug('[PostHog] Event dropped, it could not be read: $e'); + } + return (uuid: uuid, send: send); + } + + static PostHogEvent _eventFromNative( + Map built, { + String? eventName, }) { - return applyBeforeSend( - _beforeSendCallbacks, - PostHogEvent( - event: eventName, - properties: properties, - userProperties: userProperties, - userPropertiesSetOnce: userPropertiesSetOnce, - options: options == null ? null : {...options}, - ), + final properties = _stringKeyedMap(built['properties']) ?? {}; + final userProperties = _stringKeyedMap(properties.remove(r'$set')); + final userPropertiesSetOnce = + _stringKeyedMap(properties.remove(r'$set_once')); + final timestampMs = built['timestamp'] as int?; + return PostHogEvent( + event: eventName ?? built['event'] as String? ?? '', + properties: properties, + userProperties: userProperties, + userPropertiesSetOnce: userPropertiesSetOnce, + options: (built['options'] as Map?)?.cast(), + uuid: built['uuid'] as String?, + distinctId: built['distinctId'] as String?, + timestamp: timestampMs == null + ? null + : DateTime.fromMillisecondsSinceEpoch(timestampMs, isUtc: true), ); } + static Map _eventToNative(PostHogEvent event) { + final extracted = CaptureUtils.extractUserProperties( + properties: event.properties, + userProperties: event.userProperties, + userPropertiesSetOnce: event.userPropertiesSetOnce, + ); + final properties = { + ...?extracted.properties, + if (extracted.userProperties != null) r'$set': extracted.userProperties!, + if (extracted.userPropertiesSetOnce != null) + r'$set_once': extracted.userPropertiesSetOnce!, + }; + return { + 'event': event.event, + 'properties': PropertyNormalizer.normalize(properties), + if (event.distinctId?.trim().isNotEmpty == true) + 'distinctId': event.distinctId, + if (event.timestamp != null) + 'timestamp': event.timestamp!.millisecondsSinceEpoch, + 'options': cleanEventOptions(event.options) ?? const {}, + }; + } + + /// Copies a map from the channel with its string keys and non-null values. + static Map? _stringKeyedMap(Object? value) { + if (value is! Map) return null; + return { + for (final entry in value.entries) + if (entry.key is String && entry.value != null) + entry.key as String: _valueFromNative(entry.value) as Object, + }; + } + + /// Gives a nested value from the channel, where every map and list is + /// untyped, the types `capture` callers pass: callbacks commonly cast + /// `$exception_list` to `List>`, and a failed cast + /// drops the event. + static Object? _valueFromNative(Object? value) { + if (value is Map) { + if (value.keys.any((key) => key is! String)) return value; + return { + for (final entry in value.entries) + entry.key as String: _valueFromNative(entry.value), + }; + } + if (value is List && value is! TypedData) { + final items = value.map(_valueFromNative).toList(); + return items.isNotEmpty && items.every((i) => i is Map) + ? List>.from(items) + : items; + } + return value; + } + /// Native plugin calls to Flutter /// Future _handleMethodCall(MethodCall call) async { @@ -407,71 +537,81 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { return null; } - Object? result; - await _order.event( - () => _runBeforeSend( - eventName, - properties, - userProperties: userProperties, - userPropertiesSetOnce: userPropertiesSetOnce, - options: options, - ), - (processedEvent) async { - result = await _sendCapture(method, eventName, processedEvent); - }, - ); - return result; - } - - Future _sendCapture( - String method, - String eventName, - PostHogEvent? processedEvent, - ) async { - if (processedEvent == null) { - printIfDebug('[PostHog] Event dropped by beforeSend: $eventName'); - return null; + if (_beforeSendCallbacks.isNotEmpty) { + final ai = method == 'captureAi'; + try { + return await _buildRunBeforeSendAndSend( + { + ..._captureArguments( + eventName: eventName, + properties: properties, + userProperties: userProperties, + userPropertiesSetOnce: userPropertiesSetOnce, + options: options, + ), + // The native builders treat `$screen` as a screen() call: it needs + // a `$screen_name` and, on iOS, loses person properties. A plain + // capture has neither rule, so it builds under another name. + if (!ai && eventName == PostHogEventName.screen) + 'eventName': _capturedScreenBuildName, + }, + ai: ai, + eventName: eventName, + ); + } on PlatformException catch (exception) { + printIfDebug('Exeption on $method: $exception'); + return null; + } } try { - // Use processed event properties (potentially modified by beforeSend) - final extracted = CaptureUtils.extractUserProperties( - properties: processedEvent.properties, - userProperties: processedEvent.userProperties, - userPropertiesSetOnce: processedEvent.userPropertiesSetOnce, + return await _invoke( + method, + _captureArguments( + eventName: eventName, + properties: properties, + userProperties: userProperties, + userPropertiesSetOnce: userPropertiesSetOnce, + options: options, + ), ); - - final extractedProperties = extracted.properties; - final extractedUserProperties = extracted.userProperties; - final extractedUserPropertiesSetOnce = extracted.userPropertiesSetOnce; - - final normalizedProperties = extractedProperties != null - ? PropertyNormalizer.normalize(extractedProperties) - : null; - final normalizedUserProperties = extractedUserProperties != null - ? PropertyNormalizer.normalize(extractedUserProperties) - : null; - final normalizedUserPropertiesSetOnce = - extractedUserPropertiesSetOnce != null - ? PropertyNormalizer.normalize(extractedUserPropertiesSetOnce) - : null; - final cleanedOptions = cleanEventOptions(processedEvent.options); - - return await _invoke(method, { - 'eventName': processedEvent.event, - if (normalizedProperties != null) 'properties': normalizedProperties, - if (normalizedUserProperties != null) - 'userProperties': normalizedUserProperties, - if (normalizedUserPropertiesSetOnce != null) - 'userPropertiesSetOnce': normalizedUserPropertiesSetOnce, - if (cleanedOptions != null) 'options': cleanedOptions, - }); } on PlatformException catch (exception) { printIfDebug('Exeption on $method: $exception'); return null; } } + /// The `capture`, `captureAi` and `buildEvent` arguments, with `$set` and + /// `$set_once` moved out of [properties] and the values normalized. + static Map _captureArguments({ + required String eventName, + Map? properties, + Map? userProperties, + Map? userPropertiesSetOnce, + Map? options, + }) { + final extracted = CaptureUtils.extractUserProperties( + properties: properties, + userProperties: userProperties, + userPropertiesSetOnce: userPropertiesSetOnce, + ); + final extractedProperties = extracted.properties; + final extractedUserProperties = extracted.userProperties; + final extractedUserPropertiesSetOnce = extracted.userPropertiesSetOnce; + final cleanedOptions = cleanEventOptions(options); + return { + 'eventName': eventName, + if (extractedProperties != null) + 'properties': PropertyNormalizer.normalize(extractedProperties), + if (extractedUserProperties != null) + 'userProperties': PropertyNormalizer.normalize(extractedUserProperties), + if (extractedUserPropertiesSetOnce != null) + 'userPropertiesSetOnce': + PropertyNormalizer.normalize(extractedUserPropertiesSetOnce), + if (cleanedOptions != null) 'options': cleanedOptions, + }; + } + @override Future screen({ required String screenName, @@ -482,62 +622,34 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { return; } - // The screen name argument wins over a properties `$screen_name`. - // beforeSend still runs after this and can change the name. - final propsWithScreenName = { - ...?properties, - PostHogPropertyName.screenName: screenName, - }; - - // Apply beforeSend callback - screen events are captured as $screen - return _order.event( - () => _runBeforeSend( - PostHogEventName.screen, - propsWithScreenName, - options: options, - ), - (processedEvent) => _sendScreen(screenName, processedEvent), - ); - } - - Future _sendScreen( - String screenName, - PostHogEvent? processedEvent, - ) async { - if (processedEvent == null) { - printIfDebug('[PostHog] Screen event dropped by beforeSend: $screenName'); - return; - } - - // If event name was changed, use regular capture() instead - if (processedEvent.event != PostHogEventName.screen) { - await capture( - eventName: processedEvent.event, - properties: processedEvent.properties?.cast(), - options: processedEvent.options, - ); + if (_beforeSendCallbacks.isNotEmpty) { + try { + final cleanedOptions = cleanEventOptions(options); + await _buildRunBeforeSendAndSend({ + 'eventName': PostHogEventName.screen, + // The screen name argument wins over a properties `$screen_name`. + 'properties': PropertyNormalizer.normalize({ + ...?properties, + PostHogPropertyName.screenName: screenName, + }), + if (cleanedOptions != null) 'options': cleanedOptions, + }); + } on PlatformException catch (exception) { + printIfDebug('Exeption on screen: $exception'); + } return; } - // Get the (possibly modified) screen name from properties and remove it - final finalScreenName = - processedEvent.properties?[PostHogPropertyName.screenName] as String? ?? - screenName; - // It will be added back by native sdk - processedEvent.properties?.remove(PostHogPropertyName.screenName); - try { - final normalizedProperties = processedEvent.properties?.isNotEmpty == true - ? PropertyNormalizer.normalize( - processedEvent.properties!.cast(), - ) - : null; - - final cleanedOptions = cleanEventOptions(processedEvent.options); + // The native SDK adds the screen name back as `$screen_name`. + final screenProperties = {...?properties} + ..remove(PostHogPropertyName.screenName); + final cleanedOptions = cleanEventOptions(options); await _invoke('screen', { - 'screenName': finalScreenName, - if (normalizedProperties != null) 'properties': normalizedProperties, + 'screenName': screenName, + if (screenProperties.isNotEmpty) + 'properties': PropertyNormalizer.normalize(screenProperties), if (cleanedOptions != null) 'options': cleanedOptions, }); } on PlatformException catch (exception) { @@ -975,56 +1087,34 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { inAppByDefault: _config?.errorTrackingConfig.inAppByDefault ?? true, ); - // Apply beforeSend callback - exception events are captured as $exception - await _order.event( - () => _runBeforeSend( - PostHogEventName.exception, - exceptionProps.cast(), - options: options, - ), - (processedEvent) => _sendException(error, processedEvent), - ); - } on PlatformException catch (exception) { - printIfDebug('Exception in captureException: $exception'); - } - } + if (_beforeSendCallbacks.isNotEmpty) { + final cleanedOptions = cleanEventOptions(options); + await _buildRunBeforeSendAndSend({ + 'eventName': PostHogEventName.exception, + 'properties': PropertyNormalizer.normalize( + exceptionProps.cast(), + ), + 'timestamp': DateTime.now().millisecondsSinceEpoch, + if (cleanedOptions != null) 'options': cleanedOptions, + }); + return; + } - Future _sendException( - Object error, - PostHogEvent? processedEvent, - ) async { - if (processedEvent == null) { - printIfDebug( - '[PostHog] Exception event dropped by beforeSend: ${error.runtimeType}', + // Add timestamp from Flutter side (will be used and removed from native plugins) + final timestamp = DateTime.now().millisecondsSinceEpoch; + final normalizedData = PropertyNormalizer.normalize( + exceptionProps.cast(), ); - return; - } + final cleanedOptions = cleanEventOptions(options); - // If event name was changed, use capture() instead - if (processedEvent.event != PostHogEventName.exception) { - await capture( - eventName: processedEvent.event, - properties: processedEvent.properties?.cast(), - options: processedEvent.options, - ); - return; + await _invoke('captureException', { + 'timestamp': timestamp, + 'properties': normalizedData, + if (cleanedOptions != null) 'options': cleanedOptions, + }); + } on PlatformException catch (exception) { + printIfDebug('Exception in captureException: $exception'); } - - // Add timestamp from Flutter side (will be used and removed from native plugins) - final timestamp = DateTime.now().millisecondsSinceEpoch; - final normalizedData = processedEvent.properties != null - ? PropertyNormalizer.normalize( - processedEvent.properties!.cast(), - ) - : {}; - - final cleanedOptions = cleanEventOptions(processedEvent.options); - - await _invoke('captureException', { - 'timestamp': timestamp, - 'properties': normalizedData, - if (cleanedOptions != null) 'options': cleanedOptions, - }); } @override diff --git a/posthog_flutter/lib/src/posthog_flutter_web_handler.dart b/posthog_flutter/lib/src/posthog_flutter_web_handler.dart index 1f070ad7..a52b4d08 100644 --- a/posthog_flutter/lib/src/posthog_flutter_web_handler.dart +++ b/posthog_flutter/lib/src/posthog_flutter_web_handler.dart @@ -67,6 +67,8 @@ extension PostHogExtension on PostHog { external void unregister(JSAny key); // ignore: non_constant_identifier_names external JSAny? get_session_id(); + // ignore: non_constant_identifier_names + external JSAny? get_property(JSAny name); // The loader snippet's stub returns undefined until posthog-js loads. external JSFunction? onFeatureFlags(JSFunction callback); external void startSessionRecording(); @@ -297,6 +299,27 @@ Future> _reloadFeatureFlags(PostHog? ph) async { } } +/// The user posthog-js would send an event as right now. +String? currentWebDistinctId() => + posthog?.get_distinct_id()?.dartify() as String?; + +/// Whether posthog-js's current user is identified. +bool currentWebUserIdentified() => + posthog?.get_property(r'$user_state'.toJS)?.dartify() == 'identified'; + +/// posthog-js capture options carrying `$set` and `$set_once`. +/// See: https://github.com/PostHog/posthog-js/blob/main/packages/types/src/capture.ts +Map _personCaptureOptions(Map args) { + final userProperties = safeMapConversion(args['userProperties']); + final userPropertiesSetOnce = safeMapConversion( + args['userPropertiesSetOnce'], + ); + return { + if (userProperties.isNotEmpty) '\$set': userProperties, + if (userPropertiesSetOnce.isNotEmpty) '\$set_once': userPropertiesSetOnce, + }; +} + Future handleWebMethodCall(MethodCall call) async { _maybeOverrideSDKInfo(); @@ -339,20 +362,7 @@ Future handleWebMethodCall(MethodCall call) async { final properties = safeMapConversion(args['properties']); properties.addAll(_getLocationProperties()); _addAppVersionProperties(properties); - final userProperties = safeMapConversion(args['userProperties']); - final userPropertiesSetOnce = safeMapConversion( - args['userPropertiesSetOnce'], - ); - - // Build options object for posthog-js capture with $set and $set_once - // See: https://github.com/PostHog/posthog-js/blob/main/packages/types/src/capture.ts - final options = {}; - if (userProperties.isNotEmpty) { - options['\$set'] = userProperties; - } - if (userPropertiesSetOnce.isNotEmpty) { - options['\$set_once'] = userPropertiesSetOnce; - } + final options = _personCaptureOptions(args); posthog?.capture( stringToJSAny(eventName), @@ -367,7 +377,12 @@ Future handleWebMethodCall(MethodCall call) async { properties.addAll(_getLocationProperties()); _addAppVersionProperties(properties); - posthog?.capture(stringToJSAny('\$screen'), mapToJSAny(properties), null); + final options = _personCaptureOptions(args); + posthog?.capture( + stringToJSAny('\$screen'), + mapToJSAny(properties), + options.isNotEmpty ? mapToJSAny(options) : null, + ); break; case 'captureLog': final body = args['body'] as String; diff --git a/posthog_flutter/lib/src/utils/call_order.dart b/posthog_flutter/lib/src/utils/call_order.dart index 9dbb430a..42b6af6e 100644 --- a/posthog_flutter/lib/src/utils/call_order.dart +++ b/posthog_flutter/lib/src/utils/call_order.dart @@ -35,8 +35,7 @@ class CallOrder { /// Runs [hook] once every earlier call has been handed over, so it sees /// the state the app left before capturing, then hands its result to - /// [send]. Later calls wait for [send] to finish, so it may itself capture - /// (a beforeSend that renames a `$screen` does). + /// [send]. Later calls wait for [send] to finish. Future event( FutureOr Function() hook, Future Function(E event) send, @@ -62,8 +61,8 @@ class CallOrder { Future Function(E event) send, ) async { final timer = Timer(maxWait, () { - printIfDebug('[PostHog] beforeSend took longer than ' - '${maxWait.inSeconds}s; later calls no longer wait for it.'); + printIfDebug('[PostHog] An event took longer than ' + '${maxWait.inSeconds}s to hand over; later calls no longer wait for it.'); turn.ahead.then((_) => turn.end()); }); try { diff --git a/posthog_flutter/test/event_shape_snapshot_test.dart b/posthog_flutter/test/event_shape_snapshot_test.dart index 0320d7e0..b369d61f 100644 --- a/posthog_flutter/test/event_shape_snapshot_test.dart +++ b/posthog_flutter/test/event_shape_snapshot_test.dart @@ -21,6 +21,23 @@ void main() { setUp(() async { messenger.setMockMethodCallHandler(channel, (call) async { calls.add(call); + final arguments = call.arguments; + if (call.method == 'buildEvent' && arguments is Map) { + return { + 'event': arguments['eventName'], + 'uuid': 'snapshot-uuid', + 'distinctId': 'snapshot-user', + 'timestamp': 1709296200000, + 'properties': { + ...?(arguments['properties'] as Map?), + if (arguments['userProperties'] != null) + r'$set': arguments['userProperties'], + if (arguments['userPropertiesSetOnce'] != null) + r'$set_once': arguments['userPropertiesSetOnce'], + }, + 'options': arguments['options'] ?? {}, + }; + } return null; }); PosthogFlutterPlatformInterface.instance = PosthogFlutterIO(); @@ -268,17 +285,22 @@ void main() { ); final normalizedCalls = calls.map((call) { - if (call.method != 'captureException') { + final arguments = call.arguments is Map + ? Map.from(call.arguments as Map) + : null; + final rawProperties = arguments?['properties']; + if (arguments == null || + rawProperties is! Map || + !rawProperties.containsKey(r'$exception_list')) { return call; } - final arguments = Map.from(call.arguments as Map); - expect(arguments['timestamp'], isA()); - arguments['timestamp'] = ''; + if (call.method == 'buildEvent') { + expect(arguments['timestamp'], isA()); + arguments['timestamp'] = ''; + } - final properties = Map.from( - arguments['properties'] as Map, - ); + final properties = Map.from(rawProperties); final exceptionList = List.from( properties[r'$exception_list'] as List, ); diff --git a/posthog_flutter/test/posthog_flutter_desktop_test.dart b/posthog_flutter/test/posthog_flutter_desktop_test.dart index 172ec20a..a1ec3bcd 100644 --- a/posthog_flutter/test/posthog_flutter_desktop_test.dart +++ b/posthog_flutter/test/posthog_flutter_desktop_test.dart @@ -574,6 +574,207 @@ void main() { }); group('beforeSend hook', () { + group('that calls the SDK', () { + test('can capture another event without running forever', () async { + final server = await LocalPostHogServer.start(); + final seen = []; + late final PosthogFlutterDesktop platform; + final config = configFor(server) + ..beforeSend = [ + (event) { + seen.add(event.event); + if (event.event == 'outer') { + platform.capture(eventName: 'inner'); + } + return event; + }, + ]; + platform = await setUpPlatform(config); + + await platform.capture(eventName: 'outer'); + await server.waitForEvent('inner'); + await server.waitForEvent('outer'); + + expect(seen, ['outer', 'inner']); + }); + + final calls = Function(PosthogFlutterDesktop)>{ + 'reset': (platform) => platform.reset(), + 'identify': (platform) => platform.identify(userId: 'user-1'), + 'optOut': (platform) => platform.optOut(), + 'getDistinctId': (platform) => platform.getDistinctId(), + 'getFeatureFlag': (platform) => platform.getFeatureFlag(key: 'flag'), + }; + + calls.forEach((name, call) { + test('$name inside the hook does not deadlock', () async { + final server = await LocalPostHogServer.start(); + late final PosthogFlutterDesktop platform; + final config = configFor(server) + ..beforeSend = [ + (event) { + if (event.event == 'trigger') call(platform); + return event; + }, + ]; + platform = await setUpPlatform(config); + + await platform + .capture(eventName: 'trigger') + .timeout(const Duration(seconds: 2)); + }); + }); + }); + + for (final (name, call) + in <(String, Future Function(PosthogFlutterDesktop))>[ + ('reset', (platform) => platform.reset()), + ('identify', (platform) => platform.identify(userId: 'user-1')), + ]) { + test('$name inside the hook keeps the event on the earlier user', + () async { + final server = await LocalPostHogServer.start(); + late final PosthogFlutterDesktop platform; + final config = configFor(server) + ..beforeSend = [ + (event) { + if (event.event == 'trigger') call(platform); + return event; + }, + ]; + platform = await setUpPlatform(config); + final firstUser = await platform.getDistinctId(); + + await platform.capture(eventName: 'trigger'); + + final event = await server.waitForEvent('trigger'); + expect(event['distinct_id'], firstUser); + expect(await platform.getDistinctId(), isNot(firstUser)); + }); + } + + test('reset inside the hook leaves an identified event person-processed', + () async { + final server = await LocalPostHogServer.start(); + late final PosthogFlutterDesktop platform; + final config = configFor(server) + ..beforeSend = [ + (event) { + if (event.event == 'trigger') platform.reset(); + return event; + }, + ]; + platform = await setUpPlatform(config); + await platform.identify(userId: 'user-1'); + + await platform.capture(eventName: 'trigger'); + + final event = await server.waitForEvent('trigger'); + expect(event['distinct_id'], 'user-1'); + expect(_optionsOf(event), isNot(contains('process_person_profile'))); + }); + + test('identify inside the hook leaves an anonymous event personless', + () async { + final server = await LocalPostHogServer.start(); + late final PosthogFlutterDesktop platform; + final config = configFor(server) + ..beforeSend = [ + (event) { + if (event.event == 'trigger') { + platform.identify(userId: 'user-1'); + } + return event; + }, + ]; + platform = await setUpPlatform(config); + + await platform.capture(eventName: 'trigger'); + + final event = await server.waitForEvent('trigger'); + expect(_optionsOf(event)['process_person_profile'], isFalse); + }); + + test('reset inside the hook keeps the screen from the next user', () async { + final server = await LocalPostHogServer.start(); + late final PosthogFlutterDesktop platform; + final config = configFor(server) + ..beforeSend = [ + (event) { + if (event.event == r'$screen') platform.reset(); + return event; + }, + ]; + platform = await setUpPlatform(config); + + await platform.screen(screenName: 'Checkout'); + await platform.capture(eventName: 'after reset'); + + final event = await server.waitForEvent('after reset'); + expect(_propertiesOf(event), isNot(contains(r'$screen_name'))); + }); + + test('identify inside the hook keeps the screen for later events', + () async { + final server = await LocalPostHogServer.start(); + late final PosthogFlutterDesktop platform; + final config = configFor(server) + ..beforeSend = [ + (event) { + if (event.event == r'$screen') { + platform.identify(userId: 'user-1'); + } + return event; + }, + ]; + platform = await setUpPlatform(config); + + await platform.screen(screenName: 'Checkout'); + await platform.capture(eventName: 'after identify'); + + final event = await server.waitForEvent('after identify'); + expect(_propertiesOf(event)[r'$screen_name'], 'Checkout'); + }); + + test('optOut inside the hook drops the event', () async { + final server = await LocalPostHogServer.start(); + late final PosthogFlutterDesktop platform; + final config = configFor(server) + ..beforeSend = [ + (event) { + if (event.event == 'trigger') platform.optOut(); + return event; + }, + ]; + platform = await setUpPlatform(config); + + await platform.capture(eventName: 'trigger'); + await platform.optIn(); + await platform.capture(eventName: 'after'); + await server.waitForEvent('after'); + + expect(server.eventNames, isNot(contains('trigger'))); + }); + + test('calls after a burst of events apply in order', () async { + final server = await LocalPostHogServer.start(); + final config = configFor(server)..beforeSend = [(event) => event]; + final platform = await setUpPlatform(config); + final firstUser = await platform.getDistinctId(); + + final sent = [ + for (var i = 0; i < 100; i++) platform.capture(eventName: 'event $i'), + platform.reset(), + platform.capture(eventName: 'after reset'), + ]; + await Future.wait(sent); + + final last = await server.waitForEvent('event 99'); + expect(last['distinct_id'], firstUser); + final after = await server.waitForEvent('after reset'); + expect(after['distinct_id'], isNot(firstUser)); + }); + test('dropping an event keeps it off the wire', () async { final server = await LocalPostHogServer.start(); final config = configFor(server) @@ -591,6 +792,55 @@ void main() { expect(server.eventNames, isNot(contains('dropped event'))); }); + test( + 'a callback sees the uuid, distinct id and timestamp, and can change ' + 'the distinct id and timestamp but not the uuid', () async { + final server = await LocalPostHogServer.start(); + PostHogEvent? seen; + final config = configFor(server) + ..beforeSend = [ + (event) { + seen = PostHogEvent( + event: event.event, + uuid: event.uuid, + distinctId: event.distinctId, + timestamp: event.timestamp, + ); + return PostHogEvent( + event: event.event, + properties: event.properties, + distinctId: 'changed-user', + timestamp: DateTime.utc(2025, 1, 2, 3, 4, 5, 678), + ); + }, + ]; + final platform = await setUpPlatform(config); + final distinctId = await platform.getDistinctId(); + + await platform.capture(eventName: 'identity'); + + final event = await server.waitForEvent('identity'); + expect(seen!.uuid, isNotNull); + expect(seen!.distinctId, distinctId); + expect(seen!.timestamp, isNotNull); + expect(event['uuid'], seen!.uuid); + expect(event['distinct_id'], 'changed-user'); + expect(event['timestamp'], '2025-01-02T03:04:05.678Z'); + }); + + test('a blank distinct id from a callback keeps the current one', () async { + final server = await LocalPostHogServer.start(); + final config = configFor(server) + ..beforeSend = [(event) => event..distinctId = ' ']; + final platform = await setUpPlatform(config); + final distinctId = await platform.getDistinctId(); + + await platform.capture(eventName: 'blank'); + + final event = await server.waitForEvent('blank'); + expect(event['distinct_id'], distinctId); + }); + test('modifications made by a callback are delivered', () async { final server = await LocalPostHogServer.start(); final config = configFor(server) @@ -691,6 +941,54 @@ void main() { expect(personProperties, isNot(contains('dropped'))); }); + test( + 'person properties of an event a callback sends for another distinct ' + 'id stay out of flag evaluation', () async { + final server = await LocalPostHogServer.start(); + final config = configFor(server) + ..preloadFeatureFlags = false + ..beforeSend = [(event) => event..distinctId = 'other-user']; + final platform = await setUpPlatform(config); + + await platform.capture( + eventName: 'other', + userProperties: {'email': 'other@example.com'}, + ); + await platform.reloadFeatureFlags(); + + final event = await server.waitForEvent('other'); + expect(event['distinct_id'], 'other-user'); + final personProperties = Map.from( + server.flagsRequests.single.body['person_properties']! as Map, + ); + expect(personProperties, isNot(contains('email'))); + }); + + test( + 'person properties of an event a callback sends for another distinct ' + 'id leave person processing off for the current user', () async { + final server = await LocalPostHogServer.start(); + final config = configFor(server) + ..beforeSend = [ + (event) { + if (event.event == 'other') event.distinctId = 'other-user'; + return event; + }, + ]; + final platform = await setUpPlatform(config); + + await platform.capture( + eventName: 'other', + userProperties: {'email': 'other@example.com'}, + ); + await platform.capture(eventName: 'next'); + + final event = await server.waitForEvent('other'); + expect(event['distinct_id'], 'other-user'); + final next = await server.waitForEvent('next'); + expect(_optionsOf(next)['process_person_profile'], isFalse); + }); + test('a dropped person update does not turn on person processing', () async { final server = await LocalPostHogServer.start(); @@ -710,7 +1008,7 @@ void main() { expect(_optionsOf(event)['process_person_profile'], isFalse); }); - test('an event whose person properties are removed is personless', + test('removing person properties leaves person processing as prepared', () async { final server = await LocalPostHogServer.start(); final config = configFor(server) @@ -723,10 +1021,10 @@ void main() { ); final event = await server.waitForEvent('redacted'); - expect(_optionsOf(event)['process_person_profile'], isFalse); + expect(_optionsOf(event), isNot(contains('process_person_profile'))); }); - test('person properties a callback adds turn on person processing', + test('person properties a callback adds leave the event personless', () async { final server = await LocalPostHogServer.start(); final config = configFor(server) @@ -738,10 +1036,49 @@ void main() { await platform.capture(eventName: 'signed up'); final event = await server.waitForEvent('signed up'); - expect(_optionsOf(event), isNot(contains('process_person_profile'))); + expect(_optionsOf(event)['process_person_profile'], isFalse); expect(_propertiesOf(event)[r'$set'], {'email': 'user@example.com'}); }); + test('person properties a callback adds leave later events personless', + () async { + final server = await LocalPostHogServer.start(); + final config = configFor(server) + ..beforeSend = [ + (event) { + if (event.event == 'signed up') { + event.userProperties = {'email': 'user@example.com'}; + } + return event; + }, + ]; + final platform = await setUpPlatform(config); + + await platform.capture(eventName: 'signed up'); + await platform.capture(eventName: 'next'); + + final next = await server.waitForEvent('next'); + expect(_optionsOf(next)['process_person_profile'], isFalse); + }); + + test( + 'removing person properties keeps person processing on for later events', + () async { + final server = await LocalPostHogServer.start(); + final config = configFor(server) + ..beforeSend = [(event) => event..userProperties = null]; + final platform = await setUpPlatform(config); + + await platform.capture( + eventName: 'redacted', + userProperties: {'email': 'user@example.com'}, + ); + await platform.capture(eventName: 'next'); + + final next = await server.waitForEvent('next'); + expect(_optionsOf(next), isNot(contains('process_person_profile'))); + }); + test('a callback can turn person processing back on', () async { final server = await LocalPostHogServer.start(); final config = configFor(server) @@ -1118,6 +1455,30 @@ void main() { expect(stepMessagesOf(event), ['custom']); }); + test('are visible to beforeSend, which can remove them', () async { + final server = await LocalPostHogServer.start(); + final seen = []; + final config = configFor(server) + ..beforeSend = [ + (event) { + seen.add(event.properties?.remove(r'$exception_steps')); + return event; + }, + ]; + final platform = await setUpPlatform(config); + + await platform.addExceptionStep('recorded'); + await platform.captureException(error: StateError('removed steps')); + + final event = await server.waitForEvent(r'$exception'); + expect(seen, [ + [ + {r'$message': 'recorded', r'$timestamp': isA()}, + ], + ]); + expect(stepMessagesOf(event), isNull); + }); + test('are not attached while disabled', () async { final server = await LocalPostHogServer.start(); final config = configFor(server) diff --git a/posthog_flutter/test/posthog_flutter_io_test.dart b/posthog_flutter/test/posthog_flutter_io_test.dart index e4b59c14..eb4dc6b1 100644 --- a/posthog_flutter/test/posthog_flutter_io_test.dart +++ b/posthog_flutter/test/posthog_flutter_io_test.dart @@ -1,3 +1,5 @@ +import 'dart:async'; + import 'package:flutter/foundation.dart'; import 'package:flutter/services.dart'; import 'package:flutter_test/flutter_test.dart'; @@ -39,6 +41,12 @@ void main() { if (methodCall.method == 'setup') { return null; } + if (methodCall.method == 'buildEvent') { + return nativeBuiltEvent(methodCall.arguments as Map); + } + if (methodCall.method == 'sendBuiltEvent') { + return (methodCall.arguments as Map)['uuid']; + } return null; }); }); @@ -672,13 +680,14 @@ isolate_dso_base: 7000000000 eventName: r'$ai_span', options: options); await posthogFlutterIO.screen(screenName: 'Home', options: options); - expect(seen, [options, options]); + expect(seen, [sent, sent]); const changed = { 'process_person_profile': false, 'product_tour_id': 'tour-1', }; - expect(argsOf('captureAi')['options'], changed); - expect(argsOf('screen')['options'], changed); + final sends = log.where((c) => c.method == 'sendBuiltEvent').toList(); + expect(sends.map((c) => (c.arguments as Map)['options']), + [changed, changed]); }); test('a screen renamed by beforeSend keeps its options', () async { @@ -694,8 +703,8 @@ isolate_dso_base: 7000000000 await posthogFlutterIO.screen(screenName: 'Home', options: options); - expect(argsOf('capture')['eventName'], 'screen viewed'); - expect(argsOf('capture')['options'], sent); + expect(argsOf('sendBuiltEvent')['event'], 'screen viewed'); + expect(argsOf('sendBuiltEvent')['options'], sent); }); test('captureAi dropped by beforeSend returns null', () async { @@ -708,7 +717,7 @@ isolate_dso_base: 7000000000 await posthogFlutterIO.captureAi(eventName: r'$ai_generation'), isNull, ); - expect(log.where((c) => c.method == 'captureAi'), isEmpty); + expect(log.where((c) => c.method == 'sendBuiltEvent'), isEmpty); }); }); @@ -745,9 +754,9 @@ isolate_dso_base: 7000000000 await posthogFlutterIO.capture(eventName: 'original_event'); - final captureCall = log.firstWhere((c) => c.method == 'capture'); + final captureCall = log.firstWhere((c) => c.method == 'sendBuiltEvent'); final args = Map.from(captureCall.arguments as Map); - expect(args['eventName'], 'modified_event'); + expect(args['event'], 'modified_event'); }); test('beforeSend can modify properties', () async { @@ -767,7 +776,7 @@ isolate_dso_base: 7000000000 properties: {'original': true}, ); - final captureCall = log.firstWhere((c) => c.method == 'capture'); + final captureCall = log.firstWhere((c) => c.method == 'sendBuiltEvent'); final args = Map.from(captureCall.arguments as Map); expect(args['properties'], {'modified': true}); }); @@ -789,9 +798,11 @@ isolate_dso_base: 7000000000 userProperties: {'name': 'Original Name'}, ); - final captureCall = log.firstWhere((c) => c.method == 'capture'); + final captureCall = log.firstWhere((c) => c.method == 'sendBuiltEvent'); final args = Map.from(captureCall.arguments as Map); - expect(args['userProperties'], {'name': 'Modified Name'}); + expect(args['properties'], { + r'$set': {'name': 'Modified Name'} + }); }); test('beforeSend can modify userPropertiesSetOnce', () async { @@ -811,10 +822,10 @@ isolate_dso_base: 7000000000 userPropertiesSetOnce: {'last_logged_in_at': '2024-01-01'}, ); - final captureCall = log.firstWhere((c) => c.method == 'capture'); + final captureCall = log.firstWhere((c) => c.method == 'sendBuiltEvent'); final args = Map.from(captureCall.arguments as Map); - expect(args['userPropertiesSetOnce'], { - 'last_logged_in_at': '2025-01-01', + expect(args['properties'], { + r'$set_once': {'last_logged_in_at': '2025-01-01'}, }); }); @@ -825,7 +836,7 @@ isolate_dso_base: 7000000000 await posthogFlutterIO.capture(eventName: 'dropped_event'); - final captureCalls = log.where((c) => c.method == 'capture'); + final captureCalls = log.where((c) => c.method == 'sendBuiltEvent'); expect(captureCalls, isEmpty); }); @@ -844,12 +855,13 @@ isolate_dso_base: 7000000000 await posthogFlutterIO.capture(eventName: 'drop me'); await posthogFlutterIO.capture(eventName: 'keep me'); - final captureCalls = log.where((c) => c.method == 'capture').toList(); + final captureCalls = + log.where((c) => c.method == 'sendBuiltEvent').toList(); expect(captureCalls.length, 1); final args = Map.from( captureCalls.first.arguments as Map, ); - expect(args['eventName'], 'keep me'); + expect(args['event'], 'keep me'); }); test('beforeSend exception drops event and stops the chain', () async { @@ -885,7 +897,7 @@ isolate_dso_base: 7000000000 ); expect(callOrder, ['transform', 'throw']); - expect(log, isEmpty); + expect(log.where((c) => c.method == 'sendBuiltEvent'), isEmpty); }); test('multiple beforeSend callbacks are applied in order', () async { @@ -919,9 +931,9 @@ isolate_dso_base: 7000000000 await posthogFlutterIO.capture(eventName: 'original'); - final captureCall = log.firstWhere((c) => c.method == 'capture'); + final captureCall = log.firstWhere((c) => c.method == 'sendBuiltEvent'); final args = Map.from(captureCall.arguments as Map); - expect(args['eventName'], 'original_first_second_third'); + expect(args['event'], 'original_first_second_third'); expect(callOrder, [1, 2, 3]); }); @@ -980,10 +992,12 @@ isolate_dso_base: 7000000000 properties: {'event_prop': 'value'}, ); - final captureCall = log.firstWhere((c) => c.method == 'capture'); + final captureCall = log.firstWhere((c) => c.method == 'sendBuiltEvent'); final args = Map.from(captureCall.arguments as Map); - expect(args['properties'], {'event_prop': 'value'}); - expect(args['userProperties'], {'developer_name': 'John'}); + expect(args['properties'], { + 'event_prop': 'value', + r'$set': {'developer_name': 'John'}, + }); }, ); @@ -1009,10 +1023,12 @@ isolate_dso_base: 7000000000 properties: {'event_prop': 'value'}, ); - final captureCall = log.firstWhere((c) => c.method == 'capture'); + final captureCall = log.firstWhere((c) => c.method == 'sendBuiltEvent'); final args = Map.from(captureCall.arguments as Map); - expect(args['properties'], {'event_prop': 'value'}); - expect(args['userPropertiesSetOnce'], {'first_seen': '2025-01-01'}); + expect(args['properties'], { + 'event_prop': 'value', + r'$set_once': {'first_seen': '2025-01-01'}, + }); }, ); @@ -1037,13 +1053,15 @@ isolate_dso_base: 7000000000 userProperties: {'from_direct': 'direct_value', 'shared': 'direct'}, ); - final captureCall = log.firstWhere((c) => c.method == 'capture'); + final captureCall = log.firstWhere((c) => c.method == 'sendBuiltEvent'); final args = Map.from(captureCall.arguments as Map); - expect(args['properties'], {'event_prop': 'value'}); - expect(args['userProperties'], { - 'from_legacy': 'legacy_value', - 'from_direct': 'direct_value', - 'shared': 'direct', + expect(args['properties'], { + 'event_prop': 'value', + r'$set': { + 'from_legacy': 'legacy_value', + 'from_direct': 'direct_value', + 'shared': 'direct', + }, }); }); @@ -1064,9 +1082,203 @@ isolate_dso_base: 7000000000 userProperties: {'name': 'John'}, ); - final captureCall = log.firstWhere((c) => c.method == 'capture'); + final captureCall = log.firstWhere((c) => c.method == 'sendBuiltEvent'); final args = Map.from(captureCall.arguments as Map); - expect(args.containsKey('userProperties'), isFalse); + expect(args['properties'], isNot(contains(r'$set'))); + }); + }); + + group('PosthogFlutterIO beforeSend on the native-built event', () { + Map argsOf(String method) => Map.from( + log.singleWhere((c) => c.method == method).arguments as Map, + ); + + Future setUpWith(BeforeSendCallback callback) => posthogFlutterIO + .setup(PostHogConfig('test_project_token', beforeSend: [callback])); + + test('without callbacks an event takes one native call', () async { + await posthogFlutterIO.setup(PostHogConfig('test_project_token')); + log.clear(); + + await posthogFlutterIO.capture(eventName: 'clicked'); + + expect(log.map((c) => c.method), ['capture']); + }); + + test('callbacks see what the native SDK added', () async { + TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger + .setMockMethodCallHandler(channel, (call) async { + log.add(call); + if (call.method != 'buildEvent') return null; + return { + ...nativeBuiltEvent(call.arguments as Map), + 'properties': { + r'$lib': 'posthog-flutter', + 'plan': 'pro', + r'$set': {'name': 'Ada'}, + }, + }; + }); + PostHogEvent? seen; + await setUpWith((event) => seen = event); + + await posthogFlutterIO.capture(eventName: 'clicked'); + + expect(seen!.uuid, 'built-uuid'); + expect(seen!.distinctId, 'user-1'); + expect(seen!.timestamp, DateTime.utc(2026)); + expect(seen!.properties, {r'$lib': 'posthog-flutter', 'plan': 'pro'}); + expect(seen!.userProperties, {'name': 'Ada'}); + }); + + test('callbacks can cast nested values from the native SDK', () async { + TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger + .setMockMethodCallHandler(channel, (call) async { + log.add(call); + if (call.method != 'buildEvent') return null; + return { + ...nativeBuiltEvent(call.arguments as Map), + 'properties': { + r'$exception_list': [ + { + 'type': 'StateError', + 'stacktrace': { + 'frames': [ + {'in_app': true}, + ], + }, + }, + ], + 'bytes': Int32List.fromList([1, 2]), + 'empty': [], + }, + }; + }); + await setUpWith((event) { + final list = + event.properties![r'$exception_list'] as List>; + final stack = list.single['stacktrace'] as Map; + final frames = stack['frames'] as List>; + frames.single['in_app'] = false; + return event; + }); + + await posthogFlutterIO.capture(eventName: 'failed'); + + final sent = log.singleWhere((c) => c.method == 'sendBuiltEvent'); + expect((sent.arguments as Map)['properties'], { + r'$exception_list': [ + { + 'type': 'StateError', + 'stacktrace': { + 'frames': [ + {'in_app': false}, + ], + }, + }, + ], + 'bytes': [1, 2], + 'empty': [], + }); + }); + + test('sends what the callbacks return with the built uuid', () async { + await setUpWith((event) => PostHogEvent( + event: 'renamed', + properties: {'a': 1}, + distinctId: 'user-2', + timestamp: DateTime.utc(2025), + )); + + await posthogFlutterIO.capture(eventName: 'clicked'); + + expect(argsOf('sendBuiltEvent'), { + 'event': 'renamed', + 'properties': {'a': 1}, + 'distinctId': 'user-2', + 'timestamp': DateTime.utc(2025).millisecondsSinceEpoch, + 'options': {}, + 'uuid': 'built-uuid', + 'ai': false, + }); + }); + + test('captureAi builds and sends on the AI lane', () async { + await setUpWith((event) => event); + + final uuid = + await posthogFlutterIO.captureAi(eventName: r'$ai_generation'); + + expect(uuid, 'built-uuid'); + expect(argsOf('buildEvent')['ai'], isTrue); + expect(argsOf('sendBuiltEvent')['ai'], isTrue); + }); + + test('screen builds a \$screen event with its name', () async { + PostHogEvent? seen; + await setUpWith((event) => seen = event); + + await posthogFlutterIO.screen(screenName: 'Home', properties: {'a': 1}); + + expect(argsOf('buildEvent'), { + 'eventName': r'$screen', + 'properties': {'a': 1, r'$screen_name': 'Home'}, + 'ai': false, + }); + expect(seen!.event, r'$screen'); + expect(seen!.properties, {'a': 1, r'$screen_name': 'Home'}); + }); + + test('capturing \$screen keeps capture semantics', () async { + PostHogEvent? seen; + await setUpWith((event) => seen = event); + + await posthogFlutterIO.capture( + eventName: r'$screen', + userProperties: {'plan': 'pro'}, + ); + + expect(argsOf('buildEvent')['eventName'], isNot(r'$screen')); + expect(argsOf('buildEvent')['eventName'], startsWith(r'$')); + expect(seen!.event, r'$screen'); + expect(seen!.userProperties, {'plan': 'pro'}); + expect(argsOf('sendBuiltEvent')['event'], r'$screen'); + }); + + test('captureException builds with its own timestamp', () async { + await setUpWith((event) => event); + + await posthogFlutterIO.captureException(error: StateError('boom')); + + expect(argsOf('buildEvent')['eventName'], r'$exception'); + expect(argsOf('buildEvent')['timestamp'], isA()); + }); + + test('a dropped event is discarded, not sent', () async { + await setUpWith((event) => null); + + await posthogFlutterIO.capture(eventName: 'clicked'); + + expect(argsOf('discardBuiltEvent'), {'uuid': 'built-uuid'}); + expect(log.where((c) => c.method == 'sendBuiltEvent'), isEmpty); + }); + + test('an event the native SDK skips never reaches the callbacks', () async { + TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger + .setMockMethodCallHandler(channel, (call) async { + log.add(call); + return null; + }); + var called = false; + await setUpWith((event) { + called = true; + return event; + }); + + await posthogFlutterIO.capture(eventName: 'clicked'); + + expect(called, isFalse); + expect(log.where((c) => c.method == 'sendBuiltEvent'), isEmpty); }); }); @@ -1169,10 +1381,213 @@ isolate_dso_base: 7000000000 await posthogFlutterIO.reset(); await Future.wait(sent); - expect(log.map((c) => c.method), - ['capture', 'screen', 'captureException', 'reset']); + expect(log.map((c) => c.method), [ + if (hooked) ...[ + for (var i = 0; i < 3; i++) ...['buildEvent', 'sendBuiltEvent'], + ] else ...[ + 'capture', + 'screen', + 'captureException' + ], + 'reset', + ]); }); } + + test('an event keeps the callbacks set when it was captured', () async { + await posthogFlutterIO.setup( + PostHogConfig('test_project_token', beforeSend: [(event) => null])); + log.clear(); + + final sent = posthogFlutterIO.capture(eventName: 'checkout'); + await posthogFlutterIO.setup(PostHogConfig('test_project_token')); + await sent; + + expect(log.map((c) => c.method), + ['buildEvent', 'discardBuiltEvent', 'setup']); + }); + + final lifecycleCalls = Function()>{ + 'disable': () => posthogFlutterIO.optOut(), + 'close': () => posthogFlutterIO.close(), + 'setup': () => + posthogFlutterIO.setup(PostHogConfig('test_project_token')), + }; + lifecycleCalls.forEach((method, call) { + test('$method waits for an event between its build and send', () async { + await posthogFlutterIO.setup(PostHogConfig('test_project_token', + beforeSend: [(event) => event])); + log.clear(); + + final sent = posthogFlutterIO.capture(eventName: 'checkout'); + await call(); + await sent; + + expect( + log.map((c) => c.method), ['buildEvent', 'sendBuiltEvent', method]); + }); + }); + }); + + group('PosthogFlutterIO hook that renames an event', () { + final renames = Function(PosthogFlutterIO)>{ + 'screen': (io) => io.screen(screenName: 'Checkout'), + 'captureException': (io) => + io.captureException(error: StateError('boom')), + }; + + renames.forEach((name, send) { + test('$name runs the hook once and keeps its user properties', () async { + var runs = 0; + await posthogFlutterIO + .setup(PostHogConfig('test_project_token', beforeSend: [ + (event) { + runs++; + event.event = 'renamed'; + event.userProperties = {'source': 'hook'}; + return event; + }, + ])); + log.clear(); + + await send(posthogFlutterIO); + + expect(runs, 1); + expect(log.where((c) => c.method == 'buildEvent'), hasLength(1)); + final args = Map.from(log + .singleWhere((c) => c.method == 'sendBuiltEvent') + .arguments as Map); + expect(args['event'], 'renamed'); + expect((args['properties'] as Map)[r'$set'], {'source': 'hook'}); + }); + }); + }); + + group('PosthogFlutterIO hook that calls the SDK', () { + Future setUpWith( + PostHogEvent? Function(PostHogEvent event) hook, + ) async { + await posthogFlutterIO + .setup(PostHogConfig('test_project_token', beforeSend: [hook])); + log.clear(); + } + + test('can capture another event without running forever', () async { + final seen = []; + await setUpWith((event) { + seen.add(event.event); + if (event.event == 'outer') { + posthogFlutterIO.capture(eventName: 'inner'); + } + return event; + }); + + await posthogFlutterIO.capture(eventName: 'outer'); + await pumpEventQueue(); + + expect(seen, ['outer', 'inner']); + expect( + log + .where((c) => c.method == 'sendBuiltEvent') + .map((c) => (c.arguments as Map)['event']), + unorderedEquals(['inner', 'outer']), + ); + }); + + final calls = Function(PosthogFlutterIO)>{ + 'reset': (io) => io.reset(), + 'identify': (io) => io.identify(userId: 'user-1'), + 'optOut': (io) => io.optOut(), + 'close': (io) => io.close(), + 'getFeatureFlag': (io) => io.getFeatureFlag(key: 'flag'), + 'getDistinctId': (io) => io.getDistinctId(), + 'isOptOut': (io) => io.isOptOut(), + }; + + calls.forEach((name, call) { + test('$name inside the hook does not deadlock the event', () async { + TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger + .setMockMethodCallHandler(channel, (methodCall) async { + log.add(methodCall); + return switch (methodCall.method) { + 'distinctId' => 'user-1', + 'isOptOut' => false, + 'buildEvent' => nativeBuiltEvent(methodCall.arguments as Map), + 'sendBuiltEvent' => (methodCall.arguments as Map)['uuid'], + _ => null, + }; + }); + await setUpWith((event) { + call(posthogFlutterIO); + return event; + }); + + await posthogFlutterIO + .capture(eventName: 'checkout') + .timeout(const Duration(seconds: 2)); + await pumpEventQueue(); + + expect(log.map((c) => c.method), contains('sendBuiltEvent')); + }); + }); + + test('an error in unawaited work does not drop the event', () async { + final errors = []; + await runZonedGuarded(() async { + await setUpWith((event) { + Future.error(StateError('late failure')); + return event; + }); + await posthogFlutterIO.capture(eventName: 'checkout'); + await pumpEventQueue(); + }, (error, _) => errors.add(error)); + + expect(errors, hasLength(1)); + expect(log.map((c) => c.method), ['buildEvent', 'sendBuiltEvent']); + }); + + test('a change made after the hook returned is not sent', () async { + await setUpWith((event) { + Future.delayed(Duration.zero, () { + event.properties?['late'] = true; + }); + return event; + }); + + await posthogFlutterIO + .capture(eventName: 'checkout', properties: {'plan': 'pro'}); + await Future.delayed(const Duration(milliseconds: 10)); + + final args = + log.singleWhere((c) => c.method == 'sendBuiltEvent').arguments as Map; + expect(args['properties'], {'plan': 'pro'}); + }); + }); + + group('PosthogFlutterIO calls after a burst of events', () { + test('keep the order the app made them in', () async { + await posthogFlutterIO.setup( + PostHogConfig('test_project_token', beforeSend: [(event) => event])); + log.clear(); + + final sent = >[]; + final expected = []; + for (var i = 0; i < 1000; i++) { + sent.add(posthogFlutterIO.capture(eventName: 'event $i')); + expected.add('event $i'); + if (i % 100 == 99) { + sent.add(posthogFlutterIO.reset()); + expected.add('reset'); + } + } + await Future.wait(sent); + + expect( + log.where((c) => c.method != 'buildEvent').map((c) => + c.method == 'reset' ? 'reset' : (c.arguments as Map)['event']), + expected, + ); + }); }); group('PosthogFlutterIO addExceptionStep', () { @@ -1413,3 +1828,21 @@ isolate_dso_base: 7000000000 }); }); } + +/// What the native `buildEvent` handler returns for [args], without adding +/// SDK properties. +Map nativeBuiltEvent(Map args, {String uuid = 'built-uuid'}) { + return { + 'event': args['eventName'], + 'uuid': uuid, + 'distinctId': 'user-1', + 'timestamp': args['timestamp'] ?? 1767225600000, + 'properties': { + ...?(args['properties'] as Map?), + if (args['userProperties'] != null) r'$set': args['userProperties'], + if (args['userPropertiesSetOnce'] != null) + r'$set_once': args['userPropertiesSetOnce'], + }, + 'options': args['options'] ?? {}, + }; +} diff --git a/posthog_flutter/test/posthog_logs_test.dart b/posthog_flutter/test/posthog_logs_test.dart index 20c8e147..5a008f34 100644 --- a/posthog_flutter/test/posthog_logs_test.dart +++ b/posthog_flutter/test/posthog_logs_test.dart @@ -142,6 +142,39 @@ void main() { }); group('beforeSend hook', () { + test('runs before captureLog returns its first await', () async { + var ran = false; + final config = PostHogConfig('test_token'); + config.logsConfig.beforeSend = [ + (record) { + ran = true; + return record; + }, + ]; + await setupWith(config); + + final sent = Posthog().captureLog(body: 'hello'); + expect(ran, isTrue); + expect(fake.capturedLogs, hasLength(1)); + await sent; + }); + + test('a hook that logs does not run forever when it stops itself', + () async { + final config = PostHogConfig('test_token'); + config.logsConfig.beforeSend = [ + (record) { + if (record.body == 'outer') Posthog().captureLog(body: 'inner'); + return record; + }, + ]; + await setupWith(config); + + await Posthog().captureLog(body: 'outer'); + + expect(fake.capturedLogs.map((l) => l.body), ['inner', 'outer']); + }); + test('hook returning null drops the record', () async { final config = PostHogConfig('test_token'); config.logsConfig.beforeSend = [(record) => null]; diff --git a/posthog_flutter/test/snapshots/event_channel_shapes.json b/posthog_flutter/test/snapshots/event_channel_shapes.json index 2091d2e2..cac7582e 100644 --- a/posthog_flutter/test/snapshots/event_channel_shapes.json +++ b/posthog_flutter/test/snapshots/event_channel_shapes.json @@ -1,19 +1,39 @@ [ { - "method": "screen", + "method": "buildEvent", "arguments": { - "screenName": "Checkout", + "eventName": "$screen", "properties": { "cart_size": 3, "route": { "source": "email" }, + "$screen_name": "Checkout" + }, + "ai": false + } + }, + { + "method": "sendBuiltEvent", + "arguments": { + "event": "$screen", + "properties": { + "cart_size": 3, + "route": { + "source": "email" + }, + "$screen_name": "Checkout", "snapshot_before_send": "event" - } + }, + "distinctId": "snapshot-user", + "timestamp": 1709296200000, + "options": {}, + "uuid": "snapshot-uuid", + "ai": false } }, { - "method": "capture", + "method": "buildEvent", "arguments": { "eventName": "order completed", "properties": { @@ -26,8 +46,7 @@ } ], "placed_at": "2024-03-01 12:30:00.000Z", - "$screen_name": "Checkout", - "snapshot_before_send": "event" + "$screen_name": "Checkout" }, "userProperties": { "plan": "pro", @@ -37,7 +56,41 @@ "userPropertiesSetOnce": { "first_checkout_at": "2024-03-01", "signup_source": "invite" - } + }, + "ai": false + } + }, + { + "method": "sendBuiltEvent", + "arguments": { + "event": "order completed", + "properties": { + "order_id": "ord_123", + "total": 42.5, + "items": [ + { + "sku": "sku_1", + "quantity": 2 + } + ], + "placed_at": "2024-03-01 12:30:00.000Z", + "$screen_name": "Checkout", + "snapshot_before_send": "event", + "$set": { + "plan": "pro", + "legacy_only": true, + "email_verified": true + }, + "$set_once": { + "first_checkout_at": "2024-03-01", + "signup_source": "invite" + } + }, + "distinctId": "snapshot-user", + "timestamp": 1709296200000, + "options": {}, + "uuid": "snapshot-uuid", + "ai": false } }, { diff --git a/posthog_flutter/test/snapshots/special_event_channel_shapes.json b/posthog_flutter/test/snapshots/special_event_channel_shapes.json index 42be31cb..e695058e 100644 --- a/posthog_flutter/test/snapshots/special_event_channel_shapes.json +++ b/posthog_flutter/test/snapshots/special_event_channel_shapes.json @@ -15,9 +15,59 @@ } }, { - "method": "captureException", + "method": "buildEvent", "arguments": { + "eventName": "$exception", + "properties": { + "$exception_level": "error", + "$exception_list": [ + { + "type": "StateError", + "mechanism": { + "handled": true, + "synthetic": false, + "type": "generic" + }, + "value": "Bad state: checkout failed", + "stacktrace": { + "frames": [ + { + "platform": "dart", + "abs_path": "package:snapshot_app/main.dart", + "in_app": true, + "package": "snapshot_app", + "function": "main", + "filename": "main.dart", + "lineno": 10, + "colno": 3 + }, + { + "platform": "dart", + "abs_path": "package:snapshot_app/checkout.dart", + "in_app": true, + "package": "snapshot_app", + "function": "CheckoutService.submit", + "filename": "checkout.dart", + "lineno": 42, + "colno": 7 + } + ], + "type": "raw" + }, + "thread_id": "" + } + ], + "order_id": "ord_123", + "attempted_at": "2024-03-01 12:30:00.000Z" + }, "timestamp": "", + "ai": false + } + }, + { + "method": "sendBuiltEvent", + "arguments": { + "event": "$exception", "properties": { "$exception_level": "error", "$exception_list": [ @@ -60,13 +110,67 @@ "order_id": "ord_123", "attempted_at": "2024-03-01 12:30:00.000Z", "snapshot_before_send": "event" - } + }, + "distinctId": "snapshot-user", + "timestamp": 1709296200000, + "options": {}, + "uuid": "snapshot-uuid", + "ai": false } }, { - "method": "captureException", + "method": "buildEvent", "arguments": { + "eventName": "$exception", + "properties": { + "$exception_level": "error", + "$exception_list": [ + { + "type": "ArgumentError", + "mechanism": { + "handled": false, + "synthetic": false, + "type": "runZonedGuarded" + }, + "value": "Invalid argument(s): zoned checkout failure", + "stacktrace": { + "frames": [ + { + "platform": "dart", + "abs_path": "package:snapshot_app/main.dart", + "in_app": true, + "package": "snapshot_app", + "function": "main", + "filename": "main.dart", + "lineno": 12, + "colno": 3 + }, + { + "platform": "dart", + "abs_path": "package:snapshot_app/zone.dart", + "in_app": true, + "package": "snapshot_app", + "function": "CheckoutZone.run", + "filename": "zone.dart", + "lineno": 21, + "colno": 5 + } + ], + "type": "raw" + }, + "thread_id": "" + } + ], + "zone": "checkout" + }, "timestamp": "", + "ai": false + } + }, + { + "method": "sendBuiltEvent", + "arguments": { + "event": "$exception", "properties": { "$exception_level": "error", "$exception_list": [ @@ -108,7 +212,12 @@ ], "zone": "checkout", "snapshot_before_send": "event" - } + }, + "distinctId": "snapshot-user", + "timestamp": 1709296200000, + "options": {}, + "uuid": "snapshot-uuid", + "ai": false } }, { diff --git a/posthog_flutter/test/web_before_send_test.dart b/posthog_flutter/test/web_before_send_test.dart index ba633255..b1bc73cc 100644 --- a/posthog_flutter/test/web_before_send_test.dart +++ b/posthog_flutter/test/web_before_send_test.dart @@ -12,6 +12,9 @@ void main() { TestWidgetsFlutterBinding.ensureInitialized(); final captures = >[]; + late String distinctId; + late bool optedOut; + late String userState; setUp(() { captures.clear(); @@ -22,9 +25,21 @@ void main() { captures.add({ 'event': event.toDart, 'properties': properties?.dartify(), + 'options': options?.dartify(), }); }).toJS, ); + distinctId = 'first-user'; + fake.setProperty('get_distinct_id'.toJS, (() => distinctId.toJS).toJS); + optedOut = false; + userState = 'anonymous'; + fake.setProperty( + 'get_property'.toJS, + ((JSString name) => name.toDart == r'$user_state' ? userState.toJS : null) + .toJS, + ); + fake.setProperty( + 'has_opted_out_capturing'.toJS, (() => optedOut.toJS).toJS); fake.setProperty( 'captureException'.toJS, ((JSAny? error, JSAny? properties) { @@ -37,6 +52,172 @@ void main() { globalContext.setProperty('posthog'.toJS, fake); }); + group('a hook that changes the user', () { + final sends = Function(PosthogFlutterWeb)>{ + 'capture': (web) => web.capture(eventName: 'checkout'), + 'screen': (web) => web.screen(screenName: 'Cart'), + 'captureException': (web) => + web.captureException(error: StateError('boom')), + }; + + sends.forEach((name, send) { + test('keeps $name on the earlier user', () async { + final web = PosthogFlutterWeb(); + await web.setup(PostHogConfig('test_token', beforeSend: [ + (event) { + distinctId = 'next-user'; + return event; + }, + ])); + + await send(web); + + final properties = captures.single['properties'] as Map; + expect(properties['distinct_id'], 'first-user'); + }); + }); + + test('does not bring back the user who opted out', () async { + final web = PosthogFlutterWeb(); + await web.setup(PostHogConfig('test_token', beforeSend: [ + (event) { + optedOut = true; + distinctId = r'$posthog_cookieless'; + return event; + }, + ])); + + await web.capture(eventName: 'checkout'); + + expect(captures.single['properties'], isNot(contains('distinct_id'))); + }); + + test('does not send the cookieless id after opting in', () async { + distinctId = r'$posthog_cookieless'; + final web = PosthogFlutterWeb(); + await web.setup(PostHogConfig('test_token', beforeSend: [ + (event) { + distinctId = 'next-user'; + return event; + }, + ])); + + await web.capture(eventName: 'checkout'); + + expect(captures.single['properties'], isNot(contains('distinct_id'))); + }); + + test('leaves the user alone when the hook does not change it', () async { + final web = PosthogFlutterWeb(); + await web.setup(PostHogConfig('test_token', beforeSend: [(e) => e])); + + await web.capture(eventName: 'checkout'); + + expect(captures.single['properties'], isNot(contains('distinct_id'))); + }); + }); + + group('a hook that changes the user drops user properties', () { + final sends = Function(PosthogFlutterWeb)>{ + 'capture': (web) => web.capture( + eventName: 'checkout', + userProperties: {'email': 'a@example.com'}, + userPropertiesSetOnce: {'first': 'yes'}, + ), + 'screen': (web) => web.screen(screenName: 'Cart'), + 'captureException': (web) => + web.captureException(error: StateError('boom')), + }; + + PostHogConfig hooked(void Function() changeUser) => + PostHogConfig('test_token', beforeSend: [ + (event) { + changeUser(); + return event + ..userProperties = {'email': 'a@example.com'} + ..userPropertiesSetOnce = {'first': 'yes'}; + }, + ]); + + Map sentPersonProperties() { + final capture = captures.single; + final options = capture['options'] as Map? ?? const {}; + final properties = capture['properties'] as Map? ?? const {}; + return { + for (final key in [r'$set', r'$set_once']) + if (options[key] != null) key: options[key], + for (final key in [r'$set', r'$set_once']) + if (properties[key] != null) key: properties[key], + }; + } + + sends.forEach((name, send) { + test('on $name after reset() of an identified user', () async { + userState = 'identified'; + final web = PosthogFlutterWeb(); + await web.setup(hooked(() { + distinctId = 'next-user'; + userState = 'anonymous'; + })); + + await send(web); + + expect(sentPersonProperties(), isEmpty); + expect((captures.single['properties'] as Map)['distinct_id'], + 'first-user'); + }); + + test('on $name not after identify() of an anonymous user', () async { + final web = PosthogFlutterWeb(); + await web.setup(hooked(() { + distinctId = 'user-1'; + userState = 'identified'; + })); + + await send(web); + + expect(sentPersonProperties(), { + r'$set': {'email': 'a@example.com'}, + r'$set_once': {'first': 'yes'}, + }); + }); + }); + }); + + group('a hook that sets user properties without renaming', () { + PostHogConfig hooked() => PostHogConfig('test_token', beforeSend: [ + (event) { + event.userProperties = {'plan': 'pro'}; + event.userPropertiesSetOnce = {'first': 'yes'}; + return event; + }, + ]); + + test('keeps them on a screen', () async { + final web = PosthogFlutterWeb(); + await web.setup(hooked()); + + await web.screen(screenName: 'Cart'); + + expect(captures.single['event'], r'$screen'); + expect(captures.single['options'], { + r'$set': {'plan': 'pro'}, + r'$set_once': {'first': 'yes'}, + }); + }); + + test('keeps them on an exception', () async { + final web = PosthogFlutterWeb(); + await web.setup(hooked()); + + await web.captureException(error: StateError('boom')); + + final properties = captures.single['properties'] as Map; + expect(properties[r'$set'], {'plan': 'pro'}); + expect(properties[r'$set_once'], {'first': 'yes'}); + }); + }); + test('feature events carry the screen name beforeSend accepted', () async { final web = PosthogFlutterWeb(); await web.setup(PostHogConfig('test_token', beforeSend: [ @@ -113,6 +294,148 @@ void main() { expect(calls, ['getFeatureFlagResult', r'$feature_view', 'reset']); }); + for (final hooked in [false, true]) { + test( + 'feature events read the flag and reach posthog-js before a reset made ' + 'right after them (${hooked ? 'with' : 'without'} beforeSend)', + () async { + final calls = []; + var variant = 'for-the-old-user'; + final fake = globalContext.getProperty('posthog'.toJS); + fake.setProperty( + 'capture'.toJS, + ((JSString event, JSAny? properties, [JSAny? options]) { + final flagged = properties?.dartify() as Map?; + calls.add('${event.toDart}:${flagged?['feature_flag_variant']}'); + }).toJS, + ); + fake.setProperty( + 'getFeatureFlagResult'.toJS, + ((JSString key, [JSAny? options]) => { + 'key': key.toDart, + 'enabled': true, + 'variant': variant, + }.jsify()).toJS, + ); + fake.setProperty( + 'reset'.toJS, + (([JSAny? a]) { + calls.add('reset'); + variant = 'for-the-new-user'; + }).toJS, + ); + final web = PosthogFlutterWeb(); + await web.setup(PostHogConfig('test_token', + beforeSend: [if (hooked) (event) => event])); + + final sent = [ + web.captureFeatureView(flag: 'checkout'), + web.captureFeatureInteraction(flag: 'checkout'), + ]; + await web.reset(); + await Future.wait(sent); + + expect(calls, [ + r'$feature_view:for-the-old-user', + r'$feature_interaction:for-the-old-user', + 'reset', + ]); + }); + } + + group('a hook that renames an event', () { + final renames = Function(PosthogFlutterWeb)>{ + 'capture': (web) => web.capture(eventName: 'original'), + 'screen': (web) => web.screen(screenName: 'Checkout'), + 'captureException': (web) => + web.captureException(error: StateError('boom')), + }; + + renames.forEach((name, send) { + test('$name runs the hook once and keeps its user properties', () async { + var runs = 0; + final web = PosthogFlutterWeb(); + await web.setup(PostHogConfig('test_token', beforeSend: [ + (event) { + runs++; + event.event = 'renamed'; + event.userProperties = {'source': 'hook'}; + return event; + }, + ])); + + await send(web); + + expect(runs, 1); + expect(captures.single['event'], 'renamed'); + final options = captures.single['options'] as Map; + expect(options[r'$set'], {'source': 'hook'}); + }); + }); + }); + + group('a hook that calls the SDK', () { + test('can capture another event without running forever', () async { + final web = PosthogFlutterWeb(); + final seen = []; + await web.setup(PostHogConfig('test_token', beforeSend: [ + (event) { + seen.add(event.event); + if (event.event == 'outer') web.capture(eventName: 'inner'); + return event; + }, + ])); + + await web.capture(eventName: 'outer'); + + expect(seen, ['outer', 'inner']); + expect(captures.map((c) => c['event']), ['inner', 'outer']); + }); + + test('an unawaited getter inside the hook does not delay the event', + () async { + final calls = []; + final fake = globalContext.getProperty('posthog'.toJS); + fake.setProperty( + 'capture'.toJS, + ((JSString event, [JSAny? a, JSAny? b]) => calls.add(event.toDart)) + .toJS, + ); + fake.setProperty('reset'.toJS, (([JSAny? a]) => calls.add('reset')).toJS); + fake.setProperty('has_opted_out_capturing'.toJS, (() => false.toJS).toJS); + final web = PosthogFlutterWeb(); + await web.setup(PostHogConfig('test_token', beforeSend: [ + (event) { + web.isOptOut(); + return event; + }, + ])); + + final sent = web.capture(eventName: 'checkout'); + await web.reset(); + await sent; + + expect(calls, ['checkout', 'reset']); + }); + }); + + test('a change made after the hook returned is not sent', () async { + final web = PosthogFlutterWeb(); + await web.setup(PostHogConfig('test_token', beforeSend: [ + (event) { + Future.delayed(Duration.zero, () { + event.properties?['late'] = true; + }); + return event; + }, + ])); + + await web.capture(eventName: 'checkout', properties: {'plan': 'pro'}); + await Future.delayed(const Duration(milliseconds: 10)); + + expect((captures.single['properties'] as Map).containsKey('late'), isFalse); + }); + test('beforeSend null drops capture on web', () async { final web = PosthogFlutterWeb(); await web.setup( diff --git a/sdk_compliance_adapter/lib/adapter_server.dart b/sdk_compliance_adapter/lib/adapter_server.dart index 8e6f0c3f..986c272d 100644 --- a/sdk_compliance_adapter/lib/adapter_server.dart +++ b/sdk_compliance_adapter/lib/adapter_server.dart @@ -312,6 +312,7 @@ class _CaptureClient extends DesktopPostHog { required Map properties, Map? options, String? timestamp, + String? uuid, }) { final queued = super.captureStateless( distinctId, @@ -319,6 +320,7 @@ class _CaptureClient extends DesktopPostHog { properties: properties, options: options, timestamp: timestamp, + uuid: uuid, ); onCaptured?.call(); return queued; @@ -331,16 +333,18 @@ class _CaptureClient extends DesktopPostHog { required Map properties, Map? options, String? timestamp, + String? uuid, }) async { - final uuid = await super.captureAiStateless( + final captured = await super.captureAiStateless( distinctId, event, properties: properties, options: options, timestamp: timestamp, + uuid: uuid, ); - if (uuid != null) onCaptured?.call(); - return uuid; + if (captured != null) onCaptured?.call(); + return captured; } void _actAs(String distinctId) { @@ -362,6 +366,9 @@ class _CaptureClient extends DesktopPostHog { properties: prepared.properties, options: prepared.options, timestamp: timestamp, + uuid: prepared.uuid, + distinctId: prepared.distinctId, + requestsPersonProcessing: prepared.requestsPersonProcessing, ); } From d05722bc5f63c4d7e925db9ade080b7d96100939 Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Tue, 3 Nov 2026 18:35:29 -0500 Subject: [PATCH 24/28] fix: send events with a lone surrogate on Windows and Linux (#703) * fix: drop an event with a lone surrogate in its name or ids on Windows and Linux Capture v1 rejects the whole request for a lone UTF-16 surrogate in a top-level field, so one bad event lost its batch. Drop that event at enqueue, and replace lone surrogates in properties and options with U+FFFD. Claude-Session: https://claude.ai/code/session_019xLynws83apuXa9LfRy9Aq * fix: repair lone surrogates only in queued events, and keep dropped events from changing state register() and the flag property stores keep their values as given, so a registered id with a lone surrogate drops later events instead of being repaired, and unregister() still matches its key. A dropped event no longer updates person properties, and identify() ignores an id that isn't well-formed instead of saving it. Claude-Session: https://claude.ai/code/session_019xLynws83apuXa9LfRy9Aq * perf: repair lone surrogates in the background worker when the body is encoded The scan cost as much as jsonEncode on the UI isolate; in the worker it also covers property values sent as their toString(). Co-Authored-By: Claude Opus 5.5 * fix: ignore alias() and group() calls with a lone surrogate Repairing them would merge distinct aliases or groups into one. Co-Authored-By: Claude Opus 5.5 * docs: note in the changeset that identify, alias and group ignore a lone surrogate Co-Authored-By: Claude Opus 5.5 * fix: repair lone surrogates in event names and ids on Windows and Linux Send the event with U+FFFD instead of dropping it, as iOS, macOS and Android already do through the platform channel. identify(), alias() and group() store the repaired id instead of ignoring the call. Co-Authored-By: Claude Opus 5.5 * fix: repair lone surrogates in the /flags request on Windows and Linux Co-Authored-By: Claude Opus 5.5 * docs: cover the /flags request in the lone surrogate changeset entry Co-Authored-By: Claude Opus 5.5 * fix: keep ids as given and repair lone surrogates only on the wire identify(), alias() and group() stored a repaired id, while bootstrap, storage and resetGroupPropertiesForFlags() kept what the app passed, so the same id compared unequal: identify() after an identified bootstrap was treated as a user switch, and a group type's flag properties could not be reset. Ids now stay as the app passed them everywhere in the SDK, and the capture and /flags bodies are repaired when they are encoded. Co-Authored-By: Claude Opus 5.5 * perf: copy a request body only when it has a lone surrogate Encode first and repair only when the JSON has a \udXXX escape, so normal batches skip the extra copy. Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --- .changeset/v6-major-release.md | 1 + .../lib/src/core/posthog_core_stateless.dart | 2 +- .../lib/src/core/queue_worker.dart | 6 +- posthog_flutter/lib/src/core/utils/utils.dart | 43 +++++ .../test/core/capture_v1_test.dart | 163 ++++++++++++++++++ 5 files changed, 212 insertions(+), 3 deletions(-) diff --git a/.changeset/v6-major-release.md b/.changeset/v6-major-release.md index 62ea30bf..2cc1304f 100644 --- a/.changeset/v6-major-release.md +++ b/.changeset/v6-major-release.md @@ -44,6 +44,7 @@ - Skip `setup()` with one log line when `projectToken` is a personal API key (`phx_`), so the key is never sent - Stop printing capture's response body in flush error logs on Windows and Linux, and log how many repeated-uuid copies capture dropped - Drop a batch whose 2xx response has no readable per-event results on Windows and Linux instead of counting it as delivered, without resending it +- Replace lone UTF-16 surrogates with U+FFFD on Windows and Linux, in event names, ids, properties and options, and in the person and group properties sent for feature flags, so one such event no longer loses its whole batch; iOS, macOS and Android already send them that way - Log one line per batch that lost events on Windows and Linux, with the endpoint, count and reasons, also for a terminal status, and count a `limited` result as delivered - Back off failed sends on Windows and Linux from 1 second up to 30 seconds with ±25% jitter, instead of resending within the flush, treating `Retry-After` as a floor - Run queued event encoding, file work and request compression on a background isolate on Windows and Linux so they no longer drop frames diff --git a/posthog_flutter/lib/src/core/posthog_core_stateless.dart b/posthog_flutter/lib/src/core/posthog_core_stateless.dart index 6ef448bb..1c5b255b 100644 --- a/posthog_flutter/lib/src/core/posthog_core_stateless.dart +++ b/posthog_flutter/lib/src/core/posthog_core_stateless.dart @@ -476,7 +476,7 @@ abstract class PostHogCoreStateless { try { final response = await _fetchWithRetry( url, - jsonEncode(requestData), + jsonEncodeWellFormed(requestData), retryCount: _flagsRetryCount, retryDelay: _flagsRetryDelay, retryCheck: _isRetryableFlagsError, diff --git a/posthog_flutter/lib/src/core/queue_worker.dart b/posthog_flutter/lib/src/core/queue_worker.dart index b4ee23ba..e54a1646 100644 --- a/posthog_flutter/lib/src/core/queue_worker.dart +++ b/posthog_flutter/lib/src/core/queue_worker.dart @@ -8,6 +8,7 @@ import 'package:flutter/foundation.dart' show SynchronousFuture; import 'package:meta/meta.dart'; import 'logger.dart'; +import 'utils/utils.dart'; /// What [QueueWorker.write] did with an event: its serialized size in /// bytes, null when it cannot be encoded; whether it was over the size limit @@ -76,7 +77,8 @@ abstract class QueueWorker { /// could not be deleted. A file that is already gone is not an error. Future> delete(List paths); - /// Encodes [body] to JSON and compresses it with gzip when [gzip] is set. + /// Encodes [body] to JSON, with each lone UTF-16 surrogate replaced by + /// U+FFFD, and compresses it with gzip when [gzip] is set. Future encodeBody(Object? body, {required bool gzip}); /// Told when the jobs move back to the calling isolate. The worker is @@ -204,7 +206,7 @@ final class _EncodeBody extends _Job { @override EncodedBody run() { - final bytes = utf8.encode(jsonEncode(body)); + final bytes = utf8.encode(jsonEncodeWellFormed(body)); return ( payload: compress ? Uint8List.fromList(gzip.encode(bytes)) : bytes, length: bytes.length, diff --git a/posthog_flutter/lib/src/core/utils/utils.dart b/posthog_flutter/lib/src/core/utils/utils.dart index 473d5ab1..5f5c6aaf 100644 --- a/posthog_flutter/lib/src/core/utils/utils.dart +++ b/posthog_flutter/lib/src/core/utils/utils.dart @@ -95,6 +95,49 @@ Object? toJsonValue(Object? value, CoreLogger logger, return convert(value); } +/// [value] with each lone UTF-16 surrogate replaced by U+FFFD, or [value] +/// itself when it has none. `jsonEncode` writes a lone surrogate as a +/// `\ud800` escape, which capture v1 rejects in a top-level field. +String toWellFormed(String value) { + List? units; + for (var i = 0; i < value.length; i++) { + final unit = value.codeUnitAt(i); + if (unit & 0xF800 != 0xD800) continue; + if (unit < 0xDC00 && + i + 1 < value.length && + value.codeUnitAt(i + 1) & 0xFC00 == 0xDC00) { + i++; + continue; + } + (units ??= List.of(value.codeUnits))[i] = 0xFFFD; + } + return units == null ? value : String.fromCharCodes(units); +} + +final _loneSurrogateEscape = RegExp(r'\\ud[89a-f]'); + +/// `jsonEncode(value)` with each lone UTF-16 surrogate replaced by U+FFFD. +/// `jsonEncode` escapes only lone surrogates as `\udXXX`, so [value] is +/// copied and re-encoded only when the first encoding has such an escape. +String jsonEncodeWellFormed(Object? value) { + final json = jsonEncode(value); + return json.contains(_loneSurrogateEscape) + ? jsonEncode(_toWellFormedJson(value)) + : json; +} + +Object? _toWellFormedJson(Object? value) => switch (value) { + final String string => toWellFormed(string), + final Map map => { + for (final MapEntry(:key, :value) in map.entries) + toWellFormed('$key'): _toWellFormedJson(value), + }, + final List list => [ + for (final element in list) _toWellFormedJson(element) + ], + _ => value, + }; + /// [toJsonValue] for a map, typed as the JSON object it becomes. Map toJsonMap(Map map, CoreLogger logger) => toJsonValue(map, logger) as Map; diff --git a/posthog_flutter/test/core/capture_v1_test.dart b/posthog_flutter/test/core/capture_v1_test.dart index 9d978497..ecc97a4c 100644 --- a/posthog_flutter/test/core/capture_v1_test.dart +++ b/posthog_flutter/test/core/capture_v1_test.dart @@ -8,6 +8,7 @@ import 'package:posthog_flutter/src/core/file_storage.dart'; import 'package:posthog_flutter/src/core/logger.dart'; import 'package:posthog_flutter/src/core/posthog_core_stateless.dart'; import 'package:posthog_flutter/src/core/uuid.dart'; +import 'package:posthog_flutter/src/posthog_config.dart'; import 'package:posthog_flutter/src/posthog_flutter_version.dart'; import '../posthog_api_fake.dart'; @@ -95,6 +96,163 @@ void main() { }); }); + group('Lone surrogates', () { + test('in a name or id become U+FFFD and the event is sent', () async { + final server = await LocalPostHogServer.start(); + final client = testClient(server); + + client.capture('cut\uD83D'); + client.capture('session', properties: {r'$session_id': 's\uDE00'}); + client.capture('window', properties: {r'$window_id': '\uD800w'}); + client.capture('kept', properties: {'emoji': '\u{1F600}'}); + client.identify('user\uDC00'); + client.capture('after identify'); + await client.flush(); + + final events = server.events; + expect(events.map((event) => event['event']), [ + 'cut�', + 'session', + 'window', + 'kept', + r'$identify', + 'after identify' + ]); + expect(events[1]['session_id'], 's�'); + expect(events[2]['window_id'], '�w'); + expect(events.last['distinct_id'], 'user�'); + expect(client.getDistinctId(), 'user\uDC00'); + }); + + test('in a stored distinct id survive a restart unchanged', () async { + final server = await LocalPostHogServer.start(); + final dir = tempDirectory(); + final earlier = testClient(server, storage: FileStorage(dir.path)); + earlier.identify('user\uD800'); + earlier.close(); + + final client = testClient(server, storage: FileStorage(dir.path)); + + expect(client.getDistinctId(), 'user\uD800'); + }); + + test('in an identified bootstrap id still match identify', () async { + final server = await LocalPostHogServer.start(); + final client = testClient(server, + config: testConfig( + bootstrap: const PostHogBootstrapConfig( + distinctId: 'user\uD800', isIdentifiedId: true))); + + client.identify('user\uD800', userProperties: {'plan': 'pro'}); + await client.flush(); + + final set = server.events.single; + expect(set['event'], r'$set'); + expect(set['distinct_id'], 'user�'); + }); + + test('in a group type leave its flag properties resettable', () async { + final server = await LocalPostHogServer.start(); + final client = testClient(server); + + client.group('company\uD800', 'acme', groupProperties: {'size': 1}); + client.resetGroupPropertiesForFlags(groupType: 'company\uD800'); + await client.reloadFeatureFlagsAsync(); + + final body = server.flagsRequests.last.body; + expect(body['groups'], {'company�': 'acme'}); + expect(body['group_properties'] ?? const {}, isEmpty); + }); + + test('in properties and options become U+FFFD, keys included', () async { + final server = await LocalPostHogServer.start(); + final client = testClient(server); + + client.capture('e', properties: { + 'cut\uD83D': [ + 'a\uDE00', + {'k\uDC00': 'v\uD800'}, + ], + 'emoji': '\u{1F600}', + 'escape text': r'\ud800', + 'unencodable': _LoneSurrogateToString(), + }, options: { + 'product_tour_id': 't\uD800', + }); + await client.flush(); + + final event = server.events.single; + expect( + event['properties'], + containsPair('cut�', [ + 'a�', + {'k�': 'v�'}, + ])); + expect(event['properties'], containsPair('emoji', '\u{1F600}')); + expect(event['properties'], containsPair('escape text', r'\ud800')); + expect(event['properties'], containsPair('unencodable', 'o�')); + expect(event['options'], containsPair('product_tour_id', 't�')); + }); + + test('in an alias or group become U+FFFD', () async { + final server = await LocalPostHogServer.start(); + final client = testClient(server); + + client.alias('user\uD800'); + client.group('company\uD800', 'acme\uDC00'); + client.capture('e'); + await client.flush(); + + final events = server.events; + expect(events.first['properties'], containsPair('alias', 'user�')); + expect(events.last['properties'], + containsPair(r'$groups', {'company�': 'acme�'})); + }); + + test('in a registered key leave it removable by unregister', () async { + final server = await LocalPostHogServer.start(); + final client = testClient(server); + + client.register({'k\uD800': 1}); + client.unregister('k\uD800'); + client.capture('e'); + await client.flush(); + + expect(server.events.single['properties'], isNot(contains('k�'))); + }); + + test('in an AI event name become U+FFFD', () async { + final server = await LocalPostHogServer.start(); + final client = testClient(server); + + final prepared = client.prepareEvent('\$ai_cut\uD83D')!; + final uuid = await client.captureAiPrepared('\$ai_cut\uD83D', prepared); + await client.flush(); + + expect(uuid, isNotNull); + expect(server.aiEvents.single['event'], '\$ai_cut�'); + }); + + test('in the /flags request become U+FFFD', () async { + final server = await LocalPostHogServer.start(); + final client = testClient(server); + + client.identify('user\uD800'); + client.setPersonPropertiesForFlags({'plan\uD800': 'pro\uDC00'}); + client.setGroupPropertiesForFlags({ + 'company': {'name': 'acme\uD83D'}, + }); + await client.reloadFeatureFlagsAsync(); + + final body = server.flagsRequests.last.body; + expect(body['distinct_id'], 'user�'); + expect(body['person_properties'], containsPair('plan�', 'pro�')); + expect(body['group_properties'], { + 'company': {'name': 'acme�'}, + }); + }); + }); + group('captureV1Event', () { final logger = CoreLogger((_) {}); @@ -602,3 +760,8 @@ void main() { } const _ms = Duration(milliseconds: 1); + +class _LoneSurrogateToString { + @override + String toString() => 'o\uD800'; +} From fe95d8bc0d9d887bb34d51023d3462331c8ed0b5 Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Tue, 3 Nov 2026 18:38:22 -0500 Subject: [PATCH 25/28] docs: link the capture v1 upgrade guide and cover capture v1 on every platform (#701) * docs: link the capture v1 SDK upgrade guide Co-Authored-By: Claude Opus 5.5 * docs: cover capture v1 on Windows and Linux and align the 6.0 guide with the backend SDK guides Claude-Session: https://claude.ai/code/session_019xLynws83apuXa9LfRy9Aq * docs: lone surrogates on Windows and Linux (#703) Claude-Session: https://claude.ai/code/session_019xLynws83apuXa9LfRy9Aq * docs: identify ignores a distinct ID with a lone surrogate (#703) Claude-Session: https://claude.ai/code/session_019xLynws83apuXa9LfRy9Aq * docs: complete the platform interface changes and the upgrade checklist Co-Authored-By: Claude Opus 5.5 * docs: document the final 6.0 state in the guide and one grouped changeset Folds in the MIGRATION.md and changeset text of #682, #698, #703, #670, #695 and #699 so landing this PR last is "take this side". Co-Authored-By: Claude Opus 5.5 * docs: describe lone surrogates as repaired on Windows and Linux Co-Authored-By: Claude Opus 5.5 * docs: cover the /flags request in the lone surrogate changeset entry Co-Authored-By: Claude Opus 5.5 * docs: note the /flags request in the lone surrogate guide line Co-Authored-By: Claude Opus 5.5 * docs: say the SDK keeps lone-surrogate ids as passed and repairs what it sends Co-Authored-By: Claude Opus 5.5 * docs: drop the confirmed capture v1 default TODOs from the guide Co-Authored-By: Claude Opus 5.5 * docs: say $locale follows a per-app language picked in macOS Settings too Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --- .changeset/v6-major-release.md | 57 +++++----- posthog_flutter/MIGRATION.md | 191 ++++++++++++++++++++++++++++++--- 2 files changed, 203 insertions(+), 45 deletions(-) diff --git a/.changeset/v6-major-release.md b/.changeset/v6-major-release.md index 2cc1304f..b7e7ec39 100644 --- a/.changeset/v6-major-release.md +++ b/.changeset/v6-major-release.md @@ -4,54 +4,53 @@ - **Breaking:** bump the minimum iOS deployment target from 13.0 to 15.0 and macOS from 10.15 to 11.0 — see the [migration guide](https://github.com/PostHog/posthog-flutter/blob/main/posthog_flutter/MIGRATION.md) - **Breaking:** remove CocoaPods support on iOS and macOS — install through Swift Package Manager, which needs Flutter 3.41 or later and doesn't support add-to-app modules yet -- **Breaking:** change `getFeatureFlagResult()` to follow `PostHogConfig.sendFeatureFlagEvent` on iOS, macOS, Android, Windows and Linux when `sendFeatureFlagEvent` is omitted — pass `sendFeatureFlagEvent: true` to keep capturing `$feature_flag_called` -- **Breaking:** rename `getFeatureFlagResult(sendEvent:)` to `getFeatureFlagResult(sendFeatureFlagEvent:)` +- **Breaking:** adopt `posthog-ios` 4.x, which requires Xcode 26 +- **Breaking:** adopt `posthog-android` 4.x - **Breaking:** remove `PostHogConfig.apiKey` and the `com.posthog.posthog.API_KEY` manifest and Info.plist key — use `projectToken` and `com.posthog.posthog.PROJECT_TOKEN` -- **Breaking:** remove `Posthog().enable()` and `Posthog().disable()` — use `optIn()` and `optOut()` +- **Breaking:** remove `Posthog().enable()` and `Posthog().disable()`, and rename `enable()` and `disable()` to `optIn()` and `optOut()` on `PosthogFlutterPlatformInterface`, `PosthogFlutterIO` and `PosthogFlutterWeb` — use `optIn()` and `optOut()` - **Breaking:** remove `PostHogConfig.sendFeatureFlagEvents` — use `sendFeatureFlagEvent` - **Breaking:** remove `Posthog().getFeatureFlagPayload()` — use `getFeatureFlagResult(key, sendFeatureFlagEvent: false)` and read `payload` - **Breaking:** remove the `PostHogSessionReplayConfig.debouncerDelay` setter — use `throttleDelay` - **Breaking:** remove `PostHogDataMode.cellular` — use `PostHogDataMode.any` -- **Breaking:** make `beforeSend` and `logsConfig.beforeSend` callbacks synchronous — load what they need ahead of time instead of using `await` -- Keep a `reset()`, `identify()` or `optOut()` made right after an un-awaited `capture()`, `screen()`, `captureException()`, `captureFeatureView()` or `captureFeatureInteraction()` from applying to that event first, and stop dropping that event on Windows and Linux -- Run a `beforeSend` callback that renames a screen or exception event once, and keep its `userProperties` -- Keep `userProperties` and `userPropertiesSetOnce` that a `beforeSend` callback sets on a screen or exception event on web -- Send an event as its original user when a `beforeSend` callback calls `reset()` or `identify()` on Windows and Linux, instead of dropping it, and on web, instead of sending it as the new user - **Breaking:** remove `toMap()` from the config classes and `PostHogFeatureFlagResult.fromMap()` from the public API -- **Breaking:** rename `enable()` and `disable()` to `optIn()` and `optOut()` on `PosthogFlutterPlatformInterface`, `PosthogFlutterIO` and `PosthogFlutterWeb` -- **Breaking:** adopt `posthog-ios` 4.x, which requires Xcode 26 -- **Breaking:** adopt `posthog-android` 4.x -- **Breaking:** remove `PostHogConfig.onFeatureFlags` — call `Posthog().onFeatureFlags((loaded) { ... })` before `setup()` instead, which also covers the first load -- **Breaking:** return the reloaded flags from `reloadFeatureFlags()` as a `Future` -- **Breaking:** return `null` instead of the raw string for a malformed, empty or whitespace-only `getFeatureFlagResult()` payload on iOS, macOS and Android -- **Breaking:** keep string payloads passed to `PostHogBootstrapConfig.featureFlagPayloads`, such as `"123"`, as strings on iOS and macOS instead of decoding them to numbers or booleans -- **Breaking:** stop sending the legacy `version` and `build` properties on `Application Installed`, `Application Updated` and `Application Opened` on iOS and macOS — use `$app_version` and `$app_build` - **Breaking:** send events to capture v1 (`/i/v1/analytics/events`) instead of `/batch/` on iOS, macOS, Android, Windows and Linux — update your reverse proxy first, see the [iOS](https://github.com/PostHog/posthog-ios/blob/main/MIGRATION.md#hosts-without-capture-v1) and [Android](https://github.com/PostHog/posthog-android/blob/main/docs/migration-3.x-to-4.0.md#hosts-without-capture-v1) migration guides -- **Breaking:** retry a 404 on Windows and Linux so events stay queued, printing one warning, also without `debug`, until a reverse proxy or self-hosted instance serves the new path - **Breaking:** drop the batch on a redirect on Windows and Linux, following only same-origin 307 and 308 redirects, and cap a `Retry-After` wait at 30 seconds - **Breaking:** write events to disk only when the returned future completes on Windows and Linux, so an unawaited call can be lost on a crash or `exit()` — await the call or `Posthog().close()` before `exit()` - **Breaking:** apply SDK properties, then registered properties, then event properties on Windows and Linux, so your value wins for that event, and run `beforeSend` after that merge - **Breaking:** always set `$lib` and `$lib_version` from the `PostHog-Sdk-Info` header on Windows and Linux, ignoring changes made in `beforeSend` - **Breaking:** send person processing as the `process_person_profile: false` option on Windows and Linux, only while it's off, instead of a `$process_person_profile` property on every event +- **Breaking:** make `beforeSend` and `logsConfig.beforeSend` callbacks synchronous — load what they need ahead of time instead of using `await` - **Breaking:** pass `beforeSend` callbacks the event the native SDK built on iOS, macOS and Android, with its system and registered properties, and make their changes final - **Breaking:** decide person processing before `beforeSend` runs on iOS, macOS, Android, Windows and Linux — a callback that removes `$set` no longer prevents a person profile, and a callback that adds `$set` to an anonymous event must also set the `process_person_profile: true` option +- **Breaking:** remove `PostHogConfig.onFeatureFlags` — call `Posthog().onFeatureFlags((loaded) { ... })` before `setup()` instead, which also covers the first load and returns a `PostHogFeatureFlagsSubscription` you can `unsubscribe()` +- **Breaking:** return the reloaded flags from `reloadFeatureFlags()` as a `Future` +- **Breaking:** rename `getFeatureFlagResult(sendEvent:)` to `getFeatureFlagResult(sendFeatureFlagEvent:)` +- **Breaking:** change `getFeatureFlagResult()` to follow `PostHogConfig.sendFeatureFlagEvent` on iOS, macOS, Android, Windows and Linux when `sendFeatureFlagEvent` is omitted — pass `sendFeatureFlagEvent: true` to keep capturing `$feature_flag_called` +- **Breaking:** return `null` instead of the raw string for a malformed, empty or whitespace-only `getFeatureFlagResult()` payload on iOS, macOS and Android +- **Breaking:** keep string payloads passed to `PostHogBootstrapConfig.featureFlagPayloads`, such as `"123"`, as strings on iOS and macOS instead of decoding them to numbers or booleans +- **Breaking:** change `$locale` to the device's language with its region, such as `de-CH` instead of `de`, on iOS, macOS, Windows and Linux, follow a language picked for the app in Settings on iOS and macOS, and stop it following a per-app language on Android — update filters that match it +- **Breaking:** stop sending the legacy `version` and `build` properties on `Application Installed`, `Application Updated` and `Application Opened` on iOS and macOS — use `$app_version` and `$app_build` - Add an `options` parameter to `capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group` and `captureException`, and `PostHogEvent.options` for `beforeSend` callbacks +- Add `PostHogEvent.uuid`, `distinctId` and `timestamp`, set before `beforeSend` runs on every platform except web — a callback can change the distinct ID and timestamp, and the event keeps its uuid +- Add `PosthogFlutterPlugin.addBeforeSend` in Swift and Kotlin to filter or edit events the native SDK captures itself, such as crashes, app lifecycle and `$feature_flag_called` events - Add `captureAi` for AI observability events, a no-op that returns `null` on web -- Add `Posthog().onFeatureFlags()` to get notified after every feature flags load, returning a `PostHogFeatureFlagsSubscription` you can `unsubscribe()` -- Skip SDK calls with a warning instead of throwing when they run before the Flutter binding is initialized on iOS, macOS and Android - Add `PostHogConfig.captureAiCompression`, `captureAiMaxQueueSize`, `captureAiTimeout` and `captureAiMaxEventBytes` -- Apply a `$process_person_profile` property or `process_person_profile` option passed with an event to that event on Windows and Linux +- Add the `$app_language` property, reported by `PosthogObserver` from the locale `MaterialApp` resolved, and `setAppLanguage()` to set it yourself +- Add a `defaultValue` option to `isFeatureEnabled()`, returned when the flag has no value +- Declare Android `minSdkVersion` 23 to match `posthog-android` - Skip `setup()` with one log line when `projectToken` is a personal API key (`phx_`), so the key is never sent -- Stop printing capture's response body in flush error logs on Windows and Linux, and log how many repeated-uuid copies capture dropped -- Drop a batch whose 2xx response has no readable per-event results on Windows and Linux instead of counting it as delivered, without resending it +- Skip SDK calls with a warning instead of throwing when they run before the Flutter binding is initialized on iOS, macOS and Android +- Keep a `reset()`, `identify()` or `optOut()` made right after an un-awaited `capture()`, `screen()`, `captureException()`, `captureFeatureView()` or `captureFeatureInteraction()` from applying to that event first, and stop dropping that event on Windows and Linux +- Run a `beforeSend` callback that renames a screen or exception event once, and keep its `userProperties` +- Keep `userProperties` and `userPropertiesSetOnce` that a `beforeSend` callback sets on a screen or exception event on web +- Send an event as its original user when a `beforeSend` callback calls `reset()` or `identify()` on Windows and Linux, instead of dropping it, and on web, instead of sending it as the new user +- Attach `$exception_steps` before `beforeSend` runs on Windows and Linux so callbacks can read or remove them — steps recorded while a callback runs, or an event a callback renames to `$exception`, no longer get them +- Retry a 404 on Windows and Linux so events stay queued, printing one warning, also without `debug`, until a reverse proxy or self-hosted instance serves the new path +- Apply a `$process_person_profile` property or `process_person_profile` option passed with an event to that event on Windows and Linux - Replace lone UTF-16 surrogates with U+FFFD on Windows and Linux, in event names, ids, properties and options, and in the person and group properties sent for feature flags, so one such event no longer loses its whole batch; iOS, macOS and Android already send them that way -- Log one line per batch that lost events on Windows and Linux, with the endpoint, count and reasons, also for a terminal status, and count a `limited` result as delivered - Back off failed sends on Windows and Linux from 1 second up to 30 seconds with ±25% jitter, instead of resending within the flush, treating `Retry-After` as a floor +- Drop a batch whose 2xx response has no readable per-event results on Windows and Linux instead of counting it as delivered, without resending it +- Log one line per batch that lost events on Windows and Linux, with the endpoint, count and reasons, also for a terminal status, and count a `limited` result as delivered +- Stop printing capture's response body in flush error logs on Windows and Linux, and log how many repeated-uuid copies capture dropped - Run queued event encoding, file work and request compression on a background isolate on Windows and Linux so they no longer drop frames - Limit AI events waiting to be written on Windows and Linux to about 50 MiB in memory, dropping the oldest first and completing `captureAi` with `null` for them -- Take an event's timestamp before the `beforeSend` callbacks run on Windows and Linux -- Add `PostHogEvent.uuid`, `distinctId` and `timestamp`, set on every platform except web — a callback can change the distinct ID and timestamp, and the event keeps its uuid -- Attach `$exception_steps` before `beforeSend` runs on Windows and Linux so callbacks can read or remove them — steps recorded while a callback runs, or an event a callback renames to `$exception`, no longer get them -- Add `PosthogFlutterPlugin.addBeforeSend` in Swift and Kotlin to filter or edit events the native SDK captures itself, such as crashes, app lifecycle and `$feature_flag_called` events -- Declare Android `minSdkVersion` 23 to match `posthog-android` -- Add a `defaultValue` option to `isFeatureEnabled()`, returned when the flag has no value diff --git a/posthog_flutter/MIGRATION.md b/posthog_flutter/MIGRATION.md index 7e40a1ba..38141fbf 100644 --- a/posthog_flutter/MIGRATION.md +++ b/posthog_flutter/MIGRATION.md @@ -56,7 +56,7 @@ If every plugin in your app supports Swift Package Manager, you can remove Cocoa | | 5.x | 6.0 | | --- | --- | --- | | `posthog-ios` | `>= 3.92.3, < 4.0.0` | `>= 4.0.0, < 5.0.0` | -| `posthog-android` | `[3.72.9, 4.0.0)` | `[4.0.0, 5.0.0)` | +| `posthog-android` | `[3.75.0, 4.0.0)` | `[4.0.0, 5.0.0)` | | Xcode | Not set by the plugin | 26 or later | Don't add these native SDKs to your app separately at a different major version. @@ -202,6 +202,11 @@ These affect only code that calls, extends or fakes `PosthogFlutterPlatformInter - `enable()` and `disable()` are now `optIn()` and `optOut()`. - `getFeatureFlagPayload()` is removed. - `getFeatureFlagResult({required String key, bool sendEvent = true})` is now `getFeatureFlagResult({required String key, bool? sendFeatureFlagEvent})`. +- `capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group` and `captureException` take an `options` map. +- `captureAi()` is new. The base class throws `UnimplementedError` unless you override it. +- `isFeatureEnabled()` takes `defaultValue`. +- `reloadFeatureFlags()` returns a `Future`. +- `setAppLanguage(String? language)` is new. The base class does nothing unless you override it. ```dart // Before @@ -241,16 +246,50 @@ await Posthog().setup(config); ### Events go to capture v1 -**This is a silent change if you use a reverse proxy or self-host.** On iOS, macOS, Android, Windows and Linux, events go to `/i/v1/analytics/events` instead of `/batch/`, and `captureAi` events go to `/i/v1/ai/events`. Web keeps using posthog-js and its current endpoints. PostHog Cloud and the managed reverse proxy already serve the new paths. +**This is a silent change if you use a reverse proxy or self-host.** On iOS, macOS, Android, Windows and Linux, events go to `/i/v1/analytics/events` instead of `/batch/`, and `captureAi` events go to `/i/v1/ai/events`. PostHog Cloud and the managed reverse proxy already serve the new paths. Most apps upgrade without code changes, and nothing here produces a compile error. + +| Platform | Sent by | 6.0 | +| --- | --- | --- | +| iOS and macOS | posthog-ios 4.x | capture v1 | +| Android | posthog-android 4.x | capture v1 | +| Windows and Linux | posthog_flutter's own Dart client | capture v1 | +| Web | the posthog-js your app loads | unchanged | + +Web doesn't move to capture v1 in this release. It keeps posthog-js and its current endpoints. On web, `options` are sent as the legacy option properties, and `captureAi` sends nothing. + +For the changes every capture v1 SDK shares, such as event options, limits and per-event results, see [Upgrading to capture v1 SDKs](https://posthog.com/docs/libraries/capture-v1). On iOS, macOS and Android, capture v1 comes from the native SDKs, so the Capture v1 sections of the [iOS](https://github.com/PostHog/posthog-ios/blob/main/MIGRATION.md#capture-v1) and [Android](https://github.com/PostHog/posthog-android/blob/main/docs/migration-3.x-to-4.0.md#endpoints) guides apply there too. Windows and Linux are covered [below](#capture-v1-on-windows-and-linux). + + + +#### Checklist + +You need to change code if your app does any of these: + +- sends events to a self-hosted PostHog or a reverse proxy that doesn't serve `/i/v1/analytics/events` and `/i/v1/ai/events` +- identifies users with a distinct ID over 200 UTF-8 bytes, such as a JWT +- captures events whose name is over 200 UTF-8 bytes +- sets `projectToken` to a personal API key (`phx_...`) +- sets `$lib` or `$lib_version` and expects PostHog to store that value +- reads `$session_id` or `$window_id` from the raw request body, for example in a proxy +- relies on a `Retry-After` longer than 30 seconds +- on Windows or Linux, registers or passes a property with the same key as one the SDK sets, such as `$os` or `$is_identified`, and expects the SDK's value to win +- on Windows or Linux, returns a `PostHogEvent` from `beforeSend` without the event's `options` +- on Windows or Linux, alerts on the SDK's debug log lines +- on Windows or Linux, calls `exit()` without awaiting the calls before it or `Posthog().close()` + +#### Reverse proxies and self-hosting Before you upgrade, make your own proxy: - forward `/i/v1/analytics/events` and `/i/v1/ai/events` -- pass `Authorization` (the project token, sent as `Bearer `), every `PostHog-*` header, `Content-Type`, `Content-Encoding` and `User-Agent` through unchanged +- pass `Authorization` (the project token, sent as `Bearer `), every `PostHog-*` header, `Content-Type`, `Content-Encoding` and `User-Agent` through unchanged. PostHog answers `401` without `Authorization` and `400` without the others, and the batch is dropped. - if your proxy strips other credentials, keep `Authorization` values that start with `Bearer phc_`, `Bearer phs_` or `Bearer phx_`, plus the exact `Bearer ` of an older key without a prefix -- accept request bodies up to 20 MB +- accept request bodies up to 20 MB. AI requests are often larger than 1 MB, the default limit in nginx and ingress-nginx. +- pass PostHog's response body through unchanged, because a 2xx whose body isn't PostHog's `{"results": {...}}` drops the events instead of retrying them -If you ignore this on Windows and Linux, a 404 is retried, events stay queued, and the SDK prints one warning, also without `debug`. See the [iOS](https://github.com/PostHog/posthog-ios/blob/main/MIGRATION.md#hosts-without-capture-v1) and [Android](https://github.com/PostHog/posthog-android/blob/main/docs/migration-3.x-to-4.0.md#hosts-without-capture-v1) guides for those platforms. +PostHog's managed reverse proxy already does this. See the [proxy guides](https://posthog.com/docs/advanced/proxy). + +The SDK doesn't fall back to `/batch/`. On Windows and Linux, a 404 is retried, events stay queued until the route is served, and the SDK prints one warning, also without `debug`. Other statuses that aren't retried, such as 401, 403 or 405, drop the batch. See the [iOS](https://github.com/PostHog/posthog-ios/blob/main/MIGRATION.md#hosts-without-capture-v1) and [Android](https://github.com/PostHog/posthog-android/blob/main/docs/migration-3.x-to-4.0.md#hosts-without-capture-v1) guides for those platforms. ### Feature flag payloads @@ -260,7 +299,7 @@ On iOS and macOS, string values in `PostHogBootstrapConfig.featureFlagPayloads`, ### `beforeSend` on iOS, macOS and Android -**This is a silent change.** Callbacks now get the event the native SDK built, including its system properties, such as `$device_type` and `$session_id`, and registered properties. Their changes are final. In 5.x they saw only the properties you passed, so a callback that loops over or strips every property now also touches the SDK's. `PostHogEvent` also has `uuid`, `distinctId` and `timestamp`, set on every platform except web. +**This is a silent change.** Callbacks now get the event the native SDK built, including its system properties, such as `$device_type` and `$session_id`, registered properties and options, such as the `process_person_profile: false` the SDK adds while person processing is off. Their changes are final. In 5.x they saw only the properties and options you passed, so a callback that loops over or strips every property now also touches the SDK's. `PostHogEvent` also has `uuid`, `distinctId` and `timestamp`, set on every platform except web. A callback can change the distinct ID and timestamp, and the event keeps its uuid. **Person processing is decided before the callbacks run.** In 5.x, a callback that removed `$set` prevented a person profile. Now the event is still person-processed, and so are later events. Return `null` to drop an event that must not create a profile. A callback that adds `$set` to an anonymous event must also set the `process_person_profile: true` option. @@ -272,6 +311,14 @@ Events the native SDK captures itself don't go through Dart callbacks. Use `Post `Application Installed`, `Application Updated` and `Application Opened` no longer include `version` and `build`. Update insights, cohorts and filters that use them to `$app_version` and `$app_build`. Android still sends them. +### `$locale` and `$app_language` + +`$locale` now means the device's language, with its region, on iOS, Android, macOS, Windows and Linux: `de-CH` instead of `de` on iOS, macOS, Windows and Linux. On Android it no longer follows a per-app language or `Locale.setDefault()`. On older Android versions, Hebrew, Indonesian and Yiddish values also change from legacy codes, such as `in-ID` to `id-ID`. If a user picks a language for your app in iOS or macOS Settings, the system reports that language as the first preferred language, so `$locale` follows it. + +Update cohorts, insights and actions that match `$locale`: a filter on `$locale = de` stops matching `de-CH`. To keep matching a language, use a regex such as `^de(-|$)`, because "contains" also matches `en-DE`. Events already stored keep the old values. Feature flags aren't affected: the SDK doesn't send `$locale` or `$app_language` with flag requests, so flags only see these if you set them as person properties yourself. + +The new `$app_language` property is the language your app shows. `PosthogObserver` reports the locale exactly as your `MaterialApp` resolved it every time a route changes. An app that doesn't declare `supportedLocales` reports `en-US`, and one declaring `Locale('en')` reports `en`, so use a regex such as `^en(-|$)` to match English. Native detection is off because Flutter apps translate in Dart. If you translate outside `Localizations`, don't use the observer, or want to send another value, call `Posthog().setAppLanguage('de')`. + ### Network reachability on iOS and macOS A path that needs user action, such as a VPN waiting for a password, counts as reachable, and queues pause while cellular data is off for the app. Events captured in the first 100 ms after setup may leave out `$network_wifi` and `$network_cellular`. Events still on disk from a `posthog-ios` 2.x SDK are deleted instead of sent. @@ -280,16 +327,121 @@ A path that needs user action, such as a VPN waiting for a password, counts as r A personal API key (`phx_...`) in `projectToken` now skips `setup()` with one log line, so the SDK doesn't start and the key is never sent. Use your project token (`phc_...`). -### Windows and Linux +### Capture v1 on Windows and Linux + +Windows and Linux send events through posthog_flutter's own Dart client, not a native SDK. This section covers what the native guides cover for the other platforms. + +#### Event validation + +Capture v1 checks each event on its own and drops only the invalid ones, so the rest of the batch is delivered. + +- The SDK drops an event with an empty event name before sending it, as in 5.x. With `debug` on, it logs the drop. +- PostHog drops an event whose name is over 200 UTF-8 bytes. Legacy capture had no limit on event name length. +- PostHog drops an event whose distinct ID is over 200 UTF-8 bytes. Legacy capture shortened the ID to 200 characters and kept the event. If you identify users with a long ID, such as a JWT or a long email address, shorten or hash it before you upgrade. Otherwise every event for that user is dropped. +- `identify` with an empty or whitespace-only distinct ID is ignored, as in 5.x. +- A `NaN` or infinite `double` property value is removed and the event is still sent, as in 5.x. Inside a list, it's sent as `null`. +- A lone UTF-16 surrogate, such as a string cut in the middle of an emoji, becomes U+FFFD and the event is sent. This covers the event name, distinct ID, `$session_id`, `$window_id`, properties and options, the IDs passed to `identify`, `alias` and `group`, and the person and group properties sent to `/flags`. The SDK keeps each ID as you passed it and repairs only what it sends. In 5.x, legacy capture rejected the whole batch for a lone surrogate anywhere in it. iOS, macOS and Android already send the event with U+FFFD in place of each lone surrogate. +- The SDK doesn't report these drops to your code. With `debug` on, it logs how many events PostHog dropped and why (see [Logs](#logs)). + +#### SDK identity + +PostHog sets `$lib` and `$lib_version` from the `PostHog-Sdk-Info` request header, `posthog-flutter/`. +The SDK removes `$lib` and `$lib_version` from the properties it sends. +A value you set in properties, in a registered property or in `beforeSend` doesn't reach PostHog. + +#### Property precedence + +An event's properties are the SDK's, then registered properties, then the event's own, so your value now wins for that event. In 5.x, the SDK's values won. +`beforeSend` runs after that merge and sees the result. + +A registered or passed `$session_id` that is a non-empty string replaces the SDK's session ID, which can detach events from their session. + +#### Session and window IDs + +Capture v1 sends `$session_id` and `$window_id` as top-level `session_id` and `window_id` fields, not as properties. +The SDK moves them out of `properties` for you. + +- A string value, including an empty string, is sent unchanged. +- Any other value is removed and not sent. With `debug` on, the SDK logs a warning that names the key and the value's JSON type, never the value. +- A `null` value counts as unset and is removed without a warning. + +In PostHog, the events still have `$session_id` and `$window_id`. + +#### Event options + +The legacy option properties, the `$`-prefixed properties legacy capture reads as settings, still work. +When the event is sent, the SDK removes each one from `properties` and uses it for its option: + +| Legacy option property | Option | +| --- | --- | +| `$process_person_profile` | `process_person_profile` | +| `$cookieless_mode` | `cookieless_mode` | +| `$ignore_sent_at` | `disable_skew_correction` | +| `$product_tour_id` | `product_tour_id` | + +- An option you pass or set in `beforeSend` wins over its legacy option property. A `null` option counts as unset, so the legacy option property fills it. +- Option values are sent as given. PostHog drops an event whose option value it can't read. +- Other option keys are sent unchanged. +- There are no global options. To set one for every event, register its legacy option property, for example `Posthog().register(r'$cookieless_mode', true)`. +- A registered legacy option property also reaches `$identify`, `$create_alias` and `$groupidentify`. If it turns person processing off, PostHog accepts those events and then drops them with an ingestion warning, and the SDK doesn't report it. +- Person processing is sent as the `process_person_profile: false` option only while it's off, instead of a `$process_person_profile` property on every event. +- Person processing is decided before `beforeSend` runs, as on iOS, macOS and Android. A callback that adds `$set` to an anonymous event must also set the `process_person_profile: true` option. +- Events still queued on disk by 5.x are sent to capture v1 after the update, with their legacy option properties moved to options. + +**Review your `beforeSend` callbacks for the new event shape.** On Windows and Linux, `beforeSend` sees the options the SDK adds, including `process_person_profile: false`. A callback that returns a new `PostHogEvent` or replaces `event.options` without that key turns person processing on for that event. A legacy option property that a callback adds doesn't replace an option that is already set. `beforeSend` doesn't see `$identify`, `$create_alias`, `$groupidentify` or `$feature_flag_called`. + +`$exception_steps` is added to `$exception` events before `beforeSend` runs, so a callback can read or remove it. Steps recorded while a callback runs, and an event a callback renames to `$exception`, don't get them. + +#### Retries + +- The SDK retries network errors and 404, 408, 429, 500, 502, 503 and 504 responses. Other statuses drop the batch, such as a 402 when you're over your billing limit. A product quota, such as for AI events, instead drops only those events inside a 2xx. 5.x retried 408, 429, every 5xx and 3xx responses, and didn't retry 404. +- When the response asks to retry only some events, the SDK keeps those events queued and removes the rest. +- After a failed send, the wait before the next one doubles from 1 second up to 30 seconds, with up to 25% random jitter. Retries have no limit: queued events stay until they're delivered or a full queue drops the oldest. In 5.x, a failed batch was retried up to 3 times, 3 seconds apart, within the same flush. +- A `Retry-After` header is a floor under that wait, capped at 30 seconds. In 5.x it had no cap. +- A 2xx response without PostHog's per-event results drops the batch. It isn't retried, because PostHog may have stored some of the events. +- A request times out after 10 seconds without progress, and an AI request after 60 seconds. In 5.x, a request timed out after 10 seconds in total. + +#### Redirects + +The SDK follows a 307 or 308 redirect only to the origin of `host` (same scheme, host and port), at most 5 times, and resends the same body and headers. +Any other redirect drops the batch. +In 5.x, no redirect was followed and the batch stayed queued. +If a proxy redirects capture requests to another host, point `host` at the final host. + +#### Batches and size limits + +- A request carries at most `maxBatchSize` events and 5 MiB. The SDK sends as soon as 5 MiB of events is queued, even before `flushAt` is reached. In 5.x, batches were limited by event count only. +- A larger event is sent alone. +- A `413` for a batch of more than one event halves `maxBatchSize` and `flushAt`, and the events are sent again in smaller batches. A `413` for a single event drops it. +- The SDK doesn't limit the size of an analytics event, as in 5.x. + +#### AI events + +- `captureAi` events have their own on-disk queue of up to `captureAiMaxQueueSize` events (100 by default) and 50 MiB, and the oldest are dropped first. `maxQueueSize` doesn't apply. +- An event over `captureAiMaxEventBytes` (8 MiB plus 64 KiB by default) is dropped, and `captureAi` returns `null`. You can only lower the limit. +- AI requests are gzipped unless you set `captureAiCompression` to `PostHogCompression.none`. `compression` doesn't apply. +- AI requests time out after 60 seconds without progress, or `captureAiTimeout`. +- AI events use `flushAt` and `maxBatchSize`, like other events. +- `flush()` and `close()` also send AI events, and AI events left on disk are sent after the next `setup()`. +- PostHog drops an event sent with `captureAi` whose name doesn't start with `$ai_`. With `debug` on, the SDK logs a warning for it. `capture` never sends events to the AI endpoint. + +#### Logs + +All of these log only with `debug` on, except the 404 warning. + +- One line per batch reports the events PostHog dropped, with their reasons, and the repeated-uuid copies it dropped, for example `Capture /i/v1/analytics/events dropped 1 of 20 events for good (event_name_too_long: 1) and 0 repeated-uuid copies.` 5.x had no such line. +- A failed flush logs `Error while flushing PostHog /i/v1/analytics/events` or `/i/v1/ai/events` and the error, without the response body. In 5.x the line was `Error while flushing PostHog` and the error included the response body. Update any log-based alerts that match the old text. +- The debug log no longer includes the properties of captured and sent events. To inspect events, use `beforeSend`. + +#### Timestamps and IDs + +- An event's timestamp is taken before `beforeSend` runs, and a callback can change it. +- Timestamps are UTC with 3 or 6 fractional digits, as in 5.x. The SDK doesn't check for future timestamps. +- Event uuids, request IDs and anonymous distinct IDs are UUID v7. You can't set an event's uuid, so events never repeat one. + +#### Writes to disk -- **Property order:** an event's properties are the SDK's, then registered properties, then the event's own, so your value now wins for that event. `beforeSend` runs after that merge, except that `$lib` and `$lib_version` always come from the `PostHog-Sdk-Info` header. -- **Person processing:** it's sent as the `process_person_profile: false` option only while it's off, instead of a `$process_person_profile` property on every event. -- **`beforeSend` and person processing:** person processing is decided before the callbacks run. A callback that adds `$set` to an anonymous event must also set the `process_person_profile: true` option. -- **Redirects:** only same-origin 307 and 308 redirects are followed. Any other redirect drops the batch. -- **Retries:** a failed batch waits 1 second, doubling up to 30 seconds with ±25% jitter, instead of retrying within the same flush. `Retry-After` is a floor under that wait, capped at 30 seconds. -- **Writes to disk:** an event is no longer on disk when `capture`, `screen`, `captureException`, `captureFeatureView`, `captureFeatureInteraction`, `identify`, `alias`, `group` or `setPersonProperties` returns, only when the returned future completes. One you didn't await can be lost if the app crashes or calls `exit()` right after. Await the call, or `Posthog().close()`, before `exit()`. Only `close()` also covers events the SDK captures itself, such as `$feature_flag_called`. An `identify` not awaited before `exit()` can lose its `$identify` event for good, because the new ID is already saved. `close()` can now take up to 4 seconds, and a later `setup()` waits for the queue's file work. -- **Timestamps:** an event's timestamp is taken before `beforeSend` runs. -- **AI queue:** `captureAi` events have their own on-disk queue of up to `captureAiMaxQueueSize` events (100 by default) and 50 MiB. An event over `captureAiMaxEventBytes` (8 MiB plus 64 KiB by default) is dropped. +An event is no longer on disk when `capture`, `screen`, `captureException`, `captureFeatureView`, `captureFeatureInteraction`, `identify`, `alias`, `group` or `setPersonProperties` returns, only when the returned future completes. One you didn't await can be lost if the app crashes or calls `exit()` right after. Await the call, or `Posthog().close()`, before `exit()`. Only `close()` also covers events the SDK captures itself, such as `$feature_flag_called`. An `identify` not awaited before `exit()` can lose its `$identify` event for good, because the new ID is already saved. `close()` can now take up to 4 seconds, and a later `setup()` waits for the queue's file work. ### `getFeatureFlagResult()` follows your config @@ -305,9 +457,12 @@ On web, `PostHogConfig.sendFeatureFlagEvent` is not applied to posthog-js, so an ## New features -- An `options` argument on `capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group` and `captureException`, and `PostHogEvent.options` in `beforeSend`. `process_person_profile`, `cookieless_mode`, `disable_skew_correction` and `product_tour_id` win over their legacy `$` properties. On web, known keys are sent as those legacy properties and other keys are dropped. +- An `options` argument on `capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group` and `captureException`, and `PostHogEvent.options` in `beforeSend`. `process_person_profile`, `cookieless_mode`, `disable_skew_correction` and `product_tour_id` win over their legacy option properties (`$process_person_profile`, `$cookieless_mode`, `$ignore_sent_at` and `$product_tour_id`). Other keys are sent unchanged. On web, known keys are sent as those legacy option properties and other keys are dropped. On web, `process_person_profile` has no effect, and the options of `identify`, `setPersonProperties`, `alias` and `group` are dropped. - `captureAi` for `$ai_*` events. It returns the event's UUID, or `null` when the event isn't admitted. On web it sends nothing and returns `null`. - `Posthog().onFeatureFlags()` to get notified after every feature flags load. It returns a `PostHogFeatureFlagsSubscription` you can `unsubscribe()`. You can register it before `WidgetsFlutterBinding.ensureInitialized()`, but other SDK calls, including `setup()`, are skipped with a warning until the binding is initialized. +- `$app_language` and `Posthog().setAppLanguage()`. See [`$locale` and `$app_language`](#locale-and-app_language). +- `PosthogFlutterPlugin.addBeforeSend` in Swift and Kotlin, to filter or edit events the native SDK captures itself, such as crashes, app lifecycle and `$feature_flag_called` events. +- `PostHogConfig.captureAiCompression`, `captureAiMaxQueueSize`, `captureAiTimeout` and `captureAiMaxEventBytes` for `captureAi` requests. They don't apply on web. ## Upgrade checklist @@ -317,7 +472,11 @@ On web, `PostHogConfig.sendFeatureFlagEvent` is not applied to posthog-js, so an - [ ] Rename `com.posthog.posthog.API_KEY` to `com.posthog.posthog.PROJECT_TOKEN` in `AndroidManifest.xml` and `Info.plist`. - [ ] Use Xcode 26 or later. - [ ] If you run your own reverse proxy or self-host, serve `/i/v1/analytics/events` and `/i/v1/ai/events` first. +- [ ] Shorten or hash distinct IDs over 200 UTF-8 bytes. +- [ ] Make `beforeSend` callbacks, including `PostHogLogsConfig.beforeSend`, synchronous. +- [ ] Review your `beforeSend` callbacks for the new event shape, which includes the SDK's properties and options on every platform except web, and for person processing decided before they run. - [ ] Replace `PostHogConfig.onFeatureFlags` with `Posthog().onFeatureFlags()` before `setup()`. +- [ ] Update cohorts, insights and actions that match `$locale`, which now includes the region. Use `$app_language` for the language your app shows. - [ ] Move anything that reads `version` or `build` on iOS and macOS lifecycle events to `$app_version` and `$app_build`. - [ ] If you set `sendFeatureFlagEvent = false`, check whether anything relies on `$feature_flag_called` from `getFeatureFlagResult()`. - [ ] Add `sendFeatureFlagEvent: false` wherever you replace `getFeatureFlagPayload()`. From 353f1ae5ced28e47862d25bd3366086d0e18c88f Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Wed, 4 Nov 2026 16:36:24 -0500 Subject: [PATCH 26/28] fix(android): set PostHogEvent.options after copy posthog-android 4.0 keeps the 3.x PostHogEvent constructor and copy so posthog-server stays compatible, and makes options a property instead. Co-Authored-By: Claude Opus 5.5 --- .../main/kotlin/com/posthog/flutter/PosthogFlutterPlugin.kt | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/posthog_flutter/android/src/main/kotlin/com/posthog/flutter/PosthogFlutterPlugin.kt b/posthog_flutter/android/src/main/kotlin/com/posthog/flutter/PosthogFlutterPlugin.kt index ad8cdf26..69604186 100644 --- a/posthog_flutter/android/src/main/kotlin/com/posthog/flutter/PosthogFlutterPlugin.kt +++ b/posthog_flutter/android/src/main/kotlin/com/posthog/flutter/PosthogFlutterPlugin.kt @@ -1955,8 +1955,7 @@ class PosthogFlutterPlugin : distinctId = call.argument("distinctId")?.takeIf { it.isNotBlank() } ?: built.distinctId, properties = properties?.toMutableMap() ?: mutableMapOf(), timestamp = timestampMs?.let { Date(it) } ?: built.timestamp, - options = options?.toMutableMap() ?: mutableMapOf(), - ) + ).also { it.options = options?.toMutableMap() ?: mutableMapOf() } val sent = PostHog.sendBuiltEventForWrapper(event, ai = call.argument("ai") ?: false) result.success(sent?.toString()) } catch (e: Throwable) { From e60a62893db9af6c2126afd9391d740249b12dec Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Thu, 5 Nov 2026 09:36:03 -0500 Subject: [PATCH 27/28] fix(desktop): resend a capture v1 retry alone to keep its request identity (#704) When events wait to be retried, the next request of their lane sends exactly those events, so it keeps PostHog-Request-Id and created_at and increments PostHog-Attempt. Newer events go out after it as a new request. If one of the events to retry is gone from the queue, the lane falls back to normal batching and starts a new request at attempt 1. Matches posthog-android 4.0 and the backend capture v1 SDKs. Co-authored-by: Claude Opus 5.5 --- .../lib/src/core/file_storage.dart | 34 +++++++---- .../lib/src/core/posthog_core_stateless.dart | 26 +++++++- .../test/core/capture_v1_test.dart | 59 +++++++++++++++---- .../test/core/queue_flush_test.dart | 26 ++++---- 4 files changed, 111 insertions(+), 34 deletions(-) diff --git a/posthog_flutter/lib/src/core/file_storage.dart b/posthog_flutter/lib/src/core/file_storage.dart index 8c550457..58d3691b 100644 --- a/posthog_flutter/lib/src/core/file_storage.dart +++ b/posthog_flutter/lib/src/core/file_storage.dart @@ -562,6 +562,27 @@ class FileEventQueue { selected.add(id); bytes += size; } + return _read(selected).then((events) { + // An empty peek ends the flush, which must not leave the events behind + // the unreadable ones unsent. + return events.isEmpty && selected.isNotEmpty + ? _peekWritten(count, maxBytes, skipped: {...skipped, ...selected}) + : events; + }); + } + + /// Returns the events with the given [ids], in that order, or null when + /// one of them is no longer queued or cannot be read now. + Future?> peekIds(List ids) { + final queued = _ids.toSet(); + if (!ids.every(queued.contains)) return SynchronousFuture(null); + return _read(ids) + .then((events) => events.length == ids.length ? events : null); + } + + /// The [selected] events still queued, read by the worker unless they are + /// kept in memory. + Future> _read(List selected) { final toRead = [ for (final id in selected) if (!_unwritten.containsKey(id)) id, @@ -569,16 +590,9 @@ class FileEventQueue { final read = toRead.isEmpty ? SynchronousFuture(const []) : _job(_worker.read([for (final id in toRead) _pathOf(id)])); - return read.then((read) { - final events = _collect(selected, { - for (var i = 0; i < toRead.length; i++) toRead[i]: read[i], - }); - // An empty peek ends the flush, which must not leave the events behind - // the unreadable ones unsent. - return events.isEmpty && selected.isNotEmpty - ? _peekWritten(count, maxBytes, skipped: {...skipped, ...selected}) - : events; - }); + return read.then((read) => _collect(selected, { + for (var i = 0; i < toRead.length; i++) toRead[i]: read[i], + })); } /// The [selected] events still queued, from memory or from [read]. diff --git a/posthog_flutter/lib/src/core/posthog_core_stateless.dart b/posthog_flutter/lib/src/core/posthog_core_stateless.dart index 1c5b255b..7ad6b62d 100644 --- a/posthog_flutter/lib/src/core/posthog_core_stateless.dart +++ b/posthog_flutter/lib/src/core/posthog_core_stateless.dart @@ -705,8 +705,7 @@ abstract class PostHogCoreStateless { // Peeked again after every request, so events queued in the meantime // go out with the same flush. The queue sizes the batch before // reading it, so events past the batch are not decoded. - final batch = - await queue.peek(lane.maxBatchSize, maxBytes: captureV1MaxBatchBytes); + final batch = await _nextBatch(lane); if (_closed) break; if (batch.isEmpty) { // The next peek waits for the event still being written. @@ -718,6 +717,20 @@ abstract class PostHogCoreStateless { } } + /// The events of the request waiting to be retried, alone, so that the + /// retry keeps its request id and `created_at`; otherwise the next batch + /// from the front of the queue. Once one of the events to retry is gone, + /// e.g. dropped to make room, the request starts over as a new one. + Future> _nextBatch(_CaptureLane lane) async { + final retryIds = lane.retryIds; + lane.retryIds = null; + if (retryIds != null) { + final retry = await lane.queue.peekIds(retryIds); + if (retry != null) return retry; + } + return lane.queue.peek(lane.maxBatchSize, maxBytes: captureV1MaxBatchBytes); + } + /// Sends [batch] to capture v1 and removes from the queue the events that /// are done: delivered, or dropped for good. Emits `flush` with the /// delivered ones right away, so a long flush doesn't hold on to the @@ -766,6 +779,7 @@ abstract class PostHogCoreStateless { // until the next capture (forever in an idle app after an offline // failure). if (_isTransientCaptureError(e)) { + lane.retryIds = [for (final queued in batch) queued.id]; _backOff(lane, e is PostHogFetchHttpError ? e.retryAfter : null); } else { queue.remove([for (final queued in batch) queued.id]); @@ -793,6 +807,10 @@ abstract class PostHogCoreStateless { return true; } + lane.retryIds = [ + for (final queued in batch) + if (retryUuids.contains(queued.event['uuid'])) queued.id, + ]; // Counts only: uuids and server details can identify users. logger.info('Capture asked to retry ${batch.length - delivered.length} ' 'of ${batch.length} events.'); @@ -1143,6 +1161,10 @@ class _CaptureLane { /// retried. Kept in memory: after a restart the retry is a new request. CaptureV1Identity? pendingIdentity; + /// The queue ids of the events of [pendingIdentity], which the next + /// request sends alone, before any newer event. + List? retryIds; + /// Flushes in a row whose batch failed with a transient error or had /// events the server asked to retry. Each one pauses the queue for longer, /// see [captureRetryDelay], so a failure that lasts, like a missing diff --git a/posthog_flutter/test/core/capture_v1_test.dart b/posthog_flutter/test/core/capture_v1_test.dart index ecc97a4c..eb5c1362 100644 --- a/posthog_flutter/test/core/capture_v1_test.dart +++ b/posthog_flutter/test/core/capture_v1_test.dart @@ -483,28 +483,67 @@ void main() { }); }); - test('starts a new request when new events join a retried batch', () { + for (final (name, firstResponse) in [ + ( + 'a partial retry', + (PostHogRequest request) => PostHogResponse.results( + request, (name) => name == 'retried' ? 'retry' : null), + ), + ( + 'a failed request', + (PostHogRequest _) => const PostHogResponse(HttpStatus.badGateway), + ), + ]) { + test('resends $name alone, then sends newer events as a new request', () { + final api = InProcessPostHogApi(); + final storage = tempStorage(); + api.respond = (request) => api.batchRequests.length == 1 + ? firstResponse(request) + : PostHogResponse.results(request, (_) => 'ok'); + fakeAsync((async) { + final client = testClient(api, storage: storage); + client.capture('retried'); + client.flush().catchError((Object _) {}); + async.elapse(Duration.zero); + client.capture('joined'); + async.elapse(const Duration(seconds: 1)); + + final [first, retry, next] = api.batchRequests; + expect(retry.eventNames, ['retried']); + expect(retry.headers['posthog-request-id'], + first.headers['posthog-request-id']); + expect(retry.headers['posthog-attempt'], '2'); + expect(retry.body['created_at'], first.body['created_at']); + expect(next.eventNames, ['joined']); + expect(next.headers['posthog-request-id'], + isNot(first.headers['posthog-request-id'])); + expect(next.headers['posthog-attempt'], '1'); + expect(getQueue(storage), isEmpty); + }); + }); + } + + test('starts a new request once an event to retry is dropped', () { final api = InProcessPostHogApi(); final storage = tempStorage(); api.respond = (request) => api.batchRequests.length == 1 - ? PostHogResponse.results( - request, (name) => name == 'retried' ? 'retry' : null, - headers: {'Retry-After': '5'}) + ? const PostHogResponse(HttpStatus.badGateway) : PostHogResponse.results(request, (_) => 'ok'); fakeAsync((async) { - final client = testClient(api, storage: storage); - client.capture('retried'); - client.flush(); + final client = testClient(api, + config: testConfig(maxQueueSize: 2), storage: storage); + client.capture('dropped'); + client.capture('kept'); + client.flush().catchError((Object _) {}); async.elapse(Duration.zero); client.capture('joined'); - async.elapse(const Duration(seconds: 5)); + async.elapse(const Duration(seconds: 1)); final [first, second] = api.batchRequests; - expect(second.eventNames, ['retried', 'joined']); + expect(second.eventNames, ['kept', 'joined']); expect(second.headers['posthog-request-id'], isNot(first.headers['posthog-request-id'])); expect(second.headers['posthog-attempt'], '1'); - expect(getQueue(storage), isEmpty); }); }); diff --git a/posthog_flutter/test/core/queue_flush_test.dart b/posthog_flutter/test/core/queue_flush_test.dart index d839fa77..194f6212 100644 --- a/posthog_flutter/test/core/queue_flush_test.dart +++ b/posthog_flutter/test/core/queue_flush_test.dart @@ -417,17 +417,17 @@ void main() { expect(queuedEvents(storage), ['first', 'second']); async.elapse(const Duration(seconds: 1)); - expect(api.batchRequests, hasLength(2)); - expect(api.batchRequests.last.eventNames, ['first', 'second']); - expect(api.batchRequests.last.events.first['uuid'], original['uuid']); - expect(api.batchRequests.last.events.first['timestamp'], - original['timestamp']); + final [_, retry, next] = api.batchRequests; + expect(retry.eventNames, ['first']); + expect(retry.events.single['uuid'], original['uuid']); + expect(retry.events.single['timestamp'], original['timestamp']); + expect(next.eventNames, ['second']); expect(getQueue(storage), isEmpty); client.capture('third'); client.capture('fourth'); async.elapse(Duration.zero); - expect(api.batchRequests, hasLength(3), + expect(api.batchRequests, hasLength(4), reason: 'the previous pause does not apply after a success'); }); }); @@ -522,10 +522,11 @@ void main() { async.elapse(const Duration(seconds: 19)); expect(api.batchRequests, hasLength(1)); async.elapse(const Duration(seconds: 1)); - final events = api.batchRequests.last.events; - expect(events.map((event) => event['event']), ['before', 'after']); - expect(events[0]['distinct_id'], previousId); - expect(events[1]['distinct_id'], nextId); + final [_, before, after] = api.batchRequests; + expect(before.eventNames, ['before']); + expect(before.events.single['distinct_id'], previousId); + expect(after.eventNames, ['after']); + expect(after.events.single['distinct_id'], nextId); }); }); @@ -546,8 +547,9 @@ void main() { client.flush(); client.flush(); async.elapse(Duration.zero); - expect(api.batchRequests, hasLength(2)); - expect(api.batchRequests.last.eventNames, ['first', 'second']); + final [_, retry, next] = api.batchRequests; + expect(retry.eventNames, ['first']); + expect(next.eventNames, ['second']); }); }); From e28f24fcc2452106f15916b9306f4e90f9c3ea74 Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Thu, 5 Nov 2026 09:36:24 -0500 Subject: [PATCH 28/28] feat!: report the device language as $locale and add $app_language (#699) * chore!: adopt posthog-ios 4.0 - Require posthog-ios 4.x. - Adapt to the reloadFeatureFlags(_:) callback that now passes a PostHogFeatureFlagsLoaded (PostHog/posthog-ios#913). - Note the payload decoding changes from PostHog/posthog-ios#903. Co-Authored-By: Claude Opus 5.5 (1M context) * docs(changeset): note posthog-ios 4.0 drops lifecycle version and build PostHog/posthog-ios#905 removes the legacy version/build properties from lifecycle events in 4.0, so Flutter iOS and macOS apps stop sending them. Co-Authored-By: Claude Opus 5.5 (1M context) * chore(ios): drive onFeatureFlags from the posthog-ios onFeatureFlags listener posthog-ios 4.0 removes the didReceiveFeatureFlags notification. * chore!: adopt posthog-android 4.0 (#663) * chore!: adopt posthog-android 4.0 * chore!: pass the loaded flags to onFeatureFlags and reloadFeatureFlags (#664) * chore!: pass the loaded flags to onFeatureFlags and reloadFeatureFlags onFeatureFlags and reloadFeatureFlags now carry a PostHogFeatureFlagsLoaded with the enabled flags, their values and whether loading failed, matching posthog-ios 4.0 and posthog-android 4.0. On web, reloadFeatureFlags completes right away with the flags loaded so far, because posthog-js doesn't report when a reload finishes. * fix: complete the web reloadFeatureFlags with the reloaded flags Wait for the next posthog-js onFeatureFlags call instead of returning the flags already loaded, so a failed reload reports errorsLoading. Complete right away when flags are disabled, and after twice the flags request timeout when posthog-js skips the request without calling back. * chore: use PostHogFeatureFlagsCallback from posthog-android 4.0 * chore: fix ktlint function-signature * fix: await posthog-js reloadFeatureFlagsAsync on web The next onFeatureFlags callback can carry a response from a request already in flight, so reloadFeatureFlags() could complete with flags from before the reload. posthog-js 1.438.2+ settles reloadFeatureFlagsAsync() after this reload's own request; use it when present and keep the callback path for older posthog-js. * docs: pass the loaded flags in the setup example * docs: drop best-effort web note from the person and group property methods * fix(web): wait for posthog-js flags retries before reporting a reload failure posthog-js retries a timed-out /flags request once by default, 500 ms later, inside the same reload. The older-JS deadline of twice the request timeout reported cached flags with errorsLoading set before a successful retry landed. * docs: note where onFeatureFlags and errorsLoading differ on Android and web * docs: describe the older posthog-js reload timeout as the full retry budget Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 * docs(changeset): fold the posthog-android 4.0 and flags-loaded entries into one changeset Co-Authored-By: Claude Opus 5.5 * feat: add an onFeatureFlags listener you can unsubscribe * fix: isolate failing flag listeners, skip web registration without onFeatureFlags, update API snapshot * fix: deliver flag loads to onFeatureFlags listeners before the config callback A config callback that threw kept listeners from getting the load, and a reset() or close() it started was undone when the load was cached after it. Co-Authored-By: Claude Opus 5.5 * fix(web): stop flag registrations left by close() or the posthog-js loader A registration whose unsubscribe isn't stored yet (close() during the synchronous replay) or never arrives (the loader snippet's stub) now goes inert once setup() or close() runs again. Co-Authored-By: Claude Opus 5.5 * fix: drop native flag loads sent before a reset or close reached native Dart bumps a generation when reset() or close() clears the listener registry and sends it with setup, reset and close. Android and iOS tag each onFeatureFlags notification with the generation they had when it fired, and Dart drops ones from an earlier generation, so the previous user's flags can't repopulate the replay cache. Co-Authored-By: Claude Opus 5.5 * fix: start receiving native flag loads when the first listener is added With native auto-init, Posthog().onFeatureFlags() can be the app's only Dart SDK call, and nothing created the platform that installs the channel handler, so native loads never reached the listener. Co-Authored-By: Claude Opus 5.5 * fix: deliver Android reloadFeatureFlags results to onFeatureFlags listeners posthog-android passes a manual reload only to its completion, so no onFeatureFlagsCallback arrives and listeners missed the load while new ones replayed the older snapshot. A reload that finishes after a reset or close is still dropped. Co-Authored-By: Claude Opus 5.5 * chore: stop passing RRStyle to replay screenshot frames (#684) posthog-android 4.0 drops RRStyle and the wireframe tree fields from the internal RRWireframe; screenshot frames don't need a style. Co-authored-by: Claude Opus 5.5 * fix(web): clear replayed flags when a queued reset reaches posthog-js Co-Authored-By: Claude Opus 5.5 * feat!: remove PostHogConfig.onFeatureFlags in favor of the listener Posthog().onFeatureFlags() can be registered before setup() and removed, so the config field no longer adds anything. Android now drives Dart from the posthog-android listener like iOS does, which also fires after a manual reload, so the Dart-side Android reload delivery goes away. * docs: fold #670 release notes into the 6.0 docs * docs: fold #695 release notes into the 6.0 docs * test: use the onFeatureFlags listener in desktop tests from the base merge * fix(example): initialize the binding before registering the flags listener * fix: don't throw when SDK calls run before the Flutter binding exists Posthog() creates PosthogFlutterIO, whose constructor set the channel handler and aborted without a binding. Retry the install instead, and fail native calls with a PlatformException so each caller's existing fallback applies. * docs: show the removed onFeatureFlags constructor argument in the migration guide * feat!: report the device language as $locale and add $app_language * fix: address the pre-PR review of $locale and $app_language * docs: correct the $locale migration notes * fix: forward setAppLanguage on web * test: use the flags listener in the #694 desktop tests Co-Authored-By: Claude Opus 5.5 * fix: stop delivering a flags load that a listener's reset() or close() cleared The listeners after it and the config callback no longer get the old flags. Claude-Session: https://claude.ai/code/session_019xLynws83apuXa9LfRy9Aq * fix: keep $app_language on a web capture made right after reset() posthog-js clears registered properties on reset, and the language was only registered again after an await, so an un-awaited capture() went out without it. The web plugin now registers it in the same step as the reset. Native and desktop keep the language across reset, so Posthog.reset() no longer resends. Co-Authored-By: Claude Opus 5.5 * docs: say $locale follows a per-app language on iOS and macOS Co-Authored-By: Claude Opus 5.5 * docs: drop the duplicate $locale upgrade checklist item #701 already lists it. Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 (1M context) --- api/posthog_flutter.api.json | 66 +++++++++++++++++++ .../posthog/flutter/PosthogFlutterPlugin.kt | 18 +++++ .../PosthogFlutterPlugin.swift | 6 ++ posthog_flutter/lib/posthog_flutter_web.dart | 22 ++++++- posthog_flutter/lib/src/posthog.dart | 53 ++++++++++++++- .../lib/src/posthog_desktop_client.dart | 9 ++- .../lib/src/posthog_desktop_context.dart | 9 +-- .../lib/src/posthog_flutter_desktop.dart | 4 ++ .../lib/src/posthog_flutter_io.dart | 13 ++++ .../posthog_flutter_platform_interface.dart | 4 ++ .../lib/src/posthog_flutter_web_handler.dart | 8 +++ posthog_flutter/lib/src/posthog_observer.dart | 3 + .../test/posthog_desktop_context_test.dart | 16 ++--- .../test/posthog_flutter_desktop_test.dart | 13 +++- ...sthog_flutter_platform_interface_fake.dart | 7 ++ .../posthog_flutter_web_handler_test.dart | 65 ++++++++++++++++++ .../test/posthog_observer_test.dart | 66 +++++++++++++++++++ 17 files changed, 364 insertions(+), 18 deletions(-) diff --git a/api/posthog_flutter.api.json b/api/posthog_flutter.api.json index 89dc0b0d..86fde7cb 100644 --- a/api/posthog_flutter.api.json +++ b/api/posthog_flutter.api.json @@ -866,6 +866,28 @@ "type": "method", "typeParameterNames": [] }, + { + "entryPoints": [], + "isDeprecated": false, + "isExperimental": false, + "isStatic": false, + "name": "setAppLanguage", + "parameters": [ + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": false, + "isRequired": true, + "name": "language", + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "typeName": "String?" + } + ], + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "returnTypeName": "Future", + "type": "method", + "typeParameterNames": [] + }, { "entryPoints": [], "isDeprecated": false, @@ -2049,6 +2071,28 @@ "type": "method", "typeParameterNames": [] }, + { + "entryPoints": [], + "isDeprecated": false, + "isExperimental": false, + "isStatic": false, + "name": "setAppLanguage", + "parameters": [ + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": false, + "isRequired": true, + "name": "language", + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "typeName": "String?" + } + ], + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "returnTypeName": "Future", + "type": "method", + "typeParameterNames": [] + }, { "entryPoints": [], "isDeprecated": false, @@ -4870,6 +4914,28 @@ "type": "method", "typeParameterNames": [] }, + { + "entryPoints": [], + "isDeprecated": false, + "isExperimental": false, + "isStatic": false, + "name": "setAppLanguage", + "parameters": [ + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": false, + "isRequired": true, + "name": "language", + "relativePath": "lib/src/posthog.dart", + "typeName": "String?" + } + ], + "relativePath": "lib/src/posthog.dart", + "returnTypeName": "Future", + "type": "method", + "typeParameterNames": [] + }, { "entryPoints": [], "isDeprecated": false, diff --git a/posthog_flutter/android/src/main/kotlin/com/posthog/flutter/PosthogFlutterPlugin.kt b/posthog_flutter/android/src/main/kotlin/com/posthog/flutter/PosthogFlutterPlugin.kt index 69604186..4b4949b0 100644 --- a/posthog_flutter/android/src/main/kotlin/com/posthog/flutter/PosthogFlutterPlugin.kt +++ b/posthog_flutter/android/src/main/kotlin/com/posthog/flutter/PosthogFlutterPlugin.kt @@ -384,6 +384,10 @@ class PosthogFlutterPlugin : unregister(call, result) } + "setAppLanguage" -> { + setAppLanguage(call, result) + } + "debug" -> { debug(call, result) } @@ -870,6 +874,8 @@ class PosthogFlutterPlugin : } } + // Flutter apps translate in Dart, so native resources don't say what's shown + detectAppLanguage = false sdkName = "posthog-flutter" sdkVersion = postHogVersion @@ -2262,6 +2268,18 @@ class PosthogFlutterPlugin : } } + private fun setAppLanguage( + call: MethodCall, + result: Result, + ) { + try { + PostHog.setAppLanguage(call.argument("language")) + result.success(null) + } catch (e: Throwable) { + result.error("PosthogFlutterException", e.localizedMessage, null) + } + } + private fun unregisterPushNotificationToken(result: Result) { try { PostHog.unregisterPushNotificationToken() diff --git a/posthog_flutter/darwin/posthog_flutter/Sources/posthog_flutter/PosthogFlutterPlugin.swift b/posthog_flutter/darwin/posthog_flutter/Sources/posthog_flutter/PosthogFlutterPlugin.swift index 8d55ae92..1cd3e1d2 100644 --- a/posthog_flutter/darwin/posthog_flutter/Sources/posthog_flutter/PosthogFlutterPlugin.swift +++ b/posthog_flutter/darwin/posthog_flutter/Sources/posthog_flutter/PosthogFlutterPlugin.swift @@ -536,6 +536,9 @@ public class PosthogFlutterPlugin: NSObject, FlutterPlugin { config.setBeforeSend(beforeSend) } + // Flutter apps translate in Dart, so the app bundle doesn't say what's shown + config.detectAppLanguage = false + // Update SDK name and version postHogSdkName = "posthog-flutter" postHogVersion = postHogFlutterVersion @@ -615,6 +618,9 @@ public class PosthogFlutterPlugin: NSObject, FlutterPlugin { register(call, result: result) case "unregister": unregister(call, result: result) + case "setAppLanguage": + PostHogSDK.shared.setAppLanguage((call.arguments as? [String: Any])?["language"] as? String) + result(nil) case "flush": flush(result) case "captureException": diff --git a/posthog_flutter/lib/posthog_flutter_web.dart b/posthog_flutter/lib/posthog_flutter_web.dart index cc96fe4b..17ae2046 100644 --- a/posthog_flutter/lib/posthog_flutter_web.dart +++ b/posthog_flutter/lib/posthog_flutter_web.dart @@ -38,6 +38,7 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { /// way [PosthogFlutterIO] runs it before the platform channel. List _beforeSendCallbacks = []; JSFunction? _featureFlagsUnsubscribe; + String? _appLanguage; /// Bumped by each setup() and close(), so a posthog-js registration from an /// earlier one stops delivering even when it can't be unsubscribed. @@ -121,6 +122,9 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { final instance = PosthogFlutterWeb(); channel.setMethodCallHandler(instance.handleMethodCall); + // posthog-js persists registered properties, but $app_language lasts one launch. + posthog?.unregister(stringToJSAny(r'$app_language')); + // Set the platform instance so that Posthog() can call methods directly // on the web implementation instead of going through the method channel. // This is required because method channels can only pass serializable data, @@ -489,7 +493,16 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { @override Future reset() async { - return handleWebMethodCall(const MethodCall('reset')); + final language = _appLanguage; + // posthog-js clears registered properties on reset. Registering in the + // same synchronous step keeps $app_language on a capture() made without + // awaiting reset(). + await Future.wait([ + handleWebMethodCall(const MethodCall('reset')), + if (language != null) + handleWebMethodCall( + MethodCall('setAppLanguage', {'language': language})), + ]); } @override @@ -525,6 +538,13 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { return handleWebMethodCall(MethodCall('unregister', {'key': key})); } + @override + Future setAppLanguage(String? language) async { + _appLanguage = language; + return handleWebMethodCall( + MethodCall('setAppLanguage', {'language': language})); + } + @override Future isFeatureEnabled( String key, { diff --git a/posthog_flutter/lib/src/posthog.dart b/posthog_flutter/lib/src/posthog.dart index f262041f..5299dbb6 100644 --- a/posthog_flutter/lib/src/posthog.dart +++ b/posthog_flutter/lib/src/posthog.dart @@ -41,6 +41,10 @@ class Posthog { String? _currentScreen; + String? _appLanguageFromApp; + String? _resolvedAppLanguage; + String? _sentAppLanguage; + /// Initializes the PostHog SDK. /// /// This method sets up the connection to your PostHog instance and prepares @@ -69,7 +73,7 @@ class Posthog { /// For Android and iOS, if you are performing a manual setup, /// ensure `com.posthog.posthog.AUTO_INIT: false` is set in your native /// configuration. - Future setup(PostHogConfig config) { + Future setup(PostHogConfig config) async { if (!isUsableProjectToken(config.projectToken)) { return Future.value(); } @@ -95,7 +99,11 @@ class Posthog { _installFlutterIntegrations(config); - return _posthog.setup(config); + await _posthog.setup(config); + // A new desktop client starts without it. + if (_sentAppLanguage != null) { + await _posthog.setAppLanguage(_sentAppLanguage); + } } void _installFlutterIntegrations(PostHogConfig config) { @@ -558,6 +566,47 @@ class Posthog { /// Returns a [Future] that completes when the property has been removed. Future unregister(String key) => _posthog.unregister(key); + /// Sets the `$app_language` property: the language your app displays, sent + /// with every event. + /// + /// Default: [PosthogObserver] reports the locale your `MaterialApp` resolved + /// each time a route changes, which is `en-US` if you declare no + /// `supportedLocales`. Call this if you don't use the observer, translate + /// outside `Localizations`, or want to report a different value. + /// + /// Your value wins over the observer's and survives [reset]. It's kept in + /// memory, so call it again on the next launch. Compare `$locale`, which is + /// the device language, or on iOS and macOS a language picked for the app in + /// Settings. + /// + /// The [language] is a BCP 47 tag, such as `de` or `pt-BR`. Pass `null` to go + /// back to the observer's value. + /// + /// **Example:** + /// ```dart + /// await Posthog().setAppLanguage('de'); + /// ``` + Future setAppLanguage(String? language) async { + final normalized = language?.trim().replaceAll('_', '-'); + _appLanguageFromApp = normalized?.isEmpty == true ? null : normalized; + await _syncAppLanguage(); + } + + /// For internal use only. Called by [PosthogObserver] as routes change. + @internal + Future reportResolvedAppLanguage(String? language) async { + _resolvedAppLanguage = language; + await _syncAppLanguage(); + } + + Future _syncAppLanguage() async { + final language = _appLanguageFromApp ?? _resolvedAppLanguage; + if (language != _sentAppLanguage) { + _sentAppLanguage = language; + await _posthog.setAppLanguage(language); + } + } + /// Returns whether a boolean feature flag is enabled. /// /// Docs: https://posthog.com/docs/feature-flags and diff --git a/posthog_flutter/lib/src/posthog_desktop_client.dart b/posthog_flutter/lib/src/posthog_desktop_client.dart index 299e50b4..678e6ad7 100644 --- a/posthog_flutter/lib/src/posthog_desktop_client.dart +++ b/posthog_flutter/lib/src/posthog_desktop_client.dart @@ -24,12 +24,17 @@ class DesktopPostHog extends PostHogCore { /// The IANA name of the local time zone. final String? _timezone; + /// The language the app displays, reported as `$app_language`. + String? appLanguage; + @override Map getContextProperties() { - final language = languageCodeOf(PlatformDispatcher.instance.locale); + final locale = localeTagOf(PlatformDispatcher.instance.locale); + final language = appLanguage; return { ..._staticContext, - if (language != null) r'$locale': language, + if (locale != null) r'$locale': locale, + if (language != null) r'$app_language': language, }; } diff --git a/posthog_flutter/lib/src/posthog_desktop_context.dart b/posthog_flutter/lib/src/posthog_desktop_context.dart index 5f01b4f8..2c86bf30 100644 --- a/posthog_flutter/lib/src/posthog_desktop_context.dart +++ b/posthog_flutter/lib/src/posthog_desktop_context.dart @@ -41,14 +41,15 @@ String extractOsVersion(String banner) { return RegExp(r'\d+(\.\d+)+').firstMatch(banner)?[0] ?? banner; } -/// The language code of [locale] ("en"), reported as `$locale`. +/// The language tag of [locale] ("en-US"), reported as `$locale`. /// /// Null when the platform reported no locale ("und") or only the POSIX /// default Linux falls back to ("C"), which names no language. -String? languageCodeOf(Locale locale) { - final language = locale.languageCode; +String? localeTagOf(Locale locale) { const noLanguage = {'', 'und', 'C', 'POSIX'}; - return noLanguage.contains(language) ? null : language; + return noLanguage.contains(locale.languageCode) + ? null + : locale.toLanguageTag(); } /// Screen size in logical pixels. diff --git a/posthog_flutter/lib/src/posthog_flutter_desktop.dart b/posthog_flutter/lib/src/posthog_flutter_desktop.dart index 57378cf3..8a72b63e 100644 --- a/posthog_flutter/lib/src/posthog_flutter_desktop.dart +++ b/posthog_flutter/lib/src/posthog_flutter_desktop.dart @@ -506,6 +506,10 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { Future unregister(String key) => _guard('unregister', (client) => client.unregister(key)); + @override + Future setAppLanguage(String? language) => + _guard('setAppLanguage', (client) => client.appLanguage = language); + @override Future isFeatureEnabled(String key, {bool? sendFeatureFlagEvent, bool? defaultValue}) => diff --git a/posthog_flutter/lib/src/posthog_flutter_io.dart b/posthog_flutter/lib/src/posthog_flutter_io.dart index 6ba50646..4eead522 100644 --- a/posthog_flutter/lib/src/posthog_flutter_io.dart +++ b/posthog_flutter/lib/src/posthog_flutter_io.dart @@ -1053,6 +1053,19 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { } } + @override + Future setAppLanguage(String? language) async { + if (!isSupportedPlatform()) { + return; + } + + try { + await _invoke('setAppLanguage', {'language': language}); + } on PlatformException catch (exception) { + printIfDebug('Exeption on setAppLanguage: $exception'); + } + } + @override Future flush() async { if (!isSupportedPlatform()) { diff --git a/posthog_flutter/lib/src/posthog_flutter_platform_interface.dart b/posthog_flutter/lib/src/posthog_flutter_platform_interface.dart index 732f7b38..6921964c 100644 --- a/posthog_flutter/lib/src/posthog_flutter_platform_interface.dart +++ b/posthog_flutter/lib/src/posthog_flutter_platform_interface.dart @@ -187,6 +187,10 @@ abstract class PosthogFlutterPlatformInterface extends PlatformInterface { throw UnimplementedError('unregister() has not been implemented.'); } + /// Sets or, with `null`, clears the `$app_language` event property. Does + /// nothing by default, because [PosthogObserver] calls it during navigation. + Future setAppLanguage(String? language) async {} + Future isFeatureEnabled(String key, {bool? sendFeatureFlagEvent, bool? defaultValue}) { throw UnimplementedError('isFeatureEnabled() has not been implemented.'); diff --git a/posthog_flutter/lib/src/posthog_flutter_web_handler.dart b/posthog_flutter/lib/src/posthog_flutter_web_handler.dart index a52b4d08..c066fe16 100644 --- a/posthog_flutter/lib/src/posthog_flutter_web_handler.dart +++ b/posthog_flutter/lib/src/posthog_flutter_web_handler.dart @@ -515,6 +515,14 @@ Future handleWebMethodCall(MethodCall call) async { posthog?.unregister(stringToJSAny(key)); break; + case 'setAppLanguage': + final language = args['language'] as String?; + if (language == null) { + posthog?.unregister(stringToJSAny(r'$app_language')); + } else { + posthog?.register(mapToJSAny({r'$app_language': language})); + } + break; case 'getSessionId': final sessionId = posthog?.get_session_id()?.dartify() as String?; if (sessionId?.isEmpty == true) return null; diff --git a/posthog_flutter/lib/src/posthog_observer.dart b/posthog_flutter/lib/src/posthog_observer.dart index 540d686e..e001aa5e 100644 --- a/posthog_flutter/lib/src/posthog_observer.dart +++ b/posthog_flutter/lib/src/posthog_observer.dart @@ -105,6 +105,9 @@ class PosthogObserver extends RouteObserver> if (context != null) { _currentContext = context; SurveyService().onContextAvailable(); + Posthog().reportResolvedAppLanguage( + Localizations.maybeLocaleOf(context)?.toLanguageTag(), + ); } } diff --git a/posthog_flutter/test/posthog_desktop_context_test.dart b/posthog_flutter/test/posthog_desktop_context_test.dart index 5c71c4df..cc8e9bc8 100644 --- a/posthog_flutter/test/posthog_desktop_context_test.dart +++ b/posthog_flutter/test/posthog_desktop_context_test.dart @@ -73,21 +73,21 @@ void main() { }); }); - group('languageCodeOf', () { - test('reports the language without the region', () { - expect(languageCodeOf(const Locale('en', 'US')), 'en'); + group('localeTagOf', () { + test('reports the full language tag', () { + expect(localeTagOf(const Locale('en', 'US')), 'en-US'); expect( - languageCodeOf( + localeTagOf( const Locale.fromSubtags(languageCode: 'zh', scriptCode: 'Hans'), ), - 'zh', + 'zh-Hans', ); }); test('omits locales that name no language', () { - expect(languageCodeOf(const Locale.fromSubtags()), isNull); - expect(languageCodeOf(const Locale('C')), isNull); - expect(languageCodeOf(const Locale('POSIX')), isNull); + expect(localeTagOf(const Locale.fromSubtags()), isNull); + expect(localeTagOf(const Locale('C')), isNull); + expect(localeTagOf(const Locale('POSIX')), isNull); }); }); } diff --git a/posthog_flutter/test/posthog_flutter_desktop_test.dart b/posthog_flutter/test/posthog_flutter_desktop_test.dart index a1ec3bcd..69f92a57 100644 --- a/posthog_flutter/test/posthog_flutter_desktop_test.dart +++ b/posthog_flutter/test/posthog_flutter_desktop_test.dart @@ -248,6 +248,17 @@ void main() { expect(_propertiesOf(event), isNot(contains(r'$set'))); }); + test(r'sends $app_language', () async { + final server = await LocalPostHogServer.start(); + final platform = await setUpPlatform(configFor(server)); + + await platform.setAppLanguage('fr'); + await platform.capture(eventName: 'translated'); + + final event = await server.waitForEvent('translated'); + expect(_propertiesOf(event)[r'$app_language'], 'fr'); + }); + test(r'reports the platform language as $locale', () async { final server = await LocalPostHogServer.start(); final platform = await setUpPlatform(configFor(server)); @@ -257,7 +268,7 @@ void main() { final event = await server.waitForEvent('localized event'); expect( _propertiesOf(event)[r'$locale'], - PlatformDispatcher.instance.locale.languageCode, + PlatformDispatcher.instance.locale.toLanguageTag(), ); }); diff --git a/posthog_flutter/test/posthog_flutter_platform_interface_fake.dart b/posthog_flutter/test/posthog_flutter_platform_interface_fake.dart index 79183964..51affae7 100644 --- a/posthog_flutter/test/posthog_flutter_platform_interface_fake.dart +++ b/posthog_flutter/test/posthog_flutter_platform_interface_fake.dart @@ -115,6 +115,13 @@ class PosthogFlutterPlatformFake extends PosthogFlutterPlatformInterface { /// the session id, which happens while the call is still in flight. Future Function()? onSessionBoundaryCall; + final List appLanguageCalls = []; + + @override + Future setAppLanguage(String? language) async { + appLanguageCalls.add(language); + } + // Overridden because the base implementations throw UnimplementedError. @override Future reset() async { diff --git a/posthog_flutter/test/posthog_flutter_web_handler_test.dart b/posthog_flutter/test/posthog_flutter_web_handler_test.dart index 6af6d525..4831841f 100644 --- a/posthog_flutter/test/posthog_flutter_web_handler_test.dart +++ b/posthog_flutter/test/posthog_flutter_web_handler_test.dart @@ -6,8 +6,10 @@ import 'dart:js_interop_unsafe'; import 'package:flutter/services.dart'; import 'package:flutter_test/flutter_test.dart'; +import 'package:flutter_web_plugins/flutter_web_plugins.dart'; import 'package:posthog_flutter/posthog_flutter_web.dart'; import 'package:posthog_flutter/src/feature_flag_result.dart'; +import 'package:posthog_flutter/src/posthog_flutter_platform_interface.dart'; import 'package:posthog_flutter/src/posthog_flutter_web_handler.dart'; // Browser-only: handleWebMethodCall talks to the posthog-js instance on @@ -33,6 +35,69 @@ void main() { Map readOptions() => capturedOptions!.dartify()! as Map; + group('handleWebMethodCall setAppLanguage', () { + late List registered; + late List unregistered; + + setUp(() { + registered = []; + unregistered = []; + final fake = JSObject(); + fake.setProperty( + 'register'.toJS, + ((JSAny properties) { + registered.add(properties.dartify()); + }).toJS, + ); + fake.setProperty( + 'unregister'.toJS, + ((JSString key) { + unregistered.add(key.toDart); + }).toJS, + ); + globalContext.setProperty('posthog'.toJS, fake); + }); + + test('registers a language and unregisters null', () async { + final web = PosthogFlutterWeb(); + await web.setAppLanguage('de'); + await web.setAppLanguage(null); + + expect(registered, [ + {r'$app_language': 'de'} + ]); + expect(unregistered, [r'$app_language']); + }); + + test('registers the language again in the same step as reset', () { + final calls = []; + final fake = globalContext.getProperty('posthog'.toJS); + fake.setProperty('reset'.toJS, (() => calls.add('reset')).toJS); + fake.setProperty( + 'register'.toJS, + ((JSAny properties) => calls.add('register ${properties.dartify()}')) + .toJS, + ); + final web = PosthogFlutterWeb(); + web.setAppLanguage('de'); + calls.clear(); + + web.reset(); + + expect(calls, ['reset', r'register {$app_language: de}']); + }); + + test('registerWith clears the language persisted by a past launch', () { + TestWidgetsFlutterBinding.ensureInitialized(); + final previous = PosthogFlutterPlatformInterface.instance; + addTearDown(() => PosthogFlutterPlatformInterface.instance = previous); + + PosthogFlutterWeb.registerWith(webPluginRegistrar); + + expect(unregistered, [r'$app_language']); + }); + }); + group('handleWebMethodCall captureLog', () { test('remaps trace fields to snake_case for posthog-js', () async { await handleWebMethodCall(const MethodCall('captureLog', { diff --git a/posthog_flutter/test/posthog_observer_test.dart b/posthog_flutter/test/posthog_observer_test.dart index 17d3759f..26cb16f3 100644 --- a/posthog_flutter/test/posthog_observer_test.dart +++ b/posthog_flutter/test/posthog_observer_test.dart @@ -38,6 +38,72 @@ void main() { ); } + group('app language', () { + setUp(() async { + await Posthog().setAppLanguage(null); + await Posthog().reportResolvedAppLanguage(null); + fake.appLanguageCalls.clear(); + }); + + Widget app(Locale locale, GlobalKey navigator) => + WidgetsApp( + navigatorKey: navigator, + color: const Color(0xFF000000), + locale: locale, + supportedLocales: const [Locale('en'), Locale('de')], + localizationsDelegates: const [ + DefaultWidgetsLocalizations.delegate, + ], + localeResolutionCallback: (locale, supported) => supported.firstWhere( + (it) => it.languageCode == locale?.languageCode, + orElse: () => supported.first, + ), + navigatorObservers: [getSut()], + pageRouteBuilder: (settings, builder) => PageRouteBuilder( + settings: settings, + pageBuilder: (context, _, __) => builder(context), + ), + home: const SizedBox(), + ); + + testWidgets('reports the locale the app resolved, not the requested one', + (tester) async { + await tester.pumpWidget(app( + const Locale('fr', 'FR'), + GlobalKey(), + )); + + expect(fake.appLanguageCalls, ['en']); + }); + + testWidgets('picks up a language change on the next route', (tester) async { + final navigator = GlobalKey(); + await tester.pumpWidget(app(const Locale('en'), navigator)); + await tester.pumpWidget(app(const Locale('de'), navigator)); + await tester.pump(); + + navigator.currentState!.push(route(const RouteSettings(name: 'next'))); + await tester.pumpAndSettle(); + + expect(fake.appLanguageCalls, ['en', 'de']); + }); + + test('the value the app set wins over the resolved locale', () async { + await Posthog().setAppLanguage(' pt_BR '); + await Posthog().reportResolvedAppLanguage('en'); + await Posthog().setAppLanguage(null); + + expect(fake.appLanguageCalls, ['pt-BR', 'en']); + }); + + test('is sent again after setup', () async { + await Posthog().setAppLanguage('de'); + await Posthog().setup(PostHogConfig('phc_test')); + + expect(fake.appLanguageCalls, ['de', 'de']); + }); + }); + test('preserves WidgetsBindingObserver compatibility', () { expect(getSut(), isA()); });