analyticscli-ts-sdk（analyticscli TS SDK 前端）

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.

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 offeringId 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 offeringId) 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')
8. paywall flow reuses a tracker instance per stable paywall context (no per-event tracker re-creation)
9. host-app snippets only use publishable API key env names (no *WRITE_KEY* fallback)
10. if provider exposes offering/paywall id, createPaywallTracker(...) defaults include offeringId
11. exactly one screen-tracking owner exists per route transition
12. touched onboarding/paywall/purchase call sites emit canonical AnalyticsCLI events only (no legacy aliases, no dual-write)
13. every touched hosted paywall screen emits paywall:shown via tracker when shown becomes visible (not only screen-view events)
14. every touched hosted paywall screen maps purchase lifecycle callbacks to tracker methods (purchaseStarted + exactly one terminal outcome)
15. every touched paywall dismissal path (close/back/skip) emits tracker skip(...)
16. touched onboarding step milestones use dedicated onboarding APIs (tracker step helpers or trackOnboardingEvent(...)) instead of generic track(...)
17. touched onboarding survey milestones use trackOnboardingSurveyResponse(...) (or tracker survey helpers), not ad-hoc generic track(...) payloads
18. touched React Native / Expo non-onboarding screens use useFocusEffect(...) + analytics.screen(...) with one owner per route transition
19. touched onboarding flows do not force onboarding:step_complete on every step; default to onboarding:step_view and add step_complete only where completion semantics are explicit

Dashboard Credentials Checklist

Before SDK bootstrap, collect the required values from your dashboard:

• Open dash.analyticscli.com and select the target project.
• In API Keys, copy the publishable ingest API key for SDK init.
• If you will verify ingestion with CLI, create/copy a CLI readonly_token in the same API Keys area.
• Optional for CLI verification: set a default project once with analyticscli projects select (arrow-key picker), or pass --project <project_id> per command.

Minimal Web Setup

import { init } from '@analyticscli/sdk';

const analytics = init({
  apiKey: process.env.NEXT_PUBLIC_ANALYTICSCLI_PUBLISHABLE_API_KEY ?? '',
  platform: 'web',
  identityTrackingMode: 'consent_gated', // default
});

init(...) is preferred for host apps. Resolve env values in app code and pass apiKey explicitly.

React Native Setup

import AsyncStorage from '@react-native-async-storage/async-storage';
import * as Application from 'expo-application';
import { Platform } from 'react-native';
import { init } from '@analyticscli/sdk';

const analytics = init({
  apiKey: process.env.EXPO_PUBLIC_ANALYTICSCLI_PUBLISHABLE_API_KEY,
  debug: __DEV__,
  platform: Platform.OS,
  appVersion: Application.nativeApplicationVersion,
  identityTrackingMode: 'consent_gated', // default
  storage: AsyncStorage, // optional for RN if you want persistent IDs after consent
});

Consent gate for full tracking:

// user accepts full tracking
analytics.setFullTrackingConsent(true);

// user declines full tracking (strict analytics can continue)
analytics.setFullTrackingConsent(false);

There is no "do not start yet" init flag. Tracking starts on init(...); ready() (or initAsync(...)) is only for explicitly blocking first-flow logic until async storage hydration is done.

React Native Screen Tracking Pattern (Non-Onboarding)

Use useFocusEffect(...) for non-onboarding screens so screen views fire on route focus and not only on mount:

import { useFocusEffect } from '@react-navigation/native';
import { useCallback } from 'react';
import { analytics } from '@/utils/analytics';

export function SettingsScreen() {
  useFocusEffect(
    useCallback(() => {
      analytics.screen('settings', {
        screen_class: 'SettingsScreen',
        source: 'tabs',
      });
    }, []),
  );

  return null;
}

Notes:

• Keep exactly one screen-tracking owner per route transition.
• Do not emit duplicate screen events from both parent layout and child screen.
• For onboarding steps, do not replace onboarding milestone events with screen events.

Integration Depth Checklist

The integration should cover more than SDK bootstrap:

1. onboarding flow boundaries and step progression
2. paywall exposure, skip, purchase start, success, fail, cancel
3. screen views for core routes/screens
4. key product actions tied to user value (for example: first calibration complete, first result generated, export/share, restore purchases)
5. stable context properties (appVersion, platform, source, flow identifiers)
6. if using RevenueCat, correlate client-side paywall/purchase intent with server-side subscription lifecycle updates

RevenueCat + Analytics Sync (Trials & Subscriptions)

You can include trial/purchase/cancel lifecycle data inside user flows, but "perfectly synced in real time" is not realistic because app callbacks, store billing events, retries, and webhook delivery are eventually consistent.

Use this pattern for near-lossless correlation:

1. Single identity key across both systems

- Use the same stable app user id for RevenueCat appUserID and AnalyticsCLI analytics.setUser(...) (or setUser(...) on raw client). - Do not rely on anonymous ids alone for subscription lifecycle analysis.

