@thinkingai/ae-cli 6.1.19 → 6.1.21

package/skills/ae-migrate-tracking-code/references/providers/README.md

@@ -0,0 +1,58 @@
+# Provider Adapter Contract
+
+> **Terminology**: 适配器 = adapter | 识别模式 = recognition pattern | 映射 = mapping | 依赖标识 = dependency identifier | 自动采集 = auto-track | 保留字 = reserved word/prefix
+
+A provider adapter is a single Markdown file `references/providers/<provider>.md`. It carries **only** the provider-specific knowledge the migration engine needs. The core algorithm lives in `mapping-framework.md` and must stay provider-agnostic.
+
+## How to add a new provider
+
+1. Copy `firebase.md` as a template.
+2. Fill every section below.
+3. Add one row to the Provider Registry table in `SKILL.md`.
+4. Do **not** modify `SKILL.md` phases or `mapping-framework.md`.
+
+## Required sections
+
+### 1. Recognition
+
+How to detect the provider and pin its version variant. Include:
+
+- Import / dependency signatures (web, Android, iOS, Flutter/RN where relevant).
+- The exact call signatures for each call kind (event / identity / user property).
+- Version variants and how to tell them apart (e.g. Firebase v8 namespaced vs v9 modular; Amplitude legacy `getInstance().logEvent` vs 2.x `amplitude.track`).
+
+### 2. Event mapping rules
+
+- The event call → AE `track()` shape.
+- Event-name constraints (max length, allowed charset, must start with letter) and reserved prefixes that must be stripped or renamed before snake_case conversion.
+- Params/properties: max count, max name/value length, and how non-literal values (variables) are resolved.
+- How source auto-track events are treated (mapped to AE `ta_*` switches or dropped).
+
+### 3. Identity mapping
+
+Source identity call(s) → AE `login(accountId)`. Note length limits and whether multiple identifiers exist (user id vs group id).
+
+### 4. User property mapping
+
+Source user-property operations → AE user property methods. Use this table shape:
+
+| Source operation | AE method | Notes |
+|---|---|---|
+| `setUserProperty(k, v)` | `user_set` | overwrite |
+
+Cover `user_set` / `user_setOnce` / `user_add` / `user_append` / `user_unset` equivalents, and group-identify handling (AE has no direct group concept — mark `needs decision`).
+
+### 5. Auto-track decision
+
+Which source auto-collected events exist, and whether each maps to an AE auto-track event or is dropped. AE auto-track events must match `ae-generate-tracking-plan`'s autotrack list (`ta_app_install`, `ta_app_start`, `ta_page_show`, ...).
+
+### 6. Dependency identifiers
+
+Package/module names used to add or remove the source SDK:
+
+- `add` mode: AE SDK dependency (resolved via the AE wiki, not here).
+- `switch` mode: source SDK identifiers to remove (e.g. `firebase/analytics`, `@amplitude/analytics-browser`), split by platform.
+
+### 7. Official docs
+
+Authoritative links for the adapter author and for the user when manual confirmation is needed (never fetched at runtime; the agent reads this adapter, not the remote site).

package/skills/ae-migrate-tracking-code/references/providers/amplitude.md

