Conversation language: This skill document is in English, but all output to the user MUST be in the user's input language. English input → English reply; Chinese input → Chinese reply; Japanese input → Japanese reply. If uncertain, default to English. This applies to all output: section titles, phase names, prompts, code comments, etc. ⚠️ CRITICAL: Many provider adapter docs contain Chinese glossary notes. When reading them to answer an English/Japanese user, translate headings and comments to the user's language. Do NOT copy Chinese text verbatim from this document into English/Japanese replies.

ae-generate-tracking-code

ae-generate-tracking-plan

ae-generate-tracking-code

• Plan generation/upload → hand off to

  ae-generate-tracking-plan

  (codebase path).
• AE SDK code insertion → hand off to

  ae-generate-tracking-code

  (insert mode), with insertion sites supplied from the migration mapping instead of grep-discovered business triggers.

1. Locate the project and its package/dependency manifest (

   package.json

   ,

   build.gradle

   ,

   Podfile

   ,

   pubspec.yaml

   ,

   *.csproj

   , ...) plus source imports.
2. Match against the registry above. Read the matching adapter's Recognition section to confirm the provider and pin the version variant:
   • Firebase: v8 namespaced vs v9 modular (web), plus Android/iOS/Flutter native forms.
   • Amplitude: legacy (

     getInstance().logEvent

     ) vs SDK 2.x (

     amplitude.track

     /

     @amplitude/analytics-browser

     ).
3. If multiple providers are present, list them and ask which to migrate first (one provider per run keeps mapping clean). Exception — GA4 and Firebase Analytics are the same data stream: GA4 is Firebase's web layer (one measurement ID is both a GA4 property and a Firebase project). If

   gtag(...)

   and

   logEvent(...)

   coexist in one project, they are not two providers — merge them into a single migration run: one scan, one

   draft.json

   /

   mapping.json

   , one dedup pass over the shared event / property / user-id names. Never produce two drafts for one Google data stream.
4. If no registry match but tracking code exists → show the found calls, ask the user for the provider name, and (per

   references/providers/README.md

   ) collect a minimal adapter from the user-provided docs/snippet before continuing.

1. Event calls:

   logEvent(...)

   /

   track(...)

   and their params/properties.
2. Identity calls:

   setUserId(...)

   /

   identify(...)

   /

   login(...)

   .
3. User property calls:

   setUserProperty(...)

   /

   setUserProperties(...)

   /

   Identify

   operations.
4. Super property calls (common event properties):

   register(...)

   /

   registerSuperProperties(...)

   (Mixpanel, Sensors Data) /

   setDefaultEventParameters(...)

   (Firebase). Record them as

   kind: super_property

   with the full

   props

   map — do not misread them as user properties (see

   mapping-framework.md

   §6). Amplitude and GA4 have no such API.

file:line

.ae-cli/migration/scan.json

references/ir.md

trackEvent(name, props)

mixpanel.track(name, props)

resolved:false

resolved:false

• Identify the enclosing function

  F

  — it is an analytics wrapper only when

  F

  's sole role is forwarding that parameter into the SDK call. If the event name comes from local logic/expressions rather than a parameter, it is NOT a wrapper — record the site as

  resolved:false

  as usual.
• Grep for every caller of

  F

  . Resolve each caller with a static event name into a normal call site:

  kind

  is inferred from the SDK call

  F

  delegates to (event / identity / user_property),

  event_name

  from the caller's literal or constant argument,

  source_call

  = the caller's invocation line,

  file

  = the caller's file, and

  via_wrapper

  =

  F

  's name.
• Callers with a dynamic event name stay

  resolved:false

  . If no callers are found (an exported wrapper used externally, or dynamic dispatch), fall back to recording the wrapper's own SDK call as a single

  resolved:false

  site.
• Record

  F

  itself in scan.json's top-level

  wrappers

  array (see

  references/ir.md

  ) — it is the pivot for tracing, not a migration target.

session_start

first_open

screen_view

1. Read

   references/mapping-framework.md

   (generic algorithm) + the provider adapter (differences).
