tacilytics 0.0.0-stage → 2.0.2

package/sdk/flutter/README.md

@@ -0,0 +1,41 @@
+# tacilytics (Flutter)
+
+Privacy-first, cookieless app analytics for [Tacilytics](https://github.com/Open-Cosmic-Software/tacilytics).
+Screen views, goals, in-app search and revenue land in the same dashboard as your website, filterable by platform.
+
+- **Off by default.** Nothing is sent until `setEnabled(true)`, so you can wire it to your consent.
+- **No device id, no advertising id, no cookies.** One random id per app launch, kept in memory only.
+- **Fire-and-forget.** Never throws into your app, never blocks the UI.
+
+```yaml
+dependencies:
+  tacilytics:
+    git:
+      url: https://github.com/Open-Cosmic-Software/tacilytics
+      path: sdk/flutter
+```
+
+```dart
+void main() {
+  Tacilytics.init(endpoint: 'https://analytics.example.com', domain: 'example.com', appVersion: '1.4.0');
+  runApp(MaterialApp(navigatorObservers: [TacilyticsRouteObserver()], home: const Home()));
+}
+
+// after your consent dialog
+Tacilytics.instance.setEnabled(accepted);
+
+Tacilytics.instance.screen('/product/42');            // manual screen view
+Tacilytics.instance.event('Signup', {'plan': 'pro'});  // goal with properties
+Tacilytics.instance.search('vinegar', 6);              // 0 results show up under "No results"
+Tacilytics.instance.purchase(value: 49.90, items: 2);  // revenue — never pass customer data
+Tacilytics.instance.setCampaign(source: 'newsletter'); // e.g. from a deep link
+```
+
+Use the same `domain` as your website to see web and app side by side. On Flutter web the client stays silent; use the `tacilytics.js` tag there.
+
+Tests: `flutter test` (unit) · `TACILYTICS_E2E=http://localhost:3920 flutter test --tags e2e --run-skipped` (against a running server).
+
+MIT licensed.
+
+## Upgrading from `nyx_analytics`
+Rename the dependency to `tacilytics` and import `package:tacilytics/tacilytics.dart`. If you can't change your code yet, import `package:tacilytics/nyx_analytics.dart`: `NyxAnalytics`, `NyxBeacon` and `NyxRouteObserver` still work as deprecated aliases.

package/sdk/flutter/dart_test.yaml

@@ -0,0 +1,3 @@
+tags:
+  e2e:
+    skip: "live server test — run with TACILYTICS_E2E=<url> flutter test --tags e2e --run-skipped"

package/sdk/flutter/lib/nyx_analytics.dart

@@ -0,0 +1,13 @@
+/// Deprecated entry point from before the rename to Tacilytics.
+/// Import `package:tacilytics/tacilytics.dart` instead; these aliases will be removed in a later major version.
+library nyx_analytics;
+
+import 'tacilytics.dart';
+export 'tacilytics.dart';
+
+@Deprecated('Use Tacilytics')
+typedef NyxAnalytics = Tacilytics;
+@Deprecated('Use TacilyticsBeacon')
+typedef NyxBeacon = TacilyticsBeacon;
+@Deprecated('Use TacilyticsRouteObserver')
+typedef NyxRouteObserver = TacilyticsRouteObserver;

package/sdk/flutter/lib/src/beacon.dart

@@ -0,0 +1,87 @@
+import 'dart:math';
+
+/// Builds the JSON body for `POST /api/collect`. Pure functions, no I/O — fully unit-testable.
+///
+/// Wire format (shared with the web tracker, plus the app-only fields):
+///   d   site domain              p   path / screen name
+///   n   event name (optional)    pr  event properties (flat, scalars only)
+///   pf  platform: android|ios|macos|windows|linux
+///   av  app version              dv  mobile|tablet|desktop
+///   l   language (de-AT)         cc  2-letter region of the device locale
+///   sid random per-launch id (never persisted, never a device id)
+///   s / um / uc  utm source / medium / campaign (e.g. from a deep link)
+class TacilyticsBeacon {
+  TacilyticsBeacon._();
+
+  static const _sidChars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+
+  /// A fresh random session id: 24 chars, cryptographically random. Lives only in memory.
+  static String newSessionId([Random? rnd]) {
+    final r = rnd ?? Random.secure();
+    return List.generate(24, (_) => _sidChars[r.nextInt(_sidChars.length)]).join();
+  }
+
+  /// Normalises a screen name into a path: `ProductPage` stays, `product/42` → `/product/42`.
+  static String path(String screen) {
+    var p = screen.trim();
+    if (p.isEmpty) return '/';
+    if (!p.startsWith('/')) p = '/$p';
+    if (p.length > 1 && p.endsWith('/')) p = p.substring(0, p.length - 1);
+    return p.length > 512 ? p.substring(0, 512) : p;
+  }
+
+  /// Properties are flat key → scalar. Nested values and nulls are dropped, max 12 keys,
+  /// everything stringified — the same rules the server enforces, so nothing is silently lost twice.
+  static Map<String, String>? props(Map<String, Object?>? raw) {
+    if (raw == null || raw.isEmpty) return null;
+    final out = <String, String>{};
+    for (final e in raw.entries) {
+      if (out.length >= 12) break;
+      final v = e.value;
+      if (v == null || v is Map || v is Iterable) continue;
+      final k = e.key.trim();
+      if (k.isEmpty) continue;
+      final s = v is double ? _num(v) : v.toString();
+      out[k.length > 40 ? k.substring(0, 40) : k] = s.length > 80 ? s.substring(0, 80) : s;
+    }
+    return out.isEmpty ? null : out;
+  }
+
+  static String _num(double v) => v == v.roundToDouble() ? v.toStringAsFixed(0) : v.toStringAsFixed(2);
+
+  static Map<String, Object> build({
+    required String domain,
+    required String platform,
+    required String sessionId,
+    required String screen,
+    String? name,
+    Map<String, Object?>? properties,
+    String? appVersion,
+    String? device,
+    String? language,
+    String? region,
+    String? utmSource,
+    String? utmMedium,
+    String? utmCampaign,
+  }) {
+    final body = <String, Object>{
+      'd': domain,
+      'p': path(screen),
+      'pf': platform,
+      'sid': sessionId,
+    };
+    if (name != null && name.trim().isNotEmpty) {
+      body['n'] = name.trim();
+      final pr = props(properties);
+      if (pr != null) body['pr'] = pr;
+    }
+    if (appVersion != null && appVersion.isNotEmpty) body['av'] = appVersion;
+    if (device != null) body['dv'] = device;
+    if (language != null && language.isNotEmpty) body['l'] = language;
+    if (region != null && RegExp(r'^[A-Za-z]{2}$').hasMatch(region)) body['cc'] = region.toUpperCase();
+    if (utmSource != null && utmSource.isNotEmpty) body['s'] = utmSource;
+    if (utmMedium != null && utmMedium.isNotEmpty) body['um'] = utmMedium;
+    if (utmCampaign != null && utmCampaign.isNotEmpty) body['uc'] = utmCampaign;
+    return body;
+  }
+}

package/sdk/flutter/lib/src/client.dart

@@ -0,0 +1,177 @@
+import 'dart:async';
+import 'dart:convert';
+
+import 'package:flutter/foundation.dart';
+import 'package:flutter/widgets.dart';
+import 'package:http/http.dart' as http;
+
+import 'beacon.dart';
+
+/// The client. One instance per app; call [Tacilytics.init] once at start-up.
+///
+/// Privacy by design:
+/// * **Off until you call [setEnabled]`(true)`** — wire it to your consent banner.
+/// * No device id, no advertising id, no cookies. A random session id is drawn per app
+///   launch, kept in memory only, and the server hashes it with a daily salt.
+/// * Region comes from the device locale, never from IP geolocation.
+/// * Fire-and-forget: tracking never throws into your app and never blocks the UI.
+class Tacilytics {
+  Tacilytics._(this.endpoint, this.domain, this.appVersion, this._client, this._platform);
+
+  static Tacilytics? _instance;
+
+  /// The configured client. Throws if [init] was not called.
+  static Tacilytics get instance {
+    final i = _instance;
+    if (i == null) throw StateError('Tacilytics.init() must be called first');
+    return i;
+  }
+
+  /// Configure once. [endpoint] is your Tacilytics server URL, [domain] the site as registered there
+  /// (use the same one as your website to see web + app side by side, filterable by platform).
+  static Tacilytics init({
+    required String endpoint,
+    required String domain,
+    String? appVersion,
+    bool enabled = false,
+    http.Client? client,
+    String? platformOverride,
+  }) {
+    final base = endpoint.endsWith('/') ? endpoint.substring(0, endpoint.length - 1) : endpoint;
+    final i = Tacilytics._(base, domain, appVersion, client ?? http.Client(), platformOverride ?? _detectPlatform());
+    i._enabled = enabled;
+    _instance = i;
+    return i;
+  }
+
+  final String endpoint;
+  final String domain;
+  final String? appVersion;
+  final http.Client _client;
+  final String? _platform;
+  final String _sid = TacilyticsBeacon.newSessionId();
+  bool _enabled = false;
+  String? _lastScreen;
+  String? _utmSource, _utmMedium, _utmCampaign;
+
+  bool get enabled => _enabled;
+
+  /// Turn tracking on/off, e.g. from your consent dialog. Off = nothing leaves the device.
+  void setEnabled(bool on) => _enabled = on;
+
+  /// Attribute this launch to a campaign (e.g. read from a deep link's utm_* parameters).
+  void setCampaign({String? source, String? medium, String? campaign}) {
+    _utmSource = source;
+    _utmMedium = medium;
+    _utmCampaign = campaign;
+  }
+
+  /// A screen view — the app equivalent of a pageview.
+  Future<void> screen(String name) {
+    _lastScreen = TacilyticsBeacon.path(name);
+    return _send(screen: name);
+  }
+
+  /// A custom event / goal, attached to the current screen.
+  Future<void> event(String name, [Map<String, Object?>? properties]) =>
+      _send(screen: _lastScreen ?? '/', name: name, properties: properties);
+
+  /// A completed order. Shows up in the revenue panels (by source and by platform).
+  /// Never pass customer data or order numbers.
+  Future<void> purchase({required double value, String currency = 'EUR', double? net, int? items}) =>
+      event('Purchase', {
+        'value': value,
+        'currency': currency,
+        if (net != null) 'net': net,
+        if (items != null) 'items': items,
+      });
+
+  /// An in-app search with its result count (0 shows up under "No results").
+  Future<void> search(String query, int results) => event('Search', {'q': query, 'results': results});
+
+  Future<void> _send({required String screen, String? name, Map<String, Object?>? properties}) async {
+    final pf = _platform;
+    if (!_enabled || pf == null) return; // web builds: use the tacilytics.js tracker instead
+    final locale = PlatformDispatcher.instance.locale;
+    final body = TacilyticsBeacon.build(
+      domain: domain,
+      platform: pf,
+      sessionId: _sid,
+      screen: screen,
+      name: name,
+      properties: properties,
+      appVersion: appVersion,
+      device: _deviceClass(),
+      language: locale.toLanguageTag(),
+      region: locale.countryCode,
+      utmSource: _utmSource,
+      utmMedium: _utmMedium,
+      utmCampaign: _utmCampaign,
+    );
+    try {
+      await _client
+          .post(
+            Uri.parse('$endpoint/api/collect'),
+            headers: {'Content-Type': 'application/json', 'User-Agent': 'Tacilytics-Flutter/0.2 ($pf)'},
+            body: jsonEncode(body),
+          )
+          .timeout(const Duration(seconds: 10));
+    } catch (_) {
+      // analytics must never break the app — a lost beacon is acceptable
+    }
+  }
+
+  static String? _detectPlatform() {
+    if (kIsWeb) return null;
+    switch (defaultTargetPlatform) {
+      case TargetPlatform.android:
+        return 'android';
+      case TargetPlatform.iOS:
+        return 'ios';
+      case TargetPlatform.macOS:
+        return 'macos';
+      case TargetPlatform.windows:
+        return 'windows';
+      case TargetPlatform.linux:
+        return 'linux';
+      default:
+        return null;
+    }
+  }
+
+  /// Phone vs. tablet from the logical screen size (shortest side ≥ 600 dp = tablet).
+  static String _deviceClass() {
+    final views = PlatformDispatcher.instance.views;
+    if (views.isEmpty) return 'mobile';
+    final v = views.first;
+    final size = v.physicalSize / v.devicePixelRatio;
+    final pf = defaultTargetPlatform;
+    if (pf == TargetPlatform.macOS || pf == TargetPlatform.windows || pf == TargetPlatform.linux) return 'desktop';
+    return size.shortestSide >= 600 ? 'tablet' : 'mobile';
+  }
+}
+
+/// Optional: track screen views automatically —
+/// `MaterialApp(navigatorObservers: [TacilyticsRouteObserver()])`.
+/// Uses the route's `settings.name`; unnamed routes (dialogs, sheets) are skipped.
+class TacilyticsRouteObserver extends NavigatorObserver {
+  TacilyticsRouteObserver({this.nameOf});
+
+  /// Map a route to a screen name, e.g. to strip ids. Return null to skip the route.
+  final String? Function(Route<dynamic> route)? nameOf;
+
+  void _track(Route<dynamic>? route) {
+    if (route == null || Tacilytics._instance == null) return;
+    final name = nameOf != null ? nameOf!(route) : route.settings.name;
+    if (name != null && name.isNotEmpty) Tacilytics.instance.screen(name);
+  }
+
+  @override
+  void didPush(Route<dynamic> route, Route<dynamic>? previousRoute) => _track(route);
+
+  @override
+  void didReplace({Route<dynamic>? newRoute, Route<dynamic>? oldRoute}) => _track(newRoute);
+
+  @override
+  void didPop(Route<dynamic> route, Route<dynamic>? previousRoute) => _track(previousRoute);
+}

package/sdk/flutter/lib/tacilytics.dart

@@ -0,0 +1,13 @@
+/// Tacilytics for Flutter — privacy-first, cookieless app analytics.
+/// (tacit: we count, we don't tell.)
+///
+/// ```dart
+/// Tacilytics.init(endpoint: 'https://analytics.example.com', domain: 'example.com');
+/// Tacilytics.instance.setEnabled(userConsented);   // nothing is sent before this
+/// Tacilytics.instance.screen('/product/42');
+/// Tacilytics.instance.purchase(value: 49.90, currency: 'EUR');
+/// ```
+library tacilytics;
+
+export 'src/client.dart';
+export 'src/beacon.dart';

package/sdk/flutter/pubspec.lock

@@ -0,0 +1,221 @@
+# Generated by pub
+# See https://dart.dev/tools/pub/glossary#lockfile
+packages:
+  async:
+    dependency: transitive
+    description:
+      name: async
+      sha256: "947bfcf187f74dbc5e146c9eb9c0f10c9f8b30743e341481c1e2ed3ecc18c20c"
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.11.0"
+  boolean_selector:
+    dependency: transitive
+    description:
+      name: boolean_selector
+      sha256: "6cfb5af12253eaf2b368f07bacc5a80d1301a071c73360d746b7f2e32d762c66"
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.1.1"
+  characters:
+    dependency: transitive
+    description:
+      name: characters
+      sha256: "04a925763edad70e8443c99234dc3328f442e811f1d8fd1a72f1c8ad0f69a605"
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.3.0"
+  clock:
+    dependency: transitive
+    description:
+      name: clock
+      sha256: cb6d7f03e1de671e34607e909a7213e31d7752be4fb66a86d29fe1eb14bfb5cf
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.1.1"
+  collection:
+    dependency: transitive
+    description:
+      name: collection
+      sha256: a1ace0a119f20aabc852d165077c036cd864315bd99b7eaa10a60100341941bf
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.19.0"
+  fake_async:
+    dependency: transitive
+    description:
+      name: fake_async
+      sha256: "511392330127add0b769b75a987850d136345d9227c6b94c96a04cf4a391bf78"
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.3.1"
+  flutter:
+    dependency: "direct main"
+    description: flutter
+    source: sdk
+    version: "0.0.0"
+  flutter_test:
+    dependency: "direct dev"
+    description: flutter
+    source: sdk
+    version: "0.0.0"
+  http:
+    dependency: "direct main"
+    description:
+      name: http
+      sha256: "87721a4a50b19c7f1d49001e51409bddc46303966ce89a65af4f4e6004896412"
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.6.0"
+  http_parser:
+    dependency: transitive
+    description:
+      name: http_parser
+      sha256: "178d74305e7866013777bab2c3d8726205dc5a4dd935297175b19a23a2e66571"
+      url: "https://pub.dev"
+    source: hosted
+    version: "4.1.2"
+  leak_tracker:
+    dependency: transitive
+    description:
+      name: leak_tracker
+      sha256: "7bb2830ebd849694d1ec25bf1f44582d6ac531a57a365a803a6034ff751d2d06"
+      url: "https://pub.dev"
+    source: hosted
+    version: "10.0.7"
+  leak_tracker_flutter_testing:
+    dependency: transitive
+    description:
+      name: leak_tracker_flutter_testing
+      sha256: "9491a714cca3667b60b5c420da8217e6de0d1ba7a5ec322fab01758f6998f379"
+      url: "https://pub.dev"
+    source: hosted
+    version: "3.0.8"
+  leak_tracker_testing:
+    dependency: transitive
+    description:
+      name: leak_tracker_testing
+      sha256: "6ba465d5d76e67ddf503e1161d1f4a6bc42306f9d66ca1e8f079a47290fb06d3"
+      url: "https://pub.dev"
+    source: hosted
+    version: "3.0.1"
+  matcher:
+    dependency: transitive
+    description:
+      name: matcher
+      sha256: d2323aa2060500f906aa31a895b4030b6da3ebdcc5619d14ce1aada65cd161cb
+      url: "https://pub.dev"
+    source: hosted
+    version: "0.12.16+1"
+  material_color_utilities:
+    dependency: transitive
+    description:
+      name: material_color_utilities
+      sha256: f7142bb1154231d7ea5f96bc7bde4bda2a0945d2806bb11670e30b850d56bdec
+      url: "https://pub.dev"
+    source: hosted
+    version: "0.11.1"
+  meta:
+    dependency: transitive
+    description:
+      name: meta
+      sha256: bdb68674043280c3428e9ec998512fb681678676b3c54e773629ffe74419f8c7
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.15.0"
+  path:
+    dependency: transitive
+    description:
+      name: path
+      sha256: "087ce49c3f0dc39180befefc60fdb4acd8f8620e5682fe2476afd0b3688bb4af"
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.9.0"
+  sky_engine:
+    dependency: transitive
+    description: flutter
+    source: sdk
+    version: "0.0.0"
+  source_span:
+    dependency: transitive
+    description:
+      name: source_span
+      sha256: "53e943d4206a5e30df338fd4c6e7a077e02254531b138a15aec3bd143c1a8b3c"
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.10.0"
+  stack_trace:
+    dependency: transitive
+    description:
+      name: stack_trace
+      sha256: "9f47fd3630d76be3ab26f0ee06d213679aa425996925ff3feffdec504931c377"
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.12.0"
+  stream_channel:
+    dependency: transitive
+    description:
+      name: stream_channel
+      sha256: ba2aa5d8cc609d96bbb2899c28934f9e1af5cddbd60a827822ea467161eb54e7
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.1.2"
+  string_scanner:
+    dependency: transitive
+    description:
+      name: string_scanner
+      sha256: "688af5ed3402a4bde5b3a6c15fd768dbf2621a614950b17f04626c431ab3c4c3"
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.3.0"
+  term_glyph:
+    dependency: transitive
+    description:
+      name: term_glyph
+      sha256: a29248a84fbb7c79282b40b8c72a1209db169a2e0542bce341da992fe1bc7e84
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.2.1"
+  test_api:
+    dependency: transitive
+    description:
+      name: test_api
+      sha256: "664d3a9a64782fcdeb83ce9c6b39e78fd2971d4e37827b9b06c3aa1edc5e760c"
+      url: "https://pub.dev"
+    source: hosted
+    version: "0.7.3"
+  typed_data:
+    dependency: transitive
+    description:
+      name: typed_data
+      sha256: f9049c039ebfeb4cf7a7104a675823cd72dba8297f264b6637062516699fa006
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.4.0"
+  vector_math:
+    dependency: transitive
+    description:
+      name: vector_math
+      sha256: "80b3257d1492ce4d091729e3a67a60407d227c27241d6927be0130c98e741803"
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.1.4"
+  vm_service:
+    dependency: transitive
+    description:
+      name: vm_service
+      sha256: f6be3ed8bd01289b34d679c2b62226f63c0e69f9fd2e50a6b3c1c729a961041b
+      url: "https://pub.dev"
+    source: hosted
+    version: "14.3.0"
+  web:
+    dependency: transitive
+    description:
+      name: web
+      sha256: "868d88a33d8a87b18ffc05f9f030ba328ffefba92d6c127917a2ba740f9cfe4a"
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.1.1"
+sdks:
+  dart: ">=3.5.0 <4.0.0"
+  flutter: ">=3.18.0-18.0.pre.54"

package/sdk/flutter/pubspec.yaml

@@ -0,0 +1,18 @@
+name: tacilytics
+description: Privacy-first, cookieless app analytics for Tacilytics. No device id, no cookies, consent-aware.
+version: 0.2.0
+homepage: https://github.com/Open-Cosmic-Software/tacilytics
+repository: https://github.com/Open-Cosmic-Software/tacilytics/tree/master/sdk/flutter
+
+environment:
+  sdk: ">=3.0.0 <4.0.0"
+  flutter: ">=3.10.0"
+
+dependencies:
+  flutter:
+    sdk: flutter
+  http: ">=0.13.0 <2.0.0"
+
+dev_dependencies:
+  flutter_test:
+    sdk: flutter

package/sdk/flutter/test/alias_test.dart

@@ -0,0 +1,13 @@
+// ignore_for_file: deprecated_member_use_from_same_package
+import 'package:flutter_test/flutter_test.dart';
+import 'package:tacilytics/nyx_analytics.dart';
+
+void main() {
+  test('old Nyx names still work after the rename', () async {
+    final c = NyxAnalytics.init(endpoint: 'http://127.0.0.1:9', domain: 'x.com', platformOverride: 'android');
+    expect(identical(c, Tacilytics.instance), isTrue);
+    expect(NyxBeacon.path('home'), '/home');
+    expect(NyxRouteObserver(), isA<TacilyticsRouteObserver>());
+    await c.screen('/home'); // disabled by default → returns quietly
+  });
+}

package/sdk/flutter/test/beacon_test.dart

@@ -0,0 +1,46 @@
+import 'dart:math';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:tacilytics/tacilytics.dart';
+
+void main() {
+  test('screen names become paths', () {
+    expect(TacilyticsBeacon.path('product/42'), '/product/42');
+    expect(TacilyticsBeacon.path('/cart/'), '/cart');
+    expect(TacilyticsBeacon.path('  '), '/');
+  });
+
+  test('session id is random, 24 url-safe chars', () {
+    final a = TacilyticsBeacon.newSessionId(Random(1)), b = TacilyticsBeacon.newSessionId(Random(2));
+    expect(a.length, 24);
+    expect(RegExp(r'^[A-Za-z0-9]+$').hasMatch(a), isTrue);
+    expect(a, isNot(b));
+  });
+
+  test('properties are flat scalars, nested and null dropped', () {
+    final p = TacilyticsBeacon.props({'value': 49.9, 'items': 2, 'whole': 10.0, 'nested': {'a': 1}, 'list': [1], 'none': null});
+    expect(p, {'value': '49.90', 'items': '2', 'whole': '10'});
+  });
+
+  test('build: pageview has no event fields, event carries props', () {
+    final pv = TacilyticsBeacon.build(domain: 'x.com', platform: 'android', sessionId: 's' * 24, screen: 'home', region: 'at');
+    expect(pv['p'], '/home');
+    expect(pv['cc'], 'AT');
+    expect(pv.containsKey('n'), isFalse);
+    expect(pv.containsKey('pr'), isFalse);
+    final ev = TacilyticsBeacon.build(domain: 'x.com', platform: 'ios', sessionId: 's' * 24, screen: '/cart', name: 'Purchase', properties: {'value': 12.5});
+    expect(ev['n'], 'Purchase');
+    expect(ev['pr'], {'value': '12.50'});
+  });
+
+  test('invalid region is not sent', () {
+    final b = TacilyticsBeacon.build(domain: 'x.com', platform: 'ios', sessionId: 's' * 24, screen: '/', region: '419');
+    expect(b.containsKey('cc'), isFalse);
+  });
+
+  test('client sends nothing until enabled', () async {
+    final c = Tacilytics.init(endpoint: 'http://127.0.0.1:9', domain: 'x.com', platformOverride: 'android');
+    expect(c.enabled, isFalse);
+    await c.screen('/home'); // must return quietly, no network attempt
+  });
+}

package/sdk/flutter/test/e2e_test.dart

@@ -0,0 +1,18 @@
+@Tags(['e2e'])
+library;
+
+import 'dart:io';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:tacilytics/tacilytics.dart';
+
+// Runs against a live server: TACILYTICS_E2E=http://127.0.0.1:3999 flutter test --tags e2e
+void main() {
+  final url = Platform.environment['TACILYTICS_E2E'];
+  test('beacons reach a running server', () async {
+    final c = Tacilytics.init(endpoint: url!, domain: 'pastaclean.tv', appVersion: '9.9.9-e2e', platformOverride: 'android', enabled: true);
+    await c.screen('/e2e/home');
+    await c.search('essig', 6);
+    await c.purchase(value: 12.5, items: 1);
+  }, skip: url == null ? 'set TACILYTICS_E2E' : false);
+}