@@ -0,0 +1,208 @@
+# Amplitude Adapter
+
+> **Terminology**: 事件 = event | 属性 = event property / user property | 用户 ID = user id | 分组 = group | Identify 操作 = Identify operation | 自动采集 = auto-track
+
+## 1. Recognition
+
+Official Amplitude SDKs (verified against `docs.developers.amplitude.com`): **Browser (2.x)**, **Web legacy (`amplitude-js`)**, **Node.js**, **Python**, **Go**, **Java**, **Android (Kotlin)**, **iOS (Swift)**, **React Native**, **Flutter**, **Unity**. Amplitude has **no official Ruby / .NET / PHP SDK** (those are community projects — do not treat them as first-party).
+
+### Web legacy (`amplitude-js`)
+
+| Call kind | Signature |
+|---|---|
+| event | `amplitude.getInstance().logEvent('EVENT_NAME', { prop: value })` |
+| identity | `amplitude.getInstance().setUserId('id')` |
+| user props | `amplitude.getInstance().setUserProperties({ k: v })` |
+| identify | `amplitude.getInstance().identify(new amplitude.Identify().set('k', v).add('k', n).setOnce('k', v))` |
+| group | `amplitude.getInstance().setGroup('groupType', 'groupName')` |
+
+### Browser 2.x (`@amplitude/analytics-browser`)
+
+| Call kind | Signature |
+|---|---|
+| init | `amplitude.init(API_KEY, user_id?, options?)` |
+| event | `amplitude.track('event_name', { prop: value })` (legacy `logEvent` deprecated) |
+| identity | `amplitude.setUserId('id')` / `setDeviceId('id')` / `setSessionId(ms)` / `setIdentity(idObj)` |
+| identify | `amplitude.identify(new Identify().set('k', v).add('k', n).setOnce('k', v).append('k', v).prepend('k', v).postInsert('k', v).remove('k', v).unset('k').clearAll())` |
+| group | `amplitude.setGroup('groupType', 'groupName')` / `groupIdentify('groupType', 'groupName', identify)` |
+| revenue | `const rev = new Revenue().setPrice(9.99).setProductId('id'); amplitude.revenue(rev)` |
+| opt out | `amplitude.setOptOut(bool)` / `getOptOut()` |
+| flush / reset | `amplitude.flush()` / `reset()` / `extendSession()` |
+| others | `amplitude.remove()` (wipe local data), `trackVideo(...)`, `setTransport(...)`, `createInstance()` |
+
+### React Native (`@amplitude/analytics-react-native`)
+
+| Call kind | Signature |
+|---|---|
+| init | `amplitude.init(API_KEY)` |
+| event | `amplitude.logEvent('event_name', { prop: value })` — **RN uses `logEvent`, not `track`** |
+| identity | `amplitude.setUserId('id')` |
+| user props | `amplitude.setUserProperties({ k: v })` |
+| identify | `amplitude.identify(new Identify().set('k', v).add('k', n))` |
+| group | `amplitude.setGroup('groupType', 'groupName')` / `groupIdentify(...)` |
+| opt out | `amplitude.setOptOut(bool)` |
+
+### Node.js (`@amplitude/analytics-node`)
+
+| Call kind | Signature |
+|---|---|
+| init | `amplitude.init(apiKey, options?)` |
+| event | `amplitude.track(event, eventOptions?)` — user_id / device_id ride on the event, not a global setter; `logEvent(...)` is a deprecated alias |
+| identify | `amplitude.identify(new Identify().set('k', v), eventOptions?)` |
+| group | `amplitude.setGroup(...)` / `groupIdentify(...)` |
+| revenue | `amplitude.revenue(revenueObj, eventOptions?)` |
+| flush / opt-out | `amplitude.flush()` / `setOptOut(bool)` |
+
+### Python (`amplitude-analytics` on PyPI, `from amplitude import Amplitude`)
+
+| Call kind | Signature |
+|---|---|
+| init | `amp = Amplitude(api_key=...)` |
+| event | `amp.track(BaseEvent(event_type=..., user_id=..., event_properties={...}))` — `user_id` / `device_id` ride on the event, not a global setter |
+| identify | `amp.identify(Identify().set('k', v), EventOptions(user_id=...), event_properties=None)` — `Identify()` is an empty constructor; identity goes on `EventOptions` |
+| group | `amp.set_group(group_type, group_name, EventOptions(...))` / `group_identify(group_type, group_name, identify_obj, ...)` |
+| revenue | `amp.revenue(Revenue(price=...), EventOptions(...))` |
+| flush / stop | `amp.flush()` / `shutdown()` / `add(plugin)` / `remove(plugin)` |
+
+### Go (`github.com/amplitude/analytics-go/amplitude`)
+
+| Call kind | Signature |
+|---|---|
+| init | `client := amplitude.NewClient(amplitude.NewConfig("api-key"))` — `NewConfig` takes the API key |
+| event | `client.Track(amplitude.Event{EventType: "...", UserID: "..."})` — one of `UserID` / `DeviceID` required |
+| identify | `client.Identify(amplitude.Identify{...}, amplitude.EventOptions{UserID: ...})` |
+| group | `client.SetGroup(groupType, []string{groupName}, EventOptions{...})` / `client.GroupIdentify(...)` |
+| revenue | `client.Revenue(amplitude.Revenue{...}, EventOptions{...})` |
+| flush / stop | `client.Flush()` / `Shutdown()` / `Add(plugin)` / `Remove(name)` |
+
+### Java (server, `com.amplitude:java-sdk`)
+
+| Call kind | Signature |
+|---|---|
+| init | `Amplitude.getInstance().init(apiKey)` |
+| event | `amplitude.logEvent(new Event("event_type", userId))` — **Java server uses `logEvent`, not `track`**; `userId` / `deviceId` are `Event` constructor args (at least one required, `userId` ≥ 5 chars) |
+| props / groups | `event.setEventProperties(map)` / `setUserProperties(map)` / `setGroups(map)` / `setGroupProperties(map)` |
+| flush / stop | `flushEvents()` / `shutdown()`; config: `setServerUrl(...)` / `useBatchMode(...)` |
+
+No `identify` / `setGroup` / `groupIdentify` / `revenue` client methods — the Java server SDK is `logEvent`-only; groups and revenue are set as properties on the `Event` object.
+
+### Android (Kotlin, `com.amplitude:analytics-android`)
+
+- `amplitude.track("event_name", mapOf("k" to v))`, `amplitude.identify(Identify().set("k", v))`, `amplitude.setUserId("id")`, `setDeviceId("id")`, `setSessionId(ms)`, `setGroup(type, name)`, `groupIdentify(...)`, `setOptOut(bool)`, `revenue(...)`, `flush()`, `reset()`, `remove()`.
+
+### iOS (Swift, `Amplitude`)
+
+- `amplitude.track(eventType: "event_name", eventProperties: ["k": v])`, `amplitude.identify(identify: Identify().set(property: "k", value: v))`, `amplitude.setUserId(userId: "id")`, `setDeviceId(deviceId: "id")`, `setSessionId(ms)`, `setGroup(groupType:groupName:)`, `groupIdentify(...)`, `revenue(...)`, `flush()`, `reset()`, `remove()`.
+
+### Flutter (`amplitude_flutter`)
+
+- `amplitude.track('event_name', {'k': v})`, `amplitude.identify(Identify()..set('k', v))`, `amplitude.setUserId('id')`, `setDeviceId('id')`, `setGroup(type, name)`, `groupIdentify(...)`, `revenue(...)`, `reset()`, `flush()`.
+
+### Unity (legacy API — `logEvent`, not `track`)
+
+- Init: `amplitude.init(API_KEY)`.
+- Event: `amplitude.logEvent("event_name", propertiesDict)`.
+- Identity: `amplitude.setUserId("id")`.
+- User property: `setUserProperty("k", v)` / `setUserProperties({...})` / `setOnceUserProperty("k", v)` / `unsetUserProperty("k")` / `clearUserProperties()` / `appendUserProperty("k", [v])` / `addUserProperty("k", v)` / `addUserPropertyDict(...)`.
+- Group: `setGroup("groupType", "groupName")`.
+- Revenue: `logRevenue(...)`.
+- Misc: `trackSessionEvents(bool)`, `setServerUrl(...)`, `setServerZone(...)`, `setEventUploadPeriodSeconds(...)`.
+
+### Server-side → AE landing architecture
+
+Amplitude server SDKs upload directly over HTTP. AE server SDKs default to **LoggerConsumer + LogBus2** (write to local logs → LogBus2 syncs to AE) — the reliable, no-data-loss path. `switch` mode therefore requires deploying LogBus2, not just replacing the calls. If the customer insists on direct HTTP upload and accepts the data-loss risk, use the `restful` standalone option (`ae-generate-tracking-code` → `references/restful-call.md`) — do **not** switch to BatchConsumer.
+
+| Amplitude server SDK | AE server SDK |
+|---|---|
+| Node.js `@amplitude/analytics-node` | Node.js SDK |
+| Python `amplitude-analytics` (PyPI) | Python SDK |
+| Go `github.com/amplitude/analytics-go` | Golang SDK |
+| Java `com.amplitude:java-sdk` | Java SDK |
+
+## 2. Event mapping rules
+
+> **Forward compatibility**: preserve event/property names verbatim (skip snake_case — AE matches names case-sensitively) when historical Amplitude data has been (or will be) imported into AE offline and must join with new SDK data; transform only hard-constraint violations, matching the names the offline import used. See `mapping-framework.md` §1.
+
+- `logEvent(type, props)` / `track(type, props)` → `track(snake_case(type), props)`.
+- Amplitude event names are free-form; convert to AE `snake_case` (lowercase, underscores, start with a letter). Amplitude convention is often PascalCase or snake_case — normalize both.
+- **Reserved prefix**: Amplitude reserves property / user-property names starting with `[Amplitude]` (case-insensitive) for its internal system properties. A custom name with this prefix must be renamed (strip the prefix) and surfaced to the user for confirmation.
+- Event properties: map each key to an AE property with a type inferred per `mapping-framework.md`. Amplitude allows nested objects and arrays — map objects to AE `object`, object arrays to `array_row`, string arrays to `array_string`.
+- Amplitude truncates very long event/property names and has large property limits (2000 event props / 1000 user props) — no renaming needed for length, only snake_case normalization.
+- `Revenue` / `revenue(...)` / `logRevenue(...)` → AE has **no payment/revenue API and no revenue auto-track event** — revenue is an ordinary event the app reports itself. Map to a user-chosen AE payment event (e.g. `pay_order` / `purchase`) via `track(...)` with **custom** `amount` (numeric) + `currency` (ISO 4217 string) properties. Never emit `#`-prefixed money names (`#amount` / `#currency` are not valid AE preset properties — rejected at ingestion). The event name and the amount/currency property names are a user decision.
+
+## 3. Identity mapping
+
+- Client `setUserId(id)` → AE `login(accountId)` (account_id_source `user_account`).
+- Client `setDeviceId(id)` → AE visitor identity (`#distinct_id`); SDK-managed by default. **Forward compatibility**: map Amplitude's default anonymous `device_id` to AE `#distinct_id` via the AE visitor-id API (`setDistinctId` / `identify`) once at init, before any event; see `mapping-framework.md` §4. Only when the device id is a stable business id should it become `login(accountId)`.
+- **Server SDKs**: user_id / device_id ride on each event (Node/Python/Go/Java) or on the `Identify` object (Python) — map to AE per-event `#account_id` / account_id_source, not a client `login()` call.
+- `setSessionId(ms)` → AE session management is SDK-managed; drop.
+- `reset()` / `remove()` → AE `logout()` (clear login state); `remove()` also wipes local data — treat as a hard reset, confirm with user.
+- `setOptOut(bool)` → AE has no init-then-toggle switch: its consent model is to **initialize the SDK only after the user accepts the privacy policy** (the official sample code gates init behind `if (consented)` — see the AE client-SDK FAQ, e.g. `android_sdk_faq.md` / `ios_sdk_faq.md`). In `switch` mode, gate the AE init behind the same consent check rather than emitting an opt-out call. A **runtime** opt-out toggle (the user revokes consent mid-session) maps to AE's runtime pause API `enableTracking` (the compliance/GDPR doc describes it as suspending all data reporting; CocosCreator's variant is `setTrackStatus(PAUSE/STOP/SAVE_ONLY/NORMAL)`) — read the exact signature from the target platform's SDK doc; otherwise mark `needs decision`.
+- `setGroup(groupType, groupName)` / `groupIdentify` → AE has no direct group concept. Map to a user property or the AE account/role system; **mark `needs decision`** and ask the user.
+
+## 4. User property mapping
+
+Identify operations map 1:1 to AE user property methods:
+
+| Amplitude Identify operation | AE method | Notes |
+|---|---|---|
+| `set(k, v)` | `user_set` | overwrite |
+| `setOnce(k, v)` | `user_setOnce` | first-write-wins |
+| `add(k, n)` | `user_add` | numeric accumulate |
+| `append(k, v)` | `user_append` | array append |
+| `unset(k)` | `user_unset` | remove property |
+| `prepend` / `preInsert` / `postInsert` / `remove` | — | no AE equivalent; map to `user_set` with the full array or mark `needs decision` |
+| `clearAll()` | — | clears all pending ops in the Identify object; migrate the ops the object still contains, not the `clearAll` itself |
+
+Legacy `setUserProperties({k: v})` (amplitude-js / RN / Unity) → `user_set`.
+Unity `setOnceUserProperty(k, v)` → `user_setOnce`; `unsetUserProperty(k)` → `user_unset`; `appendUserProperty`/`addUserProperty` → `user_append`; `clearUserProperties()` → `needs decision` (no direct AE equivalent).
+
+> Amplitude has **no** common-property (super property) API: `setUserProperties` is a **user** property, not an event property attached to every event — do not map it to AE `setSuperProperties`.
+
+> `user_append` / `user_unset` are code-level only — they do not enter the AE plan (`update_type` is `user_set` / `user_setOnce` / `user_add`); see `mapping-framework.md` §5.
+
+## 5. Auto-track decision
+
+Amplitude auto-collects session start/end and (in some SDKs) screen/page views:
+
+| Amplitude auto-track | Decision |
+|---|---|
+| session start | drop (AE `ta_app_start` / `ta_page_show` cover lifecycle; confirm with user) |
+| session end | drop |
+| page/screen view | map to AE `ta_page_show` (web) / `ta_app_view` (native) switch |
+| Unity `trackSessionEvents(bool)` | drop the call; enable AE auto-track switches via init instead |
+
+Enable via the AE SDK init switch, never as manual `track()`.
+
+## 6. Dependency identifiers
+
+| Platform | Remove in `switch` mode | Notes |
+|---|---|---|
+| Web legacy | `amplitude-js` | |
+| Web 2.x | `@amplitude/analytics-browser` | |
+| React Native | `@amplitude/analytics-react-native` | |
+| Node | `@amplitude/node` (legacy) / `@amplitude/analytics-node` | npm |
+| Python | `amplitude-analytics` (PyPI; import `amplitude`) | pip |
+| Go | `github.com/amplitude/analytics-go` | Go module |
+| Java | `com.amplitude:java-sdk` | Maven/Gradle |
+| Android | `com.amplitude:analytics-android` | Gradle |
+| iOS | `Amplitude` (SPM/CocoaPods) | |
+| Flutter | `amplitude_flutter` | pubspec |
+| Unity | Amplitude Unity package (`.unitypackage`) | not a package-manager dependency; remove from the Unity project |
+
+AE SDK dependency is resolved via the AE wiki (`ae-generate-tracking-code` → `references/sdk-index.md`), not here.
+
+## 7. Official docs
+
+- SDK overview: https://www.docs.developers.amplitude.com/data/sdks/
+- Browser 2.x: https://www.docs.developers.amplitude.com/data/sdks/browser-2/
+- Node.js: https://www.docs.developers.amplitude.com/data/sdks/node/
+- Python: https://www.docs.developers.amplitude.com/data/sdks/python/
+- Go: https://www.docs.developers.amplitude.com/data/sdks/go/
+- Java: https://www.docs.developers.amplitude.com/data/sdks/java/
+- Android (Kotlin): https://www.docs.developers.amplitude.com/data/sdks/android-kotlin/
+- iOS: https://www.docs.developers.amplitude.com/data/sdks/ios/
+- React Native: https://www.docs.developers.amplitude.com/data/sdks/react-native/
+- Flutter: https://www.docs.developers.amplitude.com/data/sdks/flutter/
+- Unity: https://www.docs.developers.amplitude.com/data/sdks/unity/
+- Server SDK source (API verified): https://github.com/amplitude/Amplitude-TypeScript (Node), https://github.com/amplitude/Amplitude-Python, https://github.com/amplitude/analytics-go, https://github.com/amplitude/Amplitude-Java

