analyticscli-ts-sdk

Files (6)

• SKILL.md
• _meta.json
• minimal-host-template.md · references/
• onboarding-paywall.md · references/
• storage.md · references/
• versioning.md · references/

SKILL.md (first lines)

# AnalyticsCLI TypeScript SDK

## Use This Skill When

- adding AnalyticsCLI analytics to a JS or TS app
- instrumenting onboarding, paywall, purchase, or survey events
- upgrading within the current `@analyticscli/sdk` line
- validating SDK behavior together with `analyticscli`

## Supported Versions

- Skill pack: `1.6.8`
- Target package: `@analyticscli/sdk`
- Supported range: `>=0.1.0-preview.6 <0.2.0`
- If a future SDK major changes APIs or event contracts in incompatible ways, add a sibling skill such as `analyticscli-ts-sdk-v1`

See [Versioning Notes](references/versioning.md).

## Core Rules

- Initialize exactly once near app bootstrap.
- For generated host-app code, prefer `init({ ... })` with explicit identity mode (`identityTrackingMode: 'consent_gated'`).
- `init('<YOUR_APP_KEY>')` shortform is acceptable for quick demos/tests or low-level client-only integrations.
- Keep setup options minimal: `apiKey` is enough for ingest.
- In host apps, use client-safe publishable env names (for example `ANALYTICSCLI_PUBLISHABLE_API_KEY`).
- Do not use `WRITE_KEY` env names in generated host-app snippets (`ANALYTICSCLI_WRITE_KEY`, `EXPO_PUBLIC_ANALYTICSCLI_WRITE_KEY`, etc.).
- `runtimeEnv` is auto-attached. Do not pass a `mode` string.
- `debug` is only a boolean for SDK console logging.
- Do not pass `endpoint` and do not add endpoint env vars in app templates. Use the SDK default collector endpoint.
- For `platform`, do not use framework labels (`react-native`, `expo`).
- Use only canonical platform values (`web`, `ios`, `android`, `mac`, `windows`) or omit the field.
- In React Native/Expo, pass `Platform.OS` directly; the SDK normalizes values like `macos -> mac` and `win32 -> windows`.
- Treat `platform` as runtime family only (`web`/`ios`/`android`/`mac`/`windows`), not as OS version/name.
- Treat `osName` as operating-system label (for example `iOS`, `Android`, `Windows`, `macOS`, `Web`). Prefer always setting/populating `osName`; keep `platform` optional.
- `init(...)`/`new AnalyticsClient(...)` auto-emits one `session_start` event per client instance on SDK mount (`source: sdk_mount`), so host apps do not need manual startup wiring.
- Do not manually emit duplicate `session_start` unless you intentionally also track a separate custom launch event (for example `app_launch`).
- In React Native/Expo, prefer `appVersion` from `expo-application` (`nativeApplicationVersion`); nullable values can be passed directly.
- Do not specify `dedupeOnboardingStepViewsPerSession` in generated host-app code by default; SDK default is `true`. Only set it explicitly when the user requests a different behavior or asks for explicit config.
- Do not specify `dedupeScreenViewsPerSession` in generated host-app code by default; SDK default is `true`. Only set it explicitly when the user requests a different behavior or asks for explicit config.
- Set `screenViewDedupeWindowMs` only when needed for a non-standard navigation stack; otherwise rely on SDK default (`1200` ms).
- Prefer SDK trackers over host-side wrapper utilities. Keep integration code close to call sites.
- Keep event properties stable and query-relevant.
- Avoid direct PII.
- Set `identityTrackingMode` explicitly in generated host-app bootstrap code; use `'consent_gated'` as the default.
- For EU/EEA/UK user traffic, keep `identityTrackingMode: 'consent_gated'` (or `strict`) unless legal counsel approves a different setup.
- `identify` / `setUser` only work when full tracking is enabled (`always_on`, or after full-tracking consent in `consent_gated`).
- Do not force storage adapters in generated bootstrap code by default.
- Avoid top-level `Promise` singletons in app utility files.
- Use neutral file names like `analytics.ts` (not provider-specific names such as `aptabase.ts`).
- Avoid re-exporting `PAYWALL_EVENTS` / `PURCHASE_EVENTS` from host app utility files. Import SDK constants directly when needed, or use `createPaywallTracker(...)`.
- When using `createPaywallTracker(...)`, create one tracker per stable paywall context and reuse it across `shown`/`skip`/purchase calls. Recreate only when defaults change.
- If your paywall provider exposes an offering/paywall identifier, pass it as `offering` in tracker defaults.
  RevenueCat: offering identifier; Adapty: paywall/placement identifier; Superwall: placement/paywall identifier.
- In hosted paywall screens (RevenueCat UI / Adapty / Superwall or custom wrappers around them), do not use generic `track(...)` / `trackEvent(...)` for paywall or purchase milestones.
  Use one memoized `createPaywallTracker(...)` per screen/context and route lifecycle callbacks to tracker methods:
  `shown` (visible), `purchaseStarted`, one terminal event (`purchaseSuccess`/`purchaseFailed`/`purchaseCancel`), and `skip` (dismiss/close/back).
