feat(analytics): Tracking takes the Analytics service; start() replaces enableAllAutoTracking

[lohanidamodar]

What does this PR do?

Review asked that the tracking helper take the analytics service directly:

new Tracking(new Analytics(client), '<PROPERTY_ID>').start();

Before this, the helpers took an emitter callback. Every caller hand-wrote the same adapter to createEvent: pass the required url, and flatten props into the alternating key/value list the endpoint takes. That adapter now lives inside the helper, which is built from the generated service and the property id the events path requires.

Renames

Platform	Before	After
Web	new AnalyticsTracking(emitter, options?)	new Tracking(analytics, propertyId, options?)
Web	AnalyticsTrackingOptions	TrackingOptions
Web	AnalyticsEventOptions	TrackingEventOptions
Web	AnalyticsEventEmitter	removed
Web	enableAllAutoTracking()	start()
Flutter	AnalyticsTracking(emitter)	Tracking(analytics, propertyId, {url})
Flutter	AnalyticsObserver(...)	TrackingObserver(tracking)
Flutter	AnalyticsEventEmitter	removed
Flutter	enableAllAutoTracking()	start()
Flutter	lib/src/analytics_tracking.dart, lib/src/analytics_observer.dart	lib/src/tracking.dart, lib/src/tracking_observer.dart

The granular enableAuto* / disableAuto* methods are unchanged. start() turns on the same set enableAllAutoTracking() did:

• Web: pageviews, outbound links, scroll depth and engagement time. Downloads stay opt-in through enableAutoDownloadTracking(), because the list of file extensions depends on the app.
• Flutter: app-lifecycle events. Route tracking stays opt-in through TrackingObserver.

The observer keeps the Tracking prefix because a bare Observer reads as a NavigatorObserver. It takes the Tracking instance, so the property id and base url are configured once.

Flutter URLs

The endpoint only accepts absolute URLs. Screen names now resolve against a base url: the page origin on Flutter web, and app://<platform> everywhere else. Pass url: to the constructor to override it.

Gating

The requires: analytics gating from #1977 is unchanged. GenerationTest::testAnalyticsCompanionsFollowTheService still generates against a spec without the analytics service, and confirms the helpers are left out there and shipped when the service is present.

Compatibility

This is a breaking change for published prereleases. The following ship AnalyticsTracking and enableAllAutoTracking(), and code written against them will not compile on an SDK generated from this branch:

• npm appwrite@28.2.0-rc.4 (checked from the registry tarball)
• npm @appwrite.io/console@18.3.0-rc.2 (checked from the registry tarball)
• pub appwrite@27.1.0-rc.1 and appwrite@27.1.0-rc.4, which ship lib/src/analytics_tracking.dart and lib/src/analytics_observer.dart. I checked the archives downloaded from pub.dev. 27.1.0-rc.2, -rc.3 and -rc.7 have no analytics service, so they ship no helpers. No older pub prerelease ships them.

We accept this because these are all prereleases and the only consumer we know of is our own.

Coupled change: refetch

refetch (refetch-io/refetch) pins appwrite@28.2.0-rc.4. Its lib/analytics.ts uses AnalyticsTracking with the emitter, so refetch must be updated at the same time as the first SDK release that includes this change. A follow-up refetch PR will switch it to new Tracking(analytics, propertyId).start() plus enableAutoDownloadTracking().

Test Plan

• vendor/bin/phpunit tests/generation/GenerationTest.php: 95 tests and 1245 assertions pass. 4 tests are skipped, all for languages with nothing to check (for example, cli declares no enums).
• Web (php example.php web client, real 2.3.x spec with the analytics service): npm ci, format:check, lint, analyse (tsc --noEmit) and build all pass.
• Flutter (php example.php flutter client, Flutter 3.47.1):
  • flutter analyze lib/src/tracking.dart lib/src/tracking_observer.dart reports no issues in either file.
  • Across the full package, flutter analyze reports no errors. Every warning and info it reports comes from existing generated code or tests, none from these files.
  • dart format --set-exit-if-changed leaves the tracking files unchanged.
• composer lint and composer refactor:check (Rector) pass.

Related PRs and Issues

• fix(analytics): address the Flutter SDK review on the tracking helpers #1977

[hansi-codes]

🟢 Tier S · Ready to merge

The tracking helpers now accept the generated Analytics service and property ID directly, with start() as the default auto-tracking entry point. Flutter route observation and event URLs are wired through the shared tracker, and generated exports and gating checks use the renamed helpers.

Verdict	New comments	Fixed	Still open
✅ Approved	0	0	0

📂 Walkthrough · 7

File	Change
src/SDK/Language/Flutter.php	Registers the renamed Flutter tracking templates and generated file paths.
templates/flutter/lib/package.dart.twig	Exports the Tracking helper and TrackingObserver when Analytics is available.
templates/flutter/lib/src/tracking.dart.twig	Sends lifecycle and manual events through Analytics and resolves event URLs against a configured base.
templates/flutter/lib/src/tracking_observer.dart.twig	Routes screen-view events through a shared Tracking instance.
templates/web/src/index.ts.twig	Exports Tracking and its renamed option types.
templates/web/src/services/analytics-tracking.ts.twig	Uses the generated Analytics service for event requests and renames the default startup method to start().
tests/generation/GenerationTest.php	Updates the companion-file gating assertions for the renamed Flutter tracking files.

---

_{Reviewed 5724413 · Details · Comment @hansi-codes review to re-run, or mention @hansi-codes with a question.}

[hansi-codes]

🟢 Tier S · Looks good to merge. Summary