package/skills/ae-migrate-tracking-code/references/providers/firebase.md

@@ -0,0 +1,160 @@
+# Firebase Analytics Adapter
+
+> **Terminology**: 事件 = event | 参数 = param / event parameter | 用户属性 = user property | 用户 ID = user id | 自动采集 = auto-track | 保留前缀 = reserved prefix
+
+## 1. Recognition
+
+### Web (JavaScript)
+
+| Variant | Import | Event call |
+|---|---|---|
+| v8 namespaced | `import firebase from 'firebase/app'; import 'firebase/analytics';` | `firebase.analytics().logEvent('event_name', { param: value })` |
+| v9 modular | `import { getAnalytics, logEvent } from 'firebase/analytics';` | `const analytics = getAnalytics(app); logEvent(analytics, 'event_name', { param: value })` |
+
+Identity / user property calls (web):
+
+| Call | v8 | v9 |
+|---|---|---|
+| set user id | `firebase.analytics().setUserId(id)` | `setUserId(analytics, id)` |
+| set user properties | `firebase.analytics().setUserProperties({ k: v })` | `setUserProperties(analytics, { k: v })` |
+| set default event params (common event properties) | `firebase.analytics().setDefaultEventParameters({ k: v })` | `setDefaultEventParameters(analytics, { k: v })` |
+| toggle collection | `firebase.analytics().setAnalyticsCollectionEnabled(bool)` | `setAnalyticsCollectionEnabled(analytics, bool)` |
+
+### Android
+
+- Import: `com.google.firebase.analytics.FirebaseAnalytics`
+- `mFirebaseAnalytics = FirebaseAnalytics.getInstance(context)`
+- Event: `mFirebaseAnalytics.logEvent(FirebaseAnalytics.Event.SELECT_CONTENT, bundle)` (bundle keys often `FirebaseAnalytics.Param.*` constants)
+- Identity: `mFirebaseAnalytics.setUserId(id)`
+- User property: `mFirebaseAnalytics.setUserProperty(name, value)`
+
+### iOS
+
+- Import: `FirebaseAnalytics` (`import FirebaseAnalytics` in Swift / `@import FirebaseAnalytics;` in Objective-C)
+- Event: `Analytics.logEvent("event_name", parameters: [AnalyticsParameterItemID: "id"])` / ObjC `[FIRAnalytics logEventWithName:name parameters:params]`
+- Identity: `Analytics.setUserID("id")` / ObjC `[FIRAnalytics setUserID:userID]`
+- User property: `Analytics.setUserProperty(value, forName: name)` / ObjC `[FIRAnalytics setUserPropertyString:value forName:name]`
+
+### Flutter
+
+- `FirebaseAnalytics.instance.logEvent(name: 'event_name', parameters: {...})`
+- `FirebaseAnalytics.instance.setUserId(id)`
+- `FirebaseAnalytics.instance.setUserProperty(name: 'k', value: 'v')`
+
+### React Native
+
+- Import: `import analytics from '@react-native-firebase/analytics'`
+- Event: `await analytics().logEvent('event_name', { param: value })`
+- Identity: `await analytics().setUserId(id)`
+- User property: `await analytics().setUserProperty('name', value)` / `setUserProperties({ k: v })`
+- Screen: no `setCurrentScreen` — `screen_view` is auto-collected; to report a screen manually use `logEvent('screen_view', { screen_name, screen_class })`
+- Toggle collection: `await analytics().setAnalyticsCollectionEnabled(bool)`
+- Reset: `await analytics().resetAnalyticsData()` (e.g. on sign-out)
+- Other: `getAppInstanceId()`, `setSessionTimeoutDuration(ms)`, `setConsent({...})`
+
+### Unity
+
+- Import: `using Firebase.Analytics;`
+- Event: `FirebaseAnalytics.LogEvent(string eventName, Parameter[] parameters)` where each param is `new Parameter("method", "phone")`; event constant `Firebase.Analytics.FirebaseAnalytics.EventSelectContent`
+- Identity: `FirebaseAnalytics.SetUserId(id)`
+- User property: `FirebaseAnalytics.SetUserProperty("k", "v")`
+- Other: `SetAnalyticsCollectionEnabled(bool)`, `SetSessionTimeoutDuration(ms)`, `GetAnalyticsInstanceId()`
+
+### C++
+
+- Import: `#include "firebase/analytics.h"` plus `firebase/analytics/event_names.h`, `firebase/analytics/parameter_names.h`, `firebase/analytics/user_property_names.h`
+- Event: `firebase::analytics::LogEvent(name, parameters, parameter_count)` where `parameters` is `firebase::analytics::Parameter[]`; event constant `firebase::analytics::kEventSelectContent`
+- Identity: `firebase::analytics::SetUserId(id)` — official examples also pass `analytics::Parameter("user_id", mUserId)` inside the event params
+- User property: `firebase::analytics::SetUserProperty("k", "v")`
+- Other: `SetAnalyticsCollectionEnabled(bool)`, `SetSessionTimeoutDuration(ms)`, `GetAnalyticsInstanceId()`
+
+### Constant names (Android / iOS / Unity / C++)
+
+Firebase defines event constants in UPPER_SNAKE (e.g. `SELECT_CONTENT`, `ADD_PAYMENT_INFO`, `TUTORIAL_BEGIN`), Unity in PascalCase (`EventSelectContent`), and C++ in `kEvent`-prefixed form (`kEventSelectContent`); param constants likewise (`ITEM_ID`, `VALUE`, `CURRENCY`). Map them all to lowercase snake_case in AE (`select_content`, `add_payment_info`, `item_id`, `value`, `currency`).
+
+### Firebase ↔ GA4
+
+Firebase Analytics and GA4 are the same data stream (GA4 is Firebase's web layer; one measurement ID is both). If `logEvent(...)` (Firebase) and `gtag(...)` (GA4) coexist in one project, merge them into a single migration run rather than two providers (see SKILL.md Phase 0).
+
+## 2. Event mapping rules
+
+> **Forward compatibility**: preserve event/property names verbatim (skip snake_case — AE matches names case-sensitively) when historical Firebase data has been (or will be) imported into AE offline and must join with new SDK data; transform only hard-constraint violations, matching the names the offline import used. See `mapping-framework.md` §1.
+
+- `logEvent(eventName, params)` → `track(snake_case(eventName), props)`.
+- **Event name constraints**: ≤ 40 chars; only alphanumeric + underscore; must start with a letter; no spaces. Violations are already impossible for valid Firebase calls, but snake_case conversion must still lower-case the constant forms — web literals, Android/iOS `Event.*`, Unity `EventXxx`, C++ `kEventXxx` (see Section 1).
+- **Reserved prefixes** (cannot be custom events/params): `firebase_`, `google_`, `ga_`. If found, strip the prefix and flag for user confirmation.
+- **Params**: ≤ 25 per event; param name ≤ 40 chars; param value ≤ 100 chars. Map each param to an AE property with a type inferred per `mapping-framework.md`.
+- **Reserved events** (e.g. `screen_view`, `session_start`, `first_open`, `in_app_purchase`, `purchase`, `tutorial_begin`, `tutorial_complete`, `sign_up`, `login`) — do NOT rename; map `purchase`/`in_app_purchase` to a payment event and let the user decide the AE event name, drop analytics-internal ones per Section 6.
+- Non-literal param values (variables): read the surrounding code to resolve the property name/type; mark unresolved ones for confirmation.
+
+## 3. Identity mapping
+
+- `setUserId(id)` → AE `login(accountId)` (account_id_source `user_account`).
+- Firebase user id has no strict length documented; treat as opaque string.
+- **Forward compatibility**: Firebase's auto anonymous id is `app_instance_id` on **native** platforms (Android/iOS/Flutter/Unity/C++/React Native — read it via `getAppInstanceId()` / `appInstanceID` / `GetAnalyticsInstanceId()` per platform), but on **web** (v8/v9) the JS SDK has **no** `getAppInstanceId()` — the anonymous id there is the GA4 `client_id`, read via `getGoogleAnalyticsClientId(analytics)` (v9) / `firebase.analytics().getGoogleAnalyticsClientId()` (v8); it is the same stream as §1 Firebase ↔ GA4. When imported historical data must join with new data, map it to AE `#distinct_id` via the AE visitor-id API (`setDistinctId` / `identify`, name varies by SDK — read the wiki main doc) once at init, before any event; see `mapping-framework.md` §4.
+- `setAnalyticsCollectionEnabled(bool)` → AE's consent model is to **initialize the SDK only after the user accepts the privacy policy** (gate the AE init behind the consent check — see the AE client-SDK FAQ, e.g. `android_sdk_faq.md` / `ios_sdk_faq.md`), not an init-then-toggle switch. A runtime toggle maps to AE's runtime pause API `enableTracking` (the compliance/GDPR doc describes it as suspending all data reporting; CocosCreator's variant is `setTrackStatus(PAUSE/STOP/SAVE_ONLY/NORMAL)`) — read the exact signature from the target platform's SDK doc.
+- `setConsent({...})` (React Native) → **`needs decision`**: Firebase consent is per-purpose (analytics vs ads storage, ad personalization, …), finer-grained than AE's single tracking switch. Map an analytics-storage denial to the consent-gated AE init where the semantics match; other purposes have no AE equivalent — confirm with the user.
+
+## 4. User property mapping
+
+| Source operation | AE method | Notes |
+|---|---|---|
+| `setUserProperties({ k: v })` / `setUserProperty(k, v)` | `user_set` | overwrite; defaults to `user_set`. Use `user_setOnce` when the source property is first-time-only (e.g. first_open channel) |
+| numeric accumulate intent | `user_add` | only when the surrounding code reads-then-writes an increasing counter |
+
+**Reserved user property names** (cannot be used): Firebase SDK reserves `Age`, `Gender`, `Interest`; GA4 additionally reserves `first_open_time`, `first_visit_time`, `last_deep_link_referrer`, `user_id`, `first_open_after_install`.
+
+**User property name constraints**: ≤ 24 chars; names cannot begin with `firebase_`, `google_`, `ga_`, or `_`. Ensure the AE property name is snake_case and registered.
+
+## 5. Super property mapping
+
+Firebase `setDefaultEventParameters({...})` (web v8/v9, React Native, Unity) attaches default params to **every subsequent event** — they are event properties, never user properties. Map them to AE common event properties (`setSuperProperties`).
+
+| Source operation | AE method | Notes |
+|---|---|---|
+| `setDefaultEventParameters({k:v})` | `set_super_properties` (`setSuperProperties({...})`) | static common event property; lands in `draft.json` `common_event_properties` |
+
+> `setDefaultEventParameters` **accumulates** across calls, but AE `setSuperProperties` **overwrites** the whole set each call. Multiple call sites must be merged into a single `setSuperProperties` (or flagged for the user) so earlier keys are not silently dropped.
+
+## 6. Auto-track decision
+
+Firebase auto-collected events (not call sites) — map or drop:
+
+| Firebase auto-track | Decision |
+|---|---|
+| `session_start` | drop (AE `ta_app_start` / `ta_page_show` cover lifecycle; confirm with user) |
+| `first_open` | map to AE `ta_app_install` switch |
+| `screen_view` | map to AE `ta_page_show` switch (web) or drop on native (AE `ta_app_view` optional) |
+| `app_remove`, `app_update` | drop |
+| `app_clear_data`, `app_exception`, `app_store_refund`, `os_update`, `ad_*`, `notification_*`, `dynamic_link_*` | drop (no AE auto-track equivalent) |
+| `in_app_purchase` | map to an AE payment event (auto-collected, but revenue must become a `track()` with a **custom** amount property, e.g. `amount` — never a `#`-prefixed name: `#amount` is NOT a valid AE preset property and is rejected at ingestion, see `references/ae-preset-properties.md`) |
+
+Enable the chosen AE auto-track via the SDK init switch (see `ae-generate-tracking-code`), never as manual `track()`.
+
+## 7. Dependency identifiers
+
+| Platform | Remove in `switch` mode | Notes |
+|---|---|---|
+| Web v8 | `firebase/app`, `firebase/analytics` | also the global `firebase.analytics` usage |
+| Web v9 | `firebase/analytics` | keep `firebase/app` only if used elsewhere |
+| Android | `com.google.firebase:firebase-analytics` | Gradle dependency |
+| iOS | `Firebase/Analytics` (CocoaPods) / `FirebaseAnalytics` (SPM) | |
+| Flutter | `firebase_analytics` | pubspec |
+| React Native | `@react-native-firebase/analytics` | package.json |
+| Unity | Firebase Analytics package (`.unitypackage`) | not a package-manager dependency; remove the package from the Unity project |
+| C++ | `firebase::analytics` | remove the linked Firebase Analytics library from CMake / build config |
+
+AE SDK dependency is resolved via the AE wiki (`ae-generate-tracking-code` → `references/sdk-index.md`), not here.
+
+## 8. Official docs
+
+- Get started: https://firebase.google.com/docs/analytics/get-started
+- Web logEvent reference: https://firebase.google.com/docs/reference/js/analytics
+- Android events: https://firebase.google.com/docs/analytics/android/events
+- iOS events: https://firebase.google.com/docs/analytics/ios/events
+- Android user properties: https://firebase.google.com/docs/analytics/android/user-properties
+- iOS user properties: https://firebase.google.com/docs/analytics/ios/user-properties
+- User properties: https://firebase.google.com/docs/analytics/user-properties
+- Unity `FirebaseAnalytics` reference: https://firebase.google.com/docs/reference/unity/class/firebase/analytics/firebase-analytics
+- C++ `firebase::analytics` reference: https://firebase.google.com/docs/reference/cpp/namespace/firebase/analytics
+- Auto-collected events: https://support.google.com/firebase/answer/9234069

package/skills/ae-migrate-tracking-code/references/providers/ga4.md

@@ -0,0 +1,92 @@
+# Google Analytics 4 (gtag.js) Adapter
+
+> **Terminology**: 事件 = event | 参数 = event parameter | 用户属性 = user property | 用户 ID = user id | 自动采集 = enhanced measurement | 保留前缀 = reserved prefix | 服务端上报 = Measurement Protocol
+
+## 1. Recognition
+
+### Web (gtag.js)
+
+| Call kind | Signature |
+|---|---|
+| init | `gtag('js', new Date())` then `gtag('config', 'G-XXXXXXX', { ... })` |
+| event | `gtag('event', 'event_name', { param: value })` |
+| user id | `gtag('set', 'user_id', 'id')` or `gtag('config', 'G-XXXXXXX', { user_id: 'id' })` |
+| user properties | `gtag('set', 'user_properties', { k: { value: v } })` |
+| consent | `gtag('consent', 'default', { ... })` |
+
+### dataLayer variant
+
+- `dataLayer.push({ 'event': 'event_name', param: value })` — the same events pushed through a plain JS array; recognize `dataLayer` pushes alongside `gtag` calls.
+- **`dataLayer` is a shared GTM data bus, not a GA4-only pipe.** A single `dataLayer.push` is typically consumed by **multiple tags in the GTM container** — the GA4 tag plus non-GA4 tags (Google Ads conversion, remarketing/audience, Meta Pixel, other vendor tags). Unlike `gtag('event', ...)` (GA4-exclusive), a `dataLayer.push` is therefore **ambiguous in ownership**. In `switch` mode, do not delete a `dataLayer.push` assuming it only feeds GA4: confirm first that no other GTM tag depends on it. When that cannot be confirmed, keep the `dataLayer.push` and treat the site as `add` mode (add `ta.track(...)` alongside) rather than deleting it.
+
+### Server (Measurement Protocol)
+
+- Not a SDK — raw HTTP POST to `https://www.google-analytics.com/mp/collect?measurement_id=G-XXX&api_secret=SECRET` with body `{ client_id, user_id, events: [{ name, params }] }`.
+
+### GA4 ↔ Firebase Analytics
+
+GA4 is Firebase Analytics' web layer — a single measurement ID is both a GA4 property and a Firebase project. In a project where `gtag(...)` (GA4) and `logEvent(...)` (Firebase) coexist, they are **one data stream, not two providers**: merge them into a single migration run (see SKILL.md Phase 0) producing one scan / one `draft.json` / one `mapping.json`. Do not migrate them as two separate providers.
+
+## 2. Event mapping rules
+
+> **Forward compatibility**: preserve event/property names verbatim (skip snake_case — AE matches names case-sensitively) when historical GA4 data has been (or will be) imported into AE offline and must join with new SDK data; transform only hard-constraint violations, matching the names the offline import used. See `mapping-framework.md` §1.
+
+- `gtag('event', name, params)` / `dataLayer.push({event: name, ...})` → `track(snake_case(name), params)`.
+- **Event name constraints**: ≤ 40 chars; only alphanumeric + underscore; must start with a letter; ≤ 25 params; param name ≤ 40 chars; param value ≤ 100 chars.
+- **Reserved prefixes** — event, parameter, and user-property names cannot begin with `_` (leading underscore), `firebase_`, `ga_`, or `google_`; parameter names additionally cannot begin with `gtag.`. Strip the prefix and flag for user confirmation.
+- **Reserved param name**: `firebase_conversion` is the only fully-reserved parameter name (cannot be used at all). Auto-collected / system parameters — `engagement_time_msec`, `gclid`, `session_id`, `session_number` — also must not be redefined as custom parameters: drop or map per user decision.
+- **Reserved event names** (cannot be used as custom events): `ad_activeview`, `ad_click`, `ad_exposure`, `ad_query`, `ad_reward`, `adunit_exposure`, `app_clear_data`, `app_exception`, `app_install`, `app_remove`, `app_store_refund`, `app_update`, `app_upgrade`, `dynamic_link_app_open`, `dynamic_link_app_update`, `dynamic_link_first_open`, `error`, `first_open`, `first_visit`, `in_app_purchase`, `notification_dismiss`, `notification_foreground`, `notification_open`, `notification_receive`, `os_update`, `screen_view`, `session_start`, `user_engagement`.
+- **Recommended event names** (GA4-predefined — custom events must not reuse them): `click`, `file_download`, `form_start`, `form_submit`, `scroll`, `view_complete`, `video_progress`, `video_start`, `view_search_results`, `sign_up`, `login`, and more. Route both sets to Section 5 auto-track decisions, never to manual `track()`; see the events reference for the full list.
+- `gtag('set', 'user_properties', ...)` / `gtag('config', ..., { user_id })` are config calls, not events — map to identity / user property per Sections 3–4, not `track`.
+
+## 3. Identity mapping
+
+- `gtag('set', 'user_id', id)` / `gtag('config', 'G-XXX', { user_id: id })` → AE `login(accountId)` (account_id_source `user_account`).
+- Measurement Protocol `user_id` field → same mapping.
+- **Forward compatibility**: GA4's auto anonymous id is `client_id`. When imported historical data must join with new data, map it to AE `#distinct_id` via the AE visitor-id API (`setDistinctId` / `identify`) once at init, before any event; see `mapping-framework.md` §4.
+- `gtag('consent', 'default', {...})` → **`needs decision`**: GA4 consent is per-purpose (`analytics_storage`, `ad_storage`, …), finer-grained than AE's single tracking switch. AE's consent model is to **initialize the SDK only after the user accepts the privacy policy** (gate the AE init behind the consent check — see the AE client-SDK FAQ, e.g. `android_sdk_faq.md` / `ios_sdk_faq.md`). Map an `analytics_storage: denied` default to that gated init where the semantics match; `ad_storage` and other purposes have no AE equivalent — confirm with the user.
+
+## 4. User property mapping
+
+| Source operation | AE method | Notes |
+|---|---|---|
+| `gtag('set', 'user_properties', {k:{value:v}})` | `user_set` | overwrite; use `user_setOnce` when first-time-only |
+
+> GA4 / gtag.js has **no** common-property (super property) API — `gtag('set', 'user_properties', ...)` is a **user** property, not an event property attached to every event; do not map it to AE `setSuperProperties`.
+
+**Reserved user property names** (cannot be used): `first_open_time`, `first_visit_time`, `last_deep_link_referrer`, `user_id`, `first_open_after_install` — plus the reserved-prefix rule in §2.
+
+**User property limits**: ≤ 25 user properties; name ≤ 24 chars; value ≤ 36 chars; user-id value ≤ 256 chars.
+
+## 5. Auto-track decision (enhanced measurement)
+
+GA4 auto-collects these (no call sites):
+
+| GA4 auto-track | Decision |
+|---|---|
+| `page_view` | map to AE `ta_page_show` switch |
+| `session_start` | drop (AE `ta_app_start` / `ta_page_show` cover lifecycle) |
+| `first_visit` | map to AE `ta_app_install` switch |
+| `scroll`, `click`, `view_search_results`, `video_start`, `file_download`, `form_start`, `form_submit`, `user_engagement` | drop or map per user decision; most have no AE auto-track equivalent |
+
+Enable via the AE SDK init switch, never as manual `track()`.
+
+## 6. Dependency identifiers
+
+| Platform | Remove in `switch` mode | Notes |
+|---|---|---|
+| Web | gtag.js script snippet (`https://www.googletagmanager.com/gtag/js?id=G-XXXXXXX`) + all `gtag(...)` calls | remove the `dataLayer` global **only after confirming no other GTM tag consumes it** (see §1 dataLayer variant); if in doubt, keep it |
+| Server | Measurement Protocol endpoint | remove the `mp/collect` HTTP calls |
+
+AE SDK dependency is resolved via the AE wiki (`ae-generate-tracking-code` → `references/sdk-index.md`), not here.
+
+## 7. Official docs
+
+- gtag.js (GA4): https://developers.google.com/analytics/devguides/collection/ga4
+- gtag.js API reference: https://developers.google.com/tag-platform/gtagjs/reference
+- Events reference: https://developers.google.com/analytics/devguides/collection/ga4/events
+- Event parameters: https://developers.google.com/analytics/devguides/collection/ga4/event-parameters
+- User properties: https://developers.google.com/analytics/devguides/collection/ga4/user-properties
+- Collection limits (40/24/36 chars, 25 params / 25 user properties): https://support.google.com/analytics/answer/9267744
+- Measurement Protocol (GA4): https://developers.google.com/analytics/devguides/collection/protocol/ga4
+- Measurement Protocol reference (reserved names): https://developers.google.com/analytics/devguides/collection/protocol/ga4/reference