- If multiple paywall screens exist, each screen/context must have its own stable tracker defaults (`source`, `paywallId`, optional `offering`) so events are not mixed across screens.
- Prefer SDK identity helpers (`setUser`, `identify`, `clearUser`) directly instead of wrapping identify logic in host-app boilerplate.
- Do not keep legacy analytics providers or event aliases active in generated host-app code.
- For touched paywall/purchase/onboarding flows, use canonical AnalyticsCLI event names only.
- For generated docs or README snippets, write from tenant developer perspective (`your app`, `your workspace`) and avoid provider-centric phrasing such as `our SaaS`.
- Default to canonical SDK event names at call sites.
- Before generating host-app code, ensure `@analyticscli/sdk` is upgraded to the newest preview in that repo.
- For onboarding instrumentation, use dedicated SDK onboarding APIs instead of generic `track(...)`/`trackEvent(...)`:
  `createOnboardingTracker(...)`, `trackOnboardingEvent(...)`, `trackOnboardingSurveyResponse(...)`,
  plus step helpers (`step(...).view()`, `step(...).complete()`, `step(...).surveyResponse(...)`).
- Use `onboarding:step_view` as the default step progression signal. Treat `onboarding:step_complete` as optional and only emit it when a step has a meaningful completion boundary (for example explicit submit/continue confirmation or async success).
- For survey steps, default to `onboarding:step_view` + `onboarding:survey_response`; avoid unconditional `onboarding:step_complete` unless completion semantics are explicit.
- For onboarding survey events, prefer `trackOnboardingSurveyResponse(...)` (or tracker survey helpers) so SDK sanitization/normalization is preserved.
- To avoid repetitive payloads, create one onboarding tracker with shared flow defaults and use `step(...).surveyResponse(...)` with only survey-specific fields at call sites.
- For React Native / Expo non-onboarding screens, track screen views on focus with `useFocusEffect(...)` and `analytics.screen(...)`.
- For RevenueCat correlation in host apps, keep AnalyticsCLI user identity in sync with the same stable user id used in `Purchases.logIn(...)` (`setUser` on sign-in/session restore, `clearUser` on sign-out).

## Host App Minimalism Guardrails

When this skill writes host-app code, optimize for low boilerplate by default.

- Do not generate a large event translation layer such as `mapEventToCanonical(...)` with many `switch` branches.
- Do not create host-side wrappers around `identify`/`setUser` unless required by an existing app contract.
- Do not add per-call `try/catch` wrappers around every analytics helper unless the user asked for that policy.
- Do not duplicate SDK constants/events in host utility files.
- Prefer direct SDK calls in feature code (`trackPaywallEvent`, tracker helpers, `screen`, `track`) instead of generic proxy helpers.
- Keep a single screen-tracking owner per route boundary (parent layout or screen component, not both).
- If a thin `analytics.ts` is needed, keep it focused to bootstrap + a few shared helpers. Avoid becoming an event-translation layer.

## Hard Fail Patterns

Do not generate these patterns:

- giant `switch`/`if` trees that translate event names
- helpers like `mapEventToCanonical(...)` spanning many event cases
- broad catch-all wrappers around every analytics call
- top-level `Promise<AnalyticsClient | null>` bootstrap patterns
- host-side re-exports of SDK constants/events
- creating a new `createPaywallTracker(...)` instance inside each paywall callback/event helper
- helper wrappers that create a fresh paywall tracker per call (for example `trackPaywallTrackerEvent(...)`)
- hosted paywall screens that only emit `screen(...)` / `trackScreenView(...)` but never emit `paywall:shown`
- paywall/purchase milestones emitted via generic `track(...)` / `trackEvent(...)` although stable paywall context is available
- onboarding step/survey milestones emitted via generic `track(...)` / `trackEvent(...)` although dedicated onboarding APIs are available
- legacy/alias event names for onboarding/paywall/purchase milestones (for example `view_paywall`, `purchase_completed`)
- dual-write analytics emission to preserve old event names/providers
- `apiKey` fallback chains using `*WRITE_KEY*` env variables in host-app code
- duplicate screen tracking for the same route transition from both parent layout and child screen

If such a pattern already exists in the target codebase:
- do not expand it
- prefer reducing it while keeping behavior stable

## Pre-Ship Self-Check

Before finishing, verify the generated integration code meets all checks:

1. bootstrap uses `init({ ... })` (no `initFromEnv(...)`)
2. no explicit `endpoint` env var in host app templates
3. no large event translation layer added
4. SDK APIs used directly at call sites for onboarding/paywall/purchase milestones
5. identity uses SDK methods directly (`identify`/`setUser`/`clearUser`) without extra wrappers
6. `platform` is `web`/`ios`/`android`/`mac`/`windows` or omitted (never framework labels)
7. generated bootstrap sets `identityTrackingMode` explicitly (default `'consent_gated'`)

From LeoYeAI/openclaw-master-skills, MIT.

More from LeoYeAI/openclaw-master-skills