{"id":"7803e325-ff3d-48a2-98bb-ee334fe22c98","shortId":"9PAf9c","kind":"skill","title":"tracking-events","tagline":"Works with Altertable product analytics events, user identification, and aliasing. Use when tracking events, identifying users, managing traits, or resolving identities.","description":"# Tracking Events\n\n## Quick Start\n\n1. **Track an event**: Call the track API or SDK method with event name and properties\n2. **Identify a user**: Link anonymous activity to a known user after authentication\n3. **Query events**: Use SQL to analyze tracked events and identity traits\n\n## When to Use This Skill\n\n- Tracking user actions (page views, purchases, feature usage)\n- Identifying users after login or signup\n- Updating user traits (plan, email, account state)\n- Aliasing identifiers across systems (Stripe, CRM, legacy IDs)\n- Querying event data or identity traits via SQL\n- Building funnels, cohorts, or retention analysis from events\n\n## Event Model\n\nAll SDKs and the API share the same payload shape:\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `event` | Yes | Event name, e.g. `Checkout Completed` |\n| `properties` | No | Event attributes for filtering and analysis |\n| `distinct_id` | No | User or device identifier (client SDKs set automatically) |\n| `timestamp` | No | Server uses current time when omitted |\n\n## Tracking Events\n\n### Via API\n\n```bash\ncurl -X POST https://api.altertable.ai/track \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"event\":\"Purchase Completed\",\n    \"environment\":\"production\",\n    \"distinct_id\":\"u_01jza857w4f23s1hf2s61befmw\",\n    \"properties\":{\"amount\":99.99,\"currency\":\"USD\"}\n  }'\n```\n\n### Via SDK (TypeScript)\n\n```typescript\naltertable.track('Purchase Completed', {\n  amount: 99.99,\n  currency: 'USD'\n});\n```\n\n### Auto-Capture\n\nClient-side SDKs automatically capture page/screen views. Disable with:\n\n```typescript\naltertable.init('YOUR_API_KEY', { autoCapture: false });\naltertable.page('https://example.com/products');\n```\n\nServer-side SDKs (Python, Ruby) do not auto-capture pages.\n\n## Identifying Users\n\nCall `identify()` after authentication to link anonymous activity to a known user.\n\n### Via API\n\n```bash\ncurl -X POST https://api.altertable.ai/identify \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"environment\":\"production\",\n    \"distinct_id\":\"u_01jza857w4f23s1hf2s61befmw\",\n    \"traits\":{\"plan\":\"premium\",\"email\":\"user@example.com\"}\n  }'\n```\n\n### Via SDK (TypeScript)\n\n```typescript\naltertable.identify('u_01jza857w4f23s1hf2s61befmw', {\n  plan: 'premium',\n  email: 'user@example.com'\n});\n```\n\n### Updating Traits\n\nAfter identification, update traits as account state changes:\n\n```typescript\naltertable.updateTraits({ plan: 'enterprise', onboarding_completed: true });\n```\n\nServer-side SDKs update traits by calling `identify()` again with new trait values.\n\n### Session Reset\n\nCall `reset()` on logout to clear identity context:\n\n```typescript\naltertable.reset();\naltertable.reset({ resetDeviceId: true }); // also clears device ID\n```\n\n## Aliasing Users\n\nUse `alias()` to link multiple identifiers to the same user profile. This is for ID migrations and external system IDs, not for login flows (use `identify()` for those).\n\n### When to Use alias() vs identify()\n\n| Scenario | Method |\n|----------|--------|\n| Login or signup | `identify()` |\n| Known user on another device | `identify()` |\n| Migrate from old ID format | `alias()` |\n| Attach CRM or billing ID | `alias()` |\n| Merge profiles across platforms | `alias()` |\n\n### Via API\n\n```bash\ncurl -X POST https://api.altertable.ai/alias \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"environment\":\"production\",\n    \"distinct_id\":\"user_123\",\n    \"new_user_id\":\"stripe:cus_abc123\"\n  }'\n```\n\n### Via SDK (TypeScript)\n\n```typescript\naltertable.alias(`stripe:${stripeCustomerId}`);\naltertable.alias(`hubspot:${hubspotContactId}`);\n```\n\n## Querying Events\n\n### Event Counts by Type\n\n```sql\nSELECT\n  event,\n  properties->>'currency' AS currency,\n  COUNT(*) AS total\nFROM altertable.analytics.events\nGROUP BY ALL\nORDER BY total DESC;\n```\n\n### Events with Identity Traits\n\n```sql\nSELECT\n  e.event,\n  e.properties,\n  e.timestamp,\n  e.identity_traits->>'email' AS email,\n  e.identity_traits->>'plan' AS plan\nFROM altertable.analytics.events e\nWHERE e.distinct_id = 'u_01jza857w4f23s1hf2s61befmw'\nORDER BY e.timestamp DESC;\n```\n\n### Identity Traits\n\n```sql\nSELECT\n  distinct_id,\n  traits->>'email' AS email,\n  traits->>'plan' AS plan,\n  updated_at\nFROM altertable.analytics.identities\nORDER BY updated_at DESC;\n```\n\n## Available SDKs\n\n| Language | Install |\n|----------|---------|\n| TypeScript/JS | `npm install @altertable/altertable-js` |\n| React | `npm install @altertable/altertable-js @altertable/altertable-react` |\n| Python | `pip install altertable` |\n| Ruby | `gem install altertable` |\n| Swift | Swift Package Manager |\n| Kotlin | `implementation(\"ai.altertable.sdk:altertable-kotlin:0.1.0\")` |\n\n## Common Pitfalls\n\n1. **Not identifying after page reload** - Call `identify()` after authentication, including after full page loads when user is already authenticated\n2. **Using alias() for login flows** - Use `identify()` for login/signup, `alias()` for ID migrations and external system links\n3. **Missing distinct_id in server-side calls** - Server-side SDKs require you to pass `distinct_id` explicitly\n4. **Forgetting reset() on logout** - Future events get attributed to the previous user\n5. **Sensitive data in traits** - Never send secrets or regulated sensitive data in traits or event properties\n\n## Reference Files\n\n- [Event tracking details](references/event-tracking.md) - Read when working with SSR setup, tracking consent, auto-capture configuration, or platform-specific behavior\n- [Identity and aliasing](references/identity-and-aliasing.md) - Read when implementing login/signup flows, session reset, alias migrations, or querying identity data","tags":["tracking","events","skills","altertable-ai","agent-skills","ai-agents","altertable"],"capabilities":["skill","source-altertable-ai","skill-tracking-events","topic-agent-skills","topic-ai-agents","topic-altertable"],"categories":["skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/altertable-ai/skills/tracking-events","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add altertable-ai/skills","source_repo":"https://github.com/altertable-ai/skills","install_from":"skills.sh"}},"qualityScore":"0.453","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 7 github stars · SKILL.md body (5,754 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:14:20.766Z","embedding":null,"createdAt":"2026-05-18T13:21:55.499Z","updatedAt":"2026-05-18T19:14:20.766Z","lastSeenAt":"2026-05-18T19:14:20.766Z","tsv":"'/alias':433 '/identify':275 '/products'');':240 '/track':179 '0.1.0':578 '01jza857w4f23s1hf2s61befmw':200,293,305,519 '1':29,581 '123':451 '2':45,601 '3':58,619 '4':639 '5':652 '99.99':203,214 'abc123':457 'account':94,317 'across':98,422 'action':77 'activ':51,262 'ai.altertable.sdk':574 'alia':363,393,413,419,424,603,611,703 'alias':13,96,360,694 'alreadi':599 'also':356 'altert':6,563,567,576 'altertable-kotlin':575 'altertable.alias':462,465 'altertable.analytics.events':485,513 'altertable.analytics.identities':541 'altertable.identify':303 'altertable.init':231 'altertable.page':237 'altertable.reset':352,353 'altertable.track':210 'altertable.updatetraits':321 'altertable/altertable-js':554,558 'altertable/altertable-react':559 'amount':202,213 'analysi':117,149 'analyt':8 'analyz':64 'anonym':50,261 'anoth':405 'api':36,126,172,184,233,268,280,426,438 'api.altertable.ai':178,274,432 'api.altertable.ai/alias':431 'api.altertable.ai/identify':273 'api.altertable.ai/track':177 'application/json':190,286,444 'attach':414 'attribut':145,647 'authent':57,258,590,600 'author':181,277,435 'auto':218,250,684 'auto-captur':217,249,683 'autocaptur':235 'automat':160,224 'avail':547 'bash':173,269,427 'bearer':182,278,436 'behavior':691 'bill':417 'build':112 'call':33,255,334,343,587,627 'captur':219,225,251,685 'chang':319 'checkout':140 'clear':348,357 'client':157,221 'client-sid':220 'cohort':114 'common':579 'complet':141,194,212,325 'configur':686 'consent':682 'content':188,284,442 'content-typ':187,283,441 'context':350 'count':471,481 'crm':101,415 'curl':174,270,428 'currenc':204,215,478,480 'current':165 'cus':456 'd':191,287,445 'data':106,654,663,708 'desc':492,523,546 'descript':134 'detail':673 'devic':155,358,406 'disabl':228 'distinct':150,197,290,448,528,621,636 'e':514 'e.distinct':516 'e.event':499 'e.g':139 'e.identity':502,507 'e.properties':500 'e.timestamp':501,522 'email':93,297,308,504,506,531,533 'enterpris':323 'environ':195,288,446 'event':3,9,17,26,32,41,60,66,105,119,120,135,137,144,170,192,469,470,476,493,645,667,671 'example.com':239 'example.com/products'');':238 'explicit':638 'extern':379,616 'fals':236 'featur':81 'field':132 'file':670 'filter':147 'flow':385,606,700 'forget':640 'format':412 'full':593 'funnel':113 'futur':644 'gem':565 'get':646 'group':486 'h':180,186,276,282,434,440 'hubspot':466 'hubspotcontactid':467 'id':103,151,198,291,359,376,381,411,418,449,454,517,529,613,622,637 'ident':24,68,108,349,495,524,692,707 'identif':11,313 'identifi':18,46,83,97,156,253,256,335,367,387,395,401,407,583,588,608 'implement':573,698 'includ':591 'instal':550,553,557,562,566 'key':185,234,281,439 'known':54,265,402 'kotlin':572,577 'languag':549 'legaci':102 'link':49,260,365,618 'load':595 'login':86,384,398,605 'login/signup':610,699 'logout':346,643 'manag':20,571 'merg':420 'method':39,397 'migrat':377,408,614,704 'miss':620 'model':121 'multipl':366 'name':42,138 'never':657 'new':338,452 'npm':552,556 'old':410 'omit':168 'onboard':324 'order':489,520,542 'packag':570 'page':78,252,585,594 'page/screen':226 'pass':635 'payload':130 'pip':561 'pitfal':580 'plan':92,295,306,322,509,511,535,537 'platform':423,689 'platform-specif':688 'post':176,272,430 'premium':296,307 'previous':650 'product':7,196,289,447 'profil':372,421 'properti':44,142,201,477,668 'purchas':80,193,211 'python':245,560 'queri':59,104,468,706 'quick':27 'react':555 'read':675,696 'refer':669 'references/event-tracking.md':674 'references/identity-and-aliasing.md':695 'regul':661 'reload':586 'requir':133,632 'reset':342,344,641,702 'resetdeviceid':354 'resolv':23 'retent':116 'rubi':246,564 'scenario':396 'sdk':38,207,300,459 'sdks':123,158,223,244,330,548,631 'secret':659 'select':475,498,527 'send':658 'sensit':653,662 'server':163,242,328,625,629 'server-sid':241,327,624,628 'session':341,701 'set':159 'setup':680 'shape':131 'share':127 'side':222,243,329,626,630 'signup':88,400 'skill':74 'skill-tracking-events' 'source-altertable-ai' 'specif':690 'sql':62,111,474,497,526 'ssr':679 'start':28 'state':95,318 'stripe':100,455,463 'stripecustomerid':464 'swift':568,569 'system':99,380,617 'time':166 'timestamp':161 'topic-agent-skills' 'topic-ai-agents' 'topic-altertable' 'total':483,491 'track':2,16,25,30,35,65,75,169,672,681 'tracking-ev':1 'trait':21,69,91,109,294,311,315,332,339,496,503,508,525,530,534,656,665 'true':326,355 'type':189,285,443,473 'typescript':208,209,230,301,302,320,351,460,461 'typescript/js':551 'u':199,292,304,518 'updat':89,310,314,331,538,544 'usag':82 'usd':205,216 'use':14,61,72,164,362,386,392,602,607 'user':10,19,48,55,76,84,90,153,254,266,361,371,403,450,453,597,651 'user@example.com':298,309 'valu':340 'via':110,171,206,267,299,425,458 'view':79,227 'vs':394 'work':4,677 'x':175,271,429 'yes':136","prices":[{"id":"f976f888-95e6-41ad-8de5-be34f788922e","listingId":"7803e325-ff3d-48a2-98bb-ee334fe22c98","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"altertable-ai","category":"skills","install_from":"skills.sh"},"createdAt":"2026-05-18T13:21:55.499Z"}],"sources":[{"listingId":"7803e325-ff3d-48a2-98bb-ee334fe22c98","source":"github","sourceId":"altertable-ai/skills/tracking-events","sourceUrl":"https://github.com/altertable-ai/skills/tree/main/skills/tracking-events","isPrimary":false,"firstSeenAt":"2026-05-18T13:21:55.499Z","lastSeenAt":"2026-05-18T19:14:20.766Z"}],"details":{"listingId":"7803e325-ff3d-48a2-98bb-ee334fe22c98","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"altertable-ai","slug":"tracking-events","github":{"repo":"altertable-ai/skills","stars":7,"topics":["agent-skills","ai-agents","altertable"],"license":"mit","html_url":"https://github.com/altertable-ai/skills","pushed_at":"2026-05-14T10:34:10Z","description":"Agent Skills for Altertable","skill_md_sha":"6b4992d477a001e678f0f7467b386078ad14b07f","skill_md_path":"skills/tracking-events/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/altertable-ai/skills/tree/main/skills/tracking-events"},"layout":"multi","source":"github","category":"skills","frontmatter":{"name":"tracking-events","description":"Works with Altertable product analytics events, user identification, and aliasing. Use when tracking events, identifying users, managing traits, or resolving identities.","compatibility":"Requires Altertable MCP server"},"skills_sh_url":"https://skills.sh/altertable-ai/skills/tracking-events"},"updatedAt":"2026-05-18T19:14:20.766Z"}}