2. For each extracted event call: map to an AE event (snake_case name, or verbatim when forward compatibility is required —

   mapping-framework.md

   §1;

   display_name

   in the user's language), map each param to an AE property with a type, and apply naming constraints from the adapter (reserved prefixes, special characters, length caps).
3. Apply dedup + promotion rules: same property on 3+ events → common event property (super property); preset

   #

   properties never become super properties. Explicit super-property call sites (

   register

   /

   setDefaultEventParameters

   ) also land in

   draft.json

   's

   common_event_properties

   pool — see

   mapping-framework.md

   §6.
4. Map identity → AE

   login(accountId)

   (account_id_source

   user_account

   ); plus visitor-id continuity (

   setDistinctId

   /

   identify

   , init-time) when forward compatibility with imported historical data is in scope — see

   mapping-framework.md

   §4. User property ops → AE

   user_set

   /

   user_setOnce

   /

   user_add

   /

   user_append

   /

   user_unset

   per the adapter's mapping table. Super property calls → AE

   setSuperProperties({...})

   (static common event property), per

   mapping-framework.md

   §6.
5. Decide each event's

   platform

   (client / server) from where the call site lives (app code → client; backend → server).
6. Ask the user to confirm the migration mode (see Modes below) and whether historical source-platform data has been (or will be) imported into AE offline — drives forward-compatible naming per

   mapping-framework.md

   §1 and visitor-id continuity per §4. The import itself is offline data-migration work, out of scope; this skill only switches the live SDK — then:
   • Write

     .ae-cli/migration/mapping.json

     (source site → AE event + mode decision, schema in

     references/ir.md

     ).
   • Write

     .ae-cli/draft.json

     in the AE plan schema (same schema

     ae-generate-tracking-plan

     produces) so the plan skill can consume it directly.

ok

ae-generate-tracking-plan

1. ae-cli tracking plan draft --in .ae-cli/draft.json --out .ae-cli/draft.xlsx

2. ae-cli tracking plan validate --in .ae-cli/draft.json --fix

3. Resolve AE host/login/projectId per the plan skill, then

   ae-cli tracking plan upload ...

   (ask the user before uploading; append vs replace per that skill's conflict detection).

ae-generate-tracking-code

.ae-cli/migration/mapping.json

• Client/server platform + language are already in

  draft.json

  meta; resolve APP_ID / SERVER_URL as that skill does.
• For each mapped AE event, the insertion point is the original call site recorded in mapping.json.

switch

• Before any deletion, explicitly list what will be removed (the source call sites and the source SDK dependency from the adapter's Dependency identifiers) and get the user's confirmation to delete.
• Replace the source

  logEvent

  /

  track

  call with the AE

  track(...)

  call at the same site; remove now-unused source imports.
• Inline event names that came from a module constant: emit the literal snake_case name in the AE

  track(...)

  call (it must match the

  // @tracking <event_name>

  marker). Before deleting the constant definition, grep the whole project for its name — a module constant is often imported by multiple files, fed to a server-side report, or asserted in tests. Only remove it when the migrated call sites are its sole references (then it is dead code); otherwise keep it. Do not keep a constant that only feeds the migrated call.
• Remove the source SDK dependency using the adapter's Dependency identifiers (e.g.

  firebase/analytics

  ,

  @amplitude/analytics-browser

  ).
• Remove dead wrappers: when every call site resolved through a wrapper is

  replace

  d, the wrapper function is dead code — delete it (and its now-unused source import). If the wrapper's file holds nothing else, remove the file. (

  add

  mode keeps the wrapper — it still feeds the source SDK — and adds the AE call at each business call site.)
• Convert identity/user-property calls to

  login(...)

  / user-property calls similarly; super-property calls →

  setSuperProperties({...})

  in place at the original call site (never hoisted — the source's

  register

  position encodes when the values become available, e.g. after login; see

  mapping-framework.md

  §6).

add

• Keep the source call untouched; add the AE

  track(...)

  call immediately adjacent (before or after, matching surrounding style).
• Keep the two SDKs independent — in both directions. Dual-write means two independent writes, for every provider / every SDK (Firebase, Amplitude, Sensors Data, Mixpanel, GA4, …), not a source-guarded AE write:
  • The AE

    track()

    /

    login()

    / user-property /

    setSuperProperties()

    call must NOT be nested inside the source SDK's availability guard, early-return, or error path — e.g. after

    if (!analytics) return

    , behind

    isSupported()

    , or inside the source's

    try/catch

    . If the source call sits behind such a guard, lift the AE call out so it runs unconditionally.
  • Give each SDK its own

    try/catch

    around its write: a source-SDK failure (unavailable,

    isSupported() === false

    , or a thrown error) must never suppress the AE write, and an AE failure must never suppress (or crash) the source write.
  • The guard must cover the source SDK's full failure surface, not a single exception type. A pre-existing narrow catch (e.g. Python

    except ValueError

    for 400 validation, Java

    catch (IllegalArgumentException)

    ) is not the independence guard — other failures (unconfigured API key →

    RuntimeError

    , network/timeout) still escape and crash before the AE write. Broaden the catch to all exceptions, run the AE write, then re-raise the source exception so the original status/error semantics (400/503) are unchanged.
  • Give each SDK's init its own

    try/catch

    too, so that one SDK being unloaded or disabled at load time (init throws / module missing) does not take down the other SDK. Both writes must keep working no matter which SDK is unloaded or disabled.
  • This applies to every

    add

    /

    add_after

    /

    add_before

    entry in mixed runs too.
