# Showcase Analytics SDK

Contract version: 2

## Start here

1. Verify the Product website in Workspace > Settings.
2. Open Workspace > Analytics, create the install key, and use the generated framework instructions.
3. Grant consent in a test visit and return to Analytics to verify the first page view.
4. Choose the Product primary goal, then add one meaningful lifecycle event.

The SDK automatically records consented session, landing, and page-view activity. It also reads only bounded `utm_source` and `utm_campaign` tags for campaign reporting.

## Browser install

```html
<script defer src="https://showcase.example/a.js?v=2" data-product="sh_pk_YOUR_PUBLIC_KEY" data-consent="required"></script>
```

Grant consent only after your own consent flow allows collection:

```js
showcaseAnalytics.consent('granted')
showcaseAnalytics.identify('opaque_product_user_id')
showcaseAnalytics.track('signup_completed')
showcaseAnalytics.reset()
```

Only send opaque product-scoped identifiers. Do not send email, name, phone number, authentication tokens, message bodies, or arbitrary customer records.

## Signed server events

Create or rotate the one-time server secret in Product Workspace > Analytics. POST raw JSON to `/api/analytics/server/:productId` with:

- `X-Showcase-Timestamp`: current 10-digit Unix seconds
- `X-Showcase-Nonce`: unique 16-128 character value matching `^[A-Za-z0-9._:-]{16,128}$`
- `X-Showcase-Signature`: `v1=<hex HMAC-SHA256>`

Sign exactly:

```text
timestamp + "." + nonce + "." + rawBody
```

Server request timestamps must be within five minutes. Event `occurredAt` may be backfilled up to seven days. Reuse the same event ID when retrying the same business event.

## Standard events

- `page_view`
- `landing_viewed`
- `cta_clicked`
- `outbound_click`
- `signup_started`
- `signup_completed`
- `onboarding_started`
- `onboarding_completed`
- `activation_completed`
- `feature_used`
- `content_created`
- `project_created`
- `invite_sent`
- `session_started`
- `returning_session`
- `reactivated`
- `trial_started`
- `checkout_started`
- `purchase_completed`
- `subscription_started`
- `subscription_renewed`
- `subscription_cancelled`
- `refund_completed`
- `account_deleted`
- `account_inactive`

## Product dashboard

The owner dashboard provides 7/30-day trends and previous-period comparison, acquisition source/referrer/country/device/campaign breakdowns, a primary success goal, observed funnel stages, retention cohorts, monetization/churn signals, CSV export, and a copyable plain-language summary.

Untracked funnel stages are hidden rather than shown as zero. Small acquisition/cohort groups are privacy-thresholded. Public Traffic disclosure is managed separately in Workspace > Traction.

## Verification

1. Verify the canonical Product origin.
2. Create the public browser key.
3. Install the snippet once at the application root.
4. Confirm no event appears before consent.
5. Grant consent and trigger a page view plus one lifecycle event.
6. Use the Product Analytics debugger to confirm sanitized accepted events.
7. Retry an event with the same ID and confirm it does not double count.
8. Confirm logout/account switch calls `showcaseAnalytics.reset()`.
9. Create a server secret and send one signed server event.
10. Confirm the debugger shows `server` trust without visitor/session hashes.

Machine-readable schema: `/docs/analytics/schema.json`