Tracking Clix Events

Use this skill to help developers design and implement Clix event tracking via

Clix.trackEvent(...)

so events can drive event-triggered campaigns, audience filters, and personalization.

What the official docs guarantee (high-signal)

• When to track: identify the user action/system event, then attach meaningful properties (funnel checkpoints, milestones, button taps).
• Property normalization: booleans/numbers/strings map directly; date-like values serialize to ISO 8601; unsupported objects become strings.
• Error handling: event tracking calls can throw—always handle errors so the app stays robust.

MCP-first (source of truth)

If Clix MCP tools are available, treat them as the source of truth:

• clix-mcp-server:search_docs

  for conceptual behavior (campaign triggers, personalization)

• clix-mcp-server:search_sdk

  for exact SDK signatures per platform

If MCP tools are not available, use the bundled references:

• Event API contract + pitfalls →

  references/trackevent-contract.md

• Naming + schemas + privacy →

  references/naming-and-schema.md

• Implementation patterns →

  references/implementation-patterns.md

• Campaign mapping →

  references/campaign-mapping.md

• Debugging checklist →

  references/debugging.md

Workflow (copy + check off)

Event tracking progress:
- [ ] 1) Confirm platform(s) and goals (analytics vs campaign triggers)
- [ ] 2) Propose event plan (names, when fired, properties, where in code)
- [ ] 3) Validate plan (names, keys, types, PII constraints)
- [ ] 4) Implement trackEvent calls (platform-correct)
- [ ] 5) Verify: events fire once, serialize cleanly, match campaign configs

1) Confirm the minimum inputs

Ask only what’s needed:

• Platform: iOS / Android / React Native / Flutter
• Goal: analytics only, event-triggered campaigns, or both
• Top flows (1–3): e.g., onboarding, checkout, subscription
• PII policy: what must never be sent (email/phone/name/free-text, etc.)

2) Propose an “Event Plan” (before touching code)

Return a compact table the user can approve:

• event_name (stable,

  snake_case

  )
• when (exact moment the event fires)
• properties (key + type, mark required vs optional)
• location (file/function/UI handler/network response)
• purpose (campaign trigger / analytics / both)

If campaigns are involved, remind: event names and property keys must match exactly in the Clix console.

3) Validate the plan (fast feedback loop)

Create

event-plan.json

in

.clix/

directory (recommended) or project root:

Recommended location:

.clix/event-plan.json

• Organized: keeps tooling configs together
• Hidden: doesn't clutter project root
• Committable: planning document for team review

Alternative:

event-plan.json

in project root (simpler, but less organized)

For agents: Locate

scripts/validate-event-plan.sh

in the installed skill directory, then run it:

# From project root:
bash <skill-dir>/scripts/validate-event-plan.sh .clix/event-plan.json
# Or if in root:
bash <skill-dir>/scripts/validate-event-plan.sh event-plan.json

The skill directory is typically:

• .cursor/skills/event-tracking/

  (Cursor)

• .claude/skills/event-tracking/

  (Claude Code)

• .vscode/skills/event-tracking/

  (VS Code)

• .agents/skills/event-tracking/

  (Amp)
• Or check where this skill was installed

If validation fails: fix the plan first, then implement.

4) Implement tracking (platform-correct)

Use MCP to fetch the exact

trackEvent

signature for the platform; then:

• Place calls at stable boundaries (action confirmed, request succeeded, state updated)
• Avoid duplicates (don’t fire on every render; debounce where needed)
• Avoid null/complex values (prefer primitives; serialize dates to ISO)
• Do not track PII by default

See

references/implementation-patterns.md

for placement heuristics and code patterns.

5) Verify

Minimum verification:

• Event fires exactly once per user action (or the intended cadence)
• Properties are primitive + stable (no null surprises)
• For campaigns: console trigger conditions match exact names/keys

For troubleshooting steps, see

references/debugging.md

.