• Keep the source SDK dependency; only add the AE SDK dependency.

await

await analytics().logEvent(...)

await mixpanel.track(...)

track()

login()

setSuperProperties()

• switch

  : drop the

  await

  on the replaced call — awaiting a synchronous AE call is a lint warning and changes nothing. If the source call sat inside a

  try/catch

  whose

  catch

  handled the source SDK's Promise rejection (network retry, offline fallback, error reporting), that rejection branch dies with the source SDK: remove the now-dead

  catch

  logic; if the

  try

  block then holds only the AE call, collapse the

  try/catch

  into the bare AE call (AE sync failures then follow the code skill's Code Style — loud in

  switch

  ). Never wrap the AE call in a made-up

  async

  /

  await

  to keep the shapes matching.

• add

  : keep the source call's

  await

  and its

  try/catch

  exactly as-is, and place the AE call outside that block, un-

  await

  ed, in its own

  try/catch

  per the independence rule above.

// @tracking <event_name>

append

unset

ae_call

user_append

user_unset

update_type

user_set

user_setOnce

user_add

draft.json

update_type

user_set

ae_call

user_append

userAppend

user_unset

userUnset

add

switch

try/catch

• The AE init must be guarded the same way (its own

  try/catch

  / availability check), so an AE-SDK load failure never throws at load time and never takes down the source SDK.
• Never emit a load-time SDK capture that becomes a permanently-

  undefined

  reference and throws on every call (e.g.

  var ta = window.TA;

  in a wrapper) — a missing AE SDK must be a per-call no-op, not a crash of business logic or the source write.

• switch

  mode does NOT get this override: after cut-over AE is the only SDK, so it follows the code skill's Code Style as-is (failures stay loud).

1. ae-cli auth status

   / confirm active host; debug device add/select.
2. Trigger the migrated events and query

   ae-cli tracking debug-data list

   .
3. In

   add

   mode, verify AE data alongside the still-running source SDK; in

   switch

   mode, confirm the source SDK is fully removed and AE data flows.

switch

add

add

add

switch

mode

action

replace

add_after

add_before

action

switch

add_after

purchase

replace

references/ir.md

mapping-framework.md

⚠️

switch

is destructive (high-risk): it deletes source tracking calls, their imports, and the source SDK dependency. Never delete old code by default. Before deleting anything, explicitly tell the user what will be removed (call sites + dependencies) and get their confirmation; re-confirm again at Phase 4 immediately before deletion, even if

switch

was already chosen in Phase 2.

• Guessing AE SDK imports/package names — always read the wiki main doc via

  ae-generate-tracking-code

  (

  references/sdk-index.md

  ).
• Modifying event/property names away from the AE plan (

  snake_case

  , registered names).
• Migrating source SDK auto-track events as manual

  track()

  calls — map them to AE auto-track switches or drop them per the adapter.
• Nesting the AE

  track()

  /

  login()

  / user-property calls inside the source SDK's availability guard, early-return, or

  try/catch

  in

  add

  mode, or leaving either SDK's init unguarded, or guarding the source write with a narrow exception-type catch that still lets a source failure crash before the AE write — for every provider, dual-write must stay two independent writes (each SDK its own

  try/catch

  , init included, covering the full failure surface), so one SDK failing or being unloaded never takes down the other.
• Skipping the mapping summary confirmation in Phase 2.
• Writing

  user_append

  /

  user_unset

  into

  draft.json

  's

  update_type

  (the plan enum is

  user_set

  /

  user_setOnce

  /

  user_add

  only) — append/unset stay in

  mapping.json

  ae_call

  and are emitted directly at Phase 4.
• Translating "Super Property" as "超级属性" in any user-facing output.
• Writing source or AE code before the git-status pre-check (insert mode).
• Editing the provider adapters to add provider-specific logic into the core — new providers are new adapter files only.
• Deleting source tracking code or removing the source SDK dependency (

  switch

  mode) without explicitly warning the user and getting their confirmation immediately before deletion.

• references/ir.md

  — normalized IR schema (

  scan.json

  /

  mapping.json

  ).

• references/mapping-framework.md

  — provider-agnostic mapping algorithm.

• references/ae-preset-properties.md

  — authoritative AE

  #

  preset-property list + system fields (only these

  #

  names ingest).

• references/providers/README.md

  — adapter contract + how to add a provider.

• references/providers/firebase.md

  — Firebase adapter.

• references/providers/amplitude.md

  — Amplitude adapter.

• references/providers/sensors-data.md

  — Sensors Data (神策) adapter.

• references/providers/mixpanel.md

  — Mixpanel adapter.

• references/providers/ga4.md

  — Google Analytics 4 (gtag.js / Measurement Protocol) adapter.