1. Dual event streams

- Client stream (SDK): paywall and purchase journey intent (paywall:shown, purchase:started, purchase:success/failed/cancel). - Server stream (RevenueCat webhook): authoritative billing lifecycle changes (trial started, trial cancelled, renewal, subscription cancelled/expired, billing issue).

1. Correlation keys on every relevant event

- Always include stable keys when available: userId, offeringId, paywallId, packageId, entitlementKey. - For webhook-derived events, also include RevenueCat identifiers from payload (rcEventId, rcEventType, original transaction/subscription ids, environment/store).

1. Webhook idempotency is mandatory

- Deduplicate webhook ingestion by RevenueCat event id before emitting analytics events. - Replays/retries must not create duplicate cancellation or renewal events.

1. Model cancellation reasons explicitly

- Persist store/webhook cancellation reason fields when provided (or unknown). - Cancellation can happen outside the app; only webhook ingestion gives reliable coverage.

Recommended custom lifecycle events (in addition to canonical purchase:* journey events):

• billing:trial_started
• billing:trial_cancelled
• billing:trial_converted
• billing:subscription_renewed
• billing:subscription_cancelled
• billing:subscription_expired
• billing:billing_issue

This split lets funnels answer both questions:

• Journey intent: "what users did in-app before purchase/cancel"
• Billing truth: "what subscription state changed in the store/backend"

Instrumentation Rules

• Use createOnboardingTracker(...) for onboarding flows.
• For onboarding steps in touched flows, prefer createOnboardingTracker(...).step(...).view()/complete() over generic track(...).
• For low-noise step funnels, use view() as baseline and call complete() only on steps with explicit completion semantics.
• For onboarding surveys in touched flows, prefer trackOnboardingSurveyResponse(...) or tracker survey helpers over generic track(...).
• For survey steps, default to view() + surveyResponse(...); emit complete() only when the host flow has a real completion boundary.
• Prefer tracker defaults for repeated fields in onboarding/survey flows; avoid re-sending unchanged flow metadata at every call site.
• For React Native / Expo non-onboarding screens, use useFocusEffect(...) to call analytics.screen(...) on focus.
• Use createPaywallTracker(...) when paywall context is stable in a flow (source, paywallId, experiment variant).
• Keep createPaywallTracker(...) instance lifetime aligned to one stable paywall context (for example one screen flow); do not create a new tracker for every paywall event.
• Include offeringId in paywall tracker defaults when available from provider metadata (RevenueCat/Adapty/Superwall). This is strongly recommended for reliable paywall funnel segmentation.
• Use trackPaywallEvent(...) for one-off paywall and purchase milestones.
• Hosted paywall callback mapping is mandatory for touched flows:

- paywall visible callback -> paywallTracker.shown(...) - purchase started callback -> paywallTracker.purchaseStarted(...) - purchase success callback -> paywallTracker.purchaseSuccess(...) - purchase cancelled callback -> paywallTracker.purchaseCancel(...) - purchase error callback -> paywallTracker.purchaseFailed(...) - close/back/dismiss callback -> paywallTracker.skip(...)

• Use canonical event names from ONBOARDING_EVENTS, PAYWALL_EVENTS, and PURCHASE_EVENTS.
• Keep onboardingFlowId, onboardingFlowVersion, paywallId, source, and appVersion stable.
• The SDK built-in dedupe covers onboarding:step_view (dedupeOnboardingStepViewsPerSession: true, default), immediate duplicate screen(...) calls (dedupeScreenViewsPerSession: true, default; window screenViewDedupeWindowMs, default 1200 ms), and immediate overlap between onboarding screen:* and onboarding:step_view for the same step (dedupeOnboardingScreenStepViewOverlapsPerSession: true, default).
• Prevent duplicate tracking for the same user action across nested layouts/components.
• Use a single tracking owner per route or lifecycle boundary; if multiple hooks can fire, gate with a session-local idempotency key.
• For each paywall attempt, emit each milestone once (paywall:shown, purchase:started, and one terminal event: purchase:cancel or purchase:failed or purchase:success).

No-Legacy Policy

For pre-production integrations, do not preserve legacy compatibility by default:

1. Remove legacy analytics providers from touched flows instead of dual-writing.
2. Replace legacy/alias milestone names with canonical AnalyticsCLI events in the same change.
3. Prefer dedicated SDK helpers (createOnboardingTracker(...), trackOnboardingSurveyResponse(...), createPaywallTracker(...)) over ad-hoc generic tracking wrappers.

Validation Loop

After integration or upgrade, verify ingestion with stable CLI checks:

analyticscli schema events
analyticscli goal-completion --start onboarding:start --complete onboarding:complete --last 30d
analyticscli get onboarding-journey --last 30d --format text

References

• Onboarding And Paywall Contract
• Minimal Host Template
• Storage Options
• Versioning Notes