Ae Generate Tracking Code

ae-generate-tracking-code

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, template prompts, code comments, etc. ⚠️ CRITICAL: Many reference documents (wiki SDK docs, code examples) contain Chinese text. When reading Chinese source material to answer an English/Japanese user, you MUST translate headings, descriptions, and comments to the user's language. The source document's language is NOT the user's language. Use the Terminology Glossary above to map terms accurately. Do NOT copy Chinese text verbatim from this document into English/Japanese replies. Document link language: When providing official documentation URLs, use lan=zh-CN for Chinese users, lan=en-US for all others.

Terminology Glossary

When to Trigger

Trigger when user says: "generate tracking code / help me add web tracking / generate logbus config / server-side reporting code" etc. Supports multiple platforms with independent output mode selection per platform.

Phase 0 — Anchor (one question per message)

Pre-check: Read existing configuration from draft.json

First, check if .ae-cli/draft.json exists and read existing configuration:

Important: project_id ≠ APP_ID, and host ≠ SERVER_URL. Even if project_id and host are already set, SERVER_URL and APP_ID must still be resolved and confirmed separately. Prefer lookup first; ask the user only when lookup is unavailable or ambiguous.

Multi-platform support:

• If client_platforms exists (array): multi-platform scenario — generate code for each platform
• If only client_sdk_type exists: single platform (backward compatible)
• Example: client_platforms: ["android", "openharmony"] → generate code for Android + OpenHarmony

Language support:

• Android SDK: supports Java / Kotlin (can generate both)
• iOS SDK: supports Objective-C / Swift (can generate both)
• Other SDKs: fixed language, no selection needed

Language configuration source:

• Prefer meta.client_platform_languages (e.g. {"android": ["java", "kotlin"]})
• If not configured, ask user for Android/iOS platforms only

Confirmation flow:

• Has value → ask "Confirm using draft.json config: <value>? yes / enter new value"
• User says yes → use draft value
• User enters new value → update draft.json and use new value

Required configuration (must resolve and confirm each item)

⚠️ Key: SERVER_URL and APP_ID are independent config items. Even if draft.json has project_id and host, you MUST resolve and confirm them. `project_id` ≠ `APP_ID`, `host` ≠ `SERVER_URL`.

1. APP_ID — Prefer automatic lookup before asking:

• If meta.project_id is known, run ae-cli project info list once for the current host.
• Find the project whose projectId matches meta.project_id.
• If the matched project has appId, ask: "I found APP_ID `<appId>` for project `<projectId>`. Use it? yes / enter new value"
• If the project is missing, ambiguous, or has no appId, ask the user to copy APP_ID from AE Admin → "Project Settings" → "Integration Config".

1. SERVER_URL — Data ingestion endpoint (different from web URL; go to AE Admin → "Project Settings" → "Integration Config" → fill in "Public URL")

• If meta.project_id is known, you may try ae-cli project info get --project-id <project_id> once.
• Use the returned value only if the response explicitly contains a receiver URL field such as serverUrl, pushUrl, push_url, receiverUrl, publicUrl, publicReceiverAddress, privateReceiverAddress, or equivalent ingestion endpoint field.
• If both publicReceiverAddress and privateReceiverAddress are present, prefer publicReceiverAddress as SERVER_URL for generated snippets unless the user explicitly needs an internal/private-network receiver.
• If a value is found, ask: "I found SERVER_URL `<url>` for project `<projectId>`. Use it? yes / enter new value"
• ⚠️ "Public URL" only shows if previously filled in; if empty, this field won't display
• Solution: ask ops for the URL, or skip this step (use SERVER_URL or PUSH_URL placeholder in code)

host handling (optional):

• If you need to fetch plan from AE (no local draft.json) → ask for host
• If local draft.json exists → host is not required for code generation
• Before Debug validation, run ae-cli config current and confirm the active host matches the target AE environment; if it does not, run ae-cli config set-host <AE_HOST>
• Complete Debug validation with ae-cli tracking debug-device and ae-cli tracking debug-data by default; only hint the user to open the AE Debug page when those CLI capabilities are unavailable

If only xlsx file exists (no draft.json)

First, check if both .ae-cli/draft.json and .ae-cli/draft.xlsx exist:

If both are missing — the current environment hasn't generated a tracking plan yet. Remind user of two options: