Rifflets analytics contract

Status: October 5, 2026. Dan authorized deployment for invited co-founders and friends, private nickname-to-browser reporting, and traffic classification that separates likely visitors, agents and registered internal tests. The invited-test release uses automatic collection; ordinary developer builds remain off. The verified deployment URL and live smoke results are recorded in releases and STATUS.md after rollout. No audience results are inferred from tests.

Purpose and architecture

Creators first need understandable engagement counts: encounters, opens, meaningful tries, active time, the number of different Rifflets tried, repeat attempts and return visits. App-specific milestones and a true final finish are secondary measures because progress means different things across experiences. Building agents also need release-specific action sequences, stages, controls, errors, performance and device context so they can propose and test improvements. Collect broadly during internal testing, then use measured volume and utility to narrow the schema.

The shared runtime and SDK send to one first-party collector, with separate private analytics tables in the existing Pages/D1 architecture. The dashboard and aggregate JSON serve creator-style analysis; authenticated raw samples serve internal agent diagnosis. Existing public feedback/history is a separate, explicitly submitted publication flow. Never append behavioral records or IPs to public feedback.

Feed and Lab use links; the viewer embeds one app. There is no autoplay fleet. The automatic bridge covers every published route, Feed and Lab card impressions. The current source upgrade migrates every published route to reviewed rifflet.analytics/0.2 semantics; see [the coverage inventory](docs/COMMON_INFRA_COVERAGE.md) for exact meanings and browser/source evidence. This source statement is not a deployment receipt. Historical releases may lack milestone events or use a broader legacy goal. Do not infer correctness or a full-experience finish from content.json.completionEvent alone.

Required creator contract

Every new or substantially revised Rifflet must:

1. Supply apps/<slug>/analytics.json using rifflet.analytics/0.2, with a documented first meaningful action, up to 12 honest intermediate milestones, a true final completion or null, reset/stop boundaries and bounded interaction mappings. Each event has one semantic role. A finite completion must match content.json.completionEvent. For an open-ended app, explicitly map that legacy manifest event to one milestone or stop role; never rename an intermediate achievement as a final finish merely to fill a dashboard. The registry still reads 0.1 contracts for frozen source compatibility, but current published apps must use 0.2.
2. Emit those facts through createRuntime().emit(type, detail). The common bridge supplies identity, device, release, transport and lifecycle. Do not install an independent analytics client or upload arbitrary detail objects.
3. Keep play, editing and accessibility working with analytics off, blocked, unavailable, storage denied, timed out or at capacity. Never await delivery to advance play.
4. Use the build's actual app ID, version and immutable source commit. The build manifest is authoritative when a legacy runtime has stale version text; a bounded runtime_version_mismatch diagnostic flags it. Dirty previews are explicitly unpinned and accepted only by the local test server. Actor remains a backward-compatible declaration, not identity proof; traffic classification uses signed QA context and bounded browser/edge evidence while preserving unknown when evidence is insufficient.
5. Use reviewed bounded numeric, boolean and enum detail fields. Unknown fields are discarded before transport and rejected by the server. New fields require coordinated schema/client/server review and a statement of the question they answer.
6. Test event meaning, not just shape, and submit source-linked evidence with the release. Report unavailable metrics explicitly. A plan finished is not food cooked; a copied link is not delivery; a displayed solution is not a player solving it. Test intermediate milestones separately from finishing the entire defined experience.

The 0.2 shape is start: {event,meaning}, required milestones: [{key,event,meaning,valueField?}], and completion: {event,meaning} | null, followed by the existing lifecycle and interaction mappings. Keys and events are bounded lowercase tokens. valueField, when present, names a reviewed emitted integer field whose values are 0–10000. A single-step experience may use an empty milestones array. Do not invent progress events.

The SDK method milestone(key, index?) emits a milestone inside the current attempt and keeps that attempt open. It deduplicates the same key/index; without an explicit index it assigns the next index for that key. complete() is reserved for the reviewed final hook, emits completed with {kind:'final'}, and closes the attempt. Previously stored completed records with {} remain historical goal evidence and must be reported as legacyGoalAttempts, not retroactively described as verified full-experience finishes.

Common data and ownership

The exact event envelope is rifflet.event/0.2, the batch envelope rifflet.analytics-batch/0.2, and collection policy rifflet.internal-test/0.1. Executable field definitions live in shared/analytics-contract.js and shared/analytics-device.js.

Each event includes random event ID, optional persistent browser ID, session/view/attempt IDs, monotonic view sequence, client time, app ID/version/commit, surface, entry surface, actor, collection policy and a cached passive device snapshot. Browser identity lasts 30 days; sessions expire after 30 minutes idle. Attempts keep their original identity so long attempts are not split by rotation. Denied storage uses an ephemeral session and browserId:null. Clearing storage starts a new profile; the service does not relink it.

The authorized private browser directory may show an observed shared/identity.js nickname history beside the independent analytics browser ID. This is private operator evidence for recognizing a browser profile, not authentication or a public identity. Generated aliases can repeat. Never use an alias as a key, upload the identity module's opaque local ID to public scoreboards, infer a MAC address, fingerprint a device, join profiles across devices, or resurrect a profile after storage is cleared. Public scoreboard names remain explicit, consented submissions and are not backfilled from analytics. Existing alias reset semantics remain: confirm the exact old/new name, preserve progress, and leave earlier public posts under the earlier name.

Device context includes bounded user agent, platform, languages, timezone, screen and viewport dimensions, pixel ratio, touch capability, CPU count, available memory/network hints, reduced-motion/color/pointer preferences and API availability flags. These are passive observations; no permission requests or camera/microphone/sensor access. Missing properties are null or documented defaults. Request IP is read only from trusted CF-Connecting-IP, validated, and stored separately from the client payload. It is available in private raw exports; aggregates expose only the distinct address count. IPs are not people or stable identities.

No secrets, typed answers/free text, shared-link payloads, full URLs/referrers/query strings, DOM snapshots, images, audio, sensor samples, raw exception text or stacks are uploaded. Control identifiers use stable IDs or positional tokens, never text labels. Only range numeric values, checkbox/radio state and select option index are captured by the generic control observer. The raw trace contains IDs and IP and is private operational data; it must not be mistaken for a creator-safe aggregate.

Generic diagnostics are capped at 1,000 accepted observations per document view. Runtime details are not bulk uploaded: allowed keys and ranges in sanitizeAppFields define the retained subset. All events are initially unsampled within these bounds. Custom sharing paths and canvas gestures without runtime events may remain partially observed; coverage review should name those gaps.

Metrics and agent evidence

• Unique players: distinct non-null analytics browser IDs with at least one meaningful start in the selected report window. These estimate playing browser profiles, not verified people. Passive impressions and opens do not count.
• Starts: attempts begun by the app’s reviewed first meaningful action, including a replay or restart. A start is neither a page load nor a milestone or final finish. The dashboard shows the current app-specific meaning beside its progress details; historical contracts remain release-specific.
• Observed browsers: persistent IDs, not people. Storage denial/clearing, shared devices, blockers and identity expiry affect counts.
• Observed UI interaction: all published apps can report trusted click/change controls. Count distinct interacted apps per browser and returns across sessions, excluding Feed/Lab card navigation. Settings and share controls count; this is not a meaningful-play claim.
• Tried breadth: distinct app IDs with reviewed meaningful starts per browser. Repeat attempts and releases do not count as additional apps; original editions have separate IDs.
• Open-to-start: opened views with a start divided by opened views, matched on browser/session/view/app/release.
• Milestones reached: milestone event count, attempts with milestones and per-key count/attempt/max-index. A milestone does not imply the app was finished.
• Finished the full experience: unique attempts started in the selected UTC window that emit the reviewed final completion by its end, divided by starts. Apps with completion:null display “Open-ended — no final finish.” Historical releases without 0.2 evidence display “Not recorded in this release.” Orphans and completion after terminal events are excluded; in-flight attempts can be incomplete observations.
• Legacy goal attempts: attempts containing historical completed {} events. Retained for backward compatibility, never merged into verified final-finish counts.
• Repeat attempts: another attempt of the same app in one session. Return: an earlier meaningful start in a different observed session, within retained history.
• D1/D7: first observed meaningful start in retained history, followed by a start on exactly the next/seventh UTC day. Only fully elapsed target days qualify; show eligible and returned counts. This is not lifetime acquisition retention.
• Active play time: recent-input foreground time from attempts started in the selected report window, including their valid samples through the report end. It is not enjoyment, attention or learning. It undercounts quiet reading/listening/breathing, and concurrent tabs can overlap. Total time includes null-browser sessions; play time per player uses only time linked to known playing browser IDs, divided by their unique count. With no known players the average is unavailable, not zero.
• Repeat visits per player (7d): count distinct playing sessions per known browser within (report end − 7 days, report end], subtract the first session for each browser, then divide by unique players in that same rolling window. For example, three sessions for one player plus one session for another is two repeat visits / two players = 1.0. Multiple rounds or attempts in the same session do not add repeats. The session idle rule is 30 minutes; this is not next-day retention. Display repeat-session and repeated-player counts beside the average.
• Diagnostics: event and control counts, runtime actions, error categories, device distribution, timing samples/median/p95 and estimated payload bytes. Device distributions count each observed browser or ephemeral session once per scope. Top groups are capped at 50. Payload bytes exclude transport/storage overhead.

Lead reports with engagement, then show per-app milestones and final finishes with the registry's actual meanings. Do not publish one aggregate completion percentage across incomparable apps. Always separate traffic classifications, actor declarations and release versions, show denominators and instrumentation coverage, and use unavailable for undefined rates. Synthetic tests are not human demand; before/after comparisons are not causal. No analytics results are fabricated by this implementation.

Private GET /api/analytics/summary returns rifflet.analytics-summary/0.1; GET /api/analytics/evidence requires an app filter and returns the same scoped structure. They include aggregate totals, per-app/release measures, entry surfaces, traffic evidence, coverage, definitions and limitations, without visitor/session/attempt IDs or nicknames. Dates are inclusive UTC, at most 30 days; earlier retained events support return calculations. Actor may be all; traffic may be all, visitors, human-likely, agent, internal-test or unknown. “Visitors” combines human-likely and unknown, and the UI must disclose that unknown can include automation.

Traffic classification is evidence, not verified human identity. A valid registered QA context takes priority, followed by automation evidence, explicit actor declaration, and limited positive interaction evidence; missing edge signals remain null rather than false. Never classify solely from IP, nickname, click trust, or the absence of webdriver. Preserve unknown when evidence is insufficient and expose the bounded reason codes used. Filter complete browser/session evidence consistently before attempt aggregation so late evidence does not selectively remove its earlier start.

Private GET /api/analytics/events?from=YYYY-MM-DD&to=YYYY-MM-DD&actor=all&traffic=visitors&app=water-jugs&limit=500 returns at most 500 retained raw observations with device, IDs, classification, receipt time and trusted IP, newest receipt first. Private GET /api/analytics/browsers returns at most 100 browser profiles with observed nickname history and per-app engagement. truncated:true means a sample is incomplete; no pagination/full-history export is promised. For agent use, scope to its app, inspect release and chronology, and avoid exposing other apps' traces. Access is currently operator-level, not creator-specific authorization.

For each proposed improvement an agent should record: question, app/release/window, sample and missing coverage, observed action or failure pattern, alternative explanations, hypothesis, proposed change, acceptance test and resulting release. The evidence supports tuning; it does not authorize an automatic production change or optimizing time spent at the expense of the experience.

Internal collection profile and access

Per Dan's October 2 instruction, the internal test build collects automatically and adds no disclosure, settings or opt-in UI. Ordinary builds initialize no analytics identity or transport. Browser GPC/DNT signals keep collection off. The subsequent user-authorized hosted rollout enables this profile for invited testing; no disclosure or opt-in UI is added.

The hosted dashboard at /analytics is password-protected operator access. It supplies creator-style reports, but creator accounts, ownership authorization and external distribution are not implemented. Before offering reports externally, add app-scoped authorization, reviewed cohort suppression and protection against filter differencing. Never distribute the operator credential or raw all-app traces to creators.

Events are retained for 30 days by server receipt time; reads exclude expired rows and requests perform cleanup. This is lazy purge, not a claim of exact physical deletion at day 30. Scheduled purge, deletion procedures and platform backup retention must be decided for a persistent hosted service.

Delivery and operations

POST /api/analytics/events accepts exact same-origin JSON, max 20 events / 32 KiB, known release and strict fields. Exact retries keep IDs and payloads. Changed payload under an existing ID conflicts; inserts are atomic and acknowledged only after persistence. Source labels and actor fields remain client assertions, not attestation.

Authenticated same-origin QA may create a four-hour signed, Secure, HttpOnly, SameSite=Strict __Host-riff_test context at POST /api/analytics/test-context with bounded purpose (qa or exploration) and agent. Clearing the same endpoint removes it. The signed context classifies subsequent anonymous analytics; it is not a user identity or broader authorization. Its run ID and metadata stay in private evidence, never URLs. Staff manual QA can register as human QA, while agent exploration registers as agent activity.

The browser queue is memory-only, max 100 events / 24 hours, 10-second transport timeout, a maximum 10-second ordinary batch delay and five retries with backoff. Full batches and semantic terminal events send immediately without blocking play. Hidden/page-exit flushes can start extra tail batches within a shared two-request (at most 64 KiB) keepalive budget. Claimed IDs prevent concurrent duplicate sends. Permanent failures drop the batch. Navigations, crashes, blocking and full queues can lose events; an unload send is not proof of receipt. Analytics failures cannot block gameplay. A loopback-only QA hook exposes queue/drop state; central delivery-loss accounting is not implemented.

Every automated builder, agent and browser-test framework must use a dedicated browser context and put test_agent=1 on the first Feed, Lab, viewer or app navigation. scripts/test-agent-browser.mjs supplies the Playwright URL/context helper. The enabled bootstrap captures a valid declaration and removes only test_agent with history.replaceState, preserving history state, all other query text and the hash before app code can copy the current URL into a recipient link. The declaration initializes a sessionStorage marker for that top-level tab, expires after four hours and propagates through same-origin navigation and same-origin viewer descendants. A bounded in-memory page reader preserves descendant inheritance when sessionStorage is blocked, without extending the original expiry; later top-level navigation cannot inherit through blocked storage. test_agent=0 removes the marker for events created afterward; it does not rewrite queued, delivered or earlier same-session events. The SDK also accepts testAgent: true and emits an immutable integer context.test_agent snapshot on every new event. Older rifflet.observation/0.1 records without the optional field remain valid. A declared tag classifies as internal-test with reason declared-test-agent; a signed QA/builder context retains precedence. Neither mechanism grants access, authenticates an agent or proves identity.

Clean traffic views and daily trends

The dashboard sends includeLegacy=0, nickname=all, and testAgent=exclude by default alongside the visitor-candidate traffic selection. Include legacy traffic is unchecked on a fresh load. It restores unknown sessions with no modern observation context; it does not remove records from storage or erase historical goals. Modern unknown sessions remain available because insufficient human/automation evidence is not itself legacy traffic. The separate nickname selector means a valid nickname was, or was not, observed somewhere in the retained session. Missing nicknames are missing coverage, not proof of an agent.

All private reads (summary, per-app evidence, browser directory, and raw export) support the same strict query parameters: includeLegacy=0|1, nickname=all|observed|missing, testAgent=all|exclude|only. Existing API consumers that omit them retain the earlier inclusive behavior (1, all, all). The dashboard explicitly supplies its narrower defaults. Every filter uses whole-session evidence before actor/app narrowing. The explicit test selector includes context.test_agent=1, legacy actor=agent-test, and registered QA/exploration sessions; automation detection remains separately selectable through the traffic control. A later test declaration excludes earlier events in the same session too. Use a fresh context for a separate human review.

summary.trends.days contains chronological UTC buckets through the report end or current time, whichever is earlier. It reports observed browser profiles, sessions, meaningful starts, returning playing profiles, distinct apps tried, and active seconds. Today is partial. Empty selected buckets mean no retained matching observations, not proven absence of use. Browser and session counts across days cannot be summed into unique users. Active time is attributed to the attempt's start day, including valid later samples through the report end. These trends retain the existing bounded read and retention limits; they are not historical backfill or a verified-person measure.

Server requirements: existing RIFF_DB binding, separate 0002_private_analytics.sql, ANALYTICS_ENABLED=true, and server-only RIFF_RATE_KEY; private reads also need ANALYTICS_READ_TOKEN. Local/default limits are 10,000 retained events, 200 write batches and 120 reads per trusted-IP hour. The hosted invited-test profile explicitly sets ANALYTICS_CAPACITY=100000 and ANALYTICS_WRITE_RATE=2000 for shared networks. Authenticated reports show exact storage use and warn at 90%; retained rows are never silently sampled or evicted. Summary reads remain capped at 10,000 relevant rows; select an app and shorter date range if a report exceeds that bound. Rate buckets use rotating HMAC; raw IP is stored only in the separate event column. A full store rejects new batches rather than silently evicting them. Review measured volume before raising capacity; this pilot uses bounded in-memory aggregation, not a production warehouse.

The Pages/D1 adapter and migration are deployed only through the approved rollout; consult the current release receipt for remote verification. Platform references: [Pages bindings](https://developers.cloudflare.com/pages/functions/bindings/), [D1 prepared statements](https://developers.cloudflare.com/d1/worker-api/prepared-statements/), [Workers practices](https://developers.cloudflare.com/workers/best-practices/workers-best-practices/).

View hosted analytics privately

Open https://riff.marantz.net/analytics and enter the operator dashboard password. The public sign-in page is /analytics-login. The server gates the dashboard and its raw/aggregate/evidence reads; a client-side password check is not sufficient. A successful login sets a persistent 30-day host-only Secure, HttpOnly, SameSite=Strict cookie. Returning to the dashboard or sign-in page reuses that cookie, including after a browser restart. It expires 30 days after login, and signing out or clearing browser cookies ends remembered access. Only a hash of its random session token is stored in D1, and signing out revokes the server record. Password-verifier rotation invalidates existing sessions. Login attempts are limited to ten per trusted IP per fifteen-minute window before password verification. Sessions are bounded to 64 active records per verifier and 128 total; expired rows are purged during auth requests. A password rotation should deliberately clear the session table as part of the rollout, so prior-verifier records do not temporarily consume capacity. Verify or retire older deployment aliases when rotating credentials.

The operator password is held only in the ignored, mode-600 .analytics/dashboard-password file for the owner. Pages stores a salted PBKDF2-SHA256 verifier in the secret ANALYTICS_PASSWORD_HASH; neither the password nor that verifier is shipped in assets, logs or URLs. Session endpoints use exact same-origin JSON and bounded request bodies. Protected responses are non-cacheable. This is shared operator access to all apps and private raw samples, not creator-specific accounts.

The build bundles dashboard HTML from ignored .generated/analytics.html into the authenticated Pages Function and removes it from public dist. Keep this separation: static-router URL normalization must never expose a dashboard page through an unguarded alias. Build before compiling Functions.

The original loopback viewer remains available as an alternative. After the authorized deployment, run npm run analytics:live-dashboard and open http://127.0.0.1:4287/analytics.html. This loopback-only viewer reads the real hosted database through authenticated APIs. The read capability is stored in the ignored, mode-600 .analytics/operator-token file and the Pages secret ANALYTICS_READ_TOKEN; it never enters dashboard JavaScript, browser storage or URLs. The viewer accepts only same-origin GET requests and serves only the exact built dashboard assets. Direct unauthenticated hosted API reads return 401; authenticated browser reads use the HttpOnly session and never receive the operator bearer capability. Restart the viewer after rebuilding its assets.

Run and validate

cd '/Users/dmarantz/Projects/Advanced Content/rifflets-analytics'
npm run analytics:build
PORT=4286 npm run analytics:preview

Open http://127.0.0.1:4286/feed and http://127.0.0.1:4286/analytics.html. Loopback preview validates Host/Origin, stores SQLite under ignored .analytics/, and supplies read authorization inside the server; no browser bearer token. ANALYTICS_DB=:memory: makes tests disposable. Set RIFF_ANALYTICS_ACTOR=agent-test during automated QA builds. npm run build restores an analytics-off artifact.

Acceptance covers first action/true completion, reset/replay/stop, incoming completed state, direct/viewer navigation, hidden documents, keyboard/touch, denied storage, no analytics on normal builds, GPC/DNT, failed/duplicate/conflicting delivery, bounded fields, trusted IP and private reads. Shape validation cannot replace source/browser validation of meaning. Desktop viewport checks are not physical-phone tests.

Remaining extensions are comprehensive per-app browser terminal-path verification, creator-specific access, hosted retention operations and a public-audience policy if the audience changes. The current rollout uses the existing authorized Pages/D1 service; creator report distribution is not enabled.

Independent Claude audit follow-up — October 4

Exact-release measurement: the registry records each reviewed release's analytics contract. Final rates use finalEligibleStarts only; historical releases without a recorded 0.2 contract are unavailable, never a zero-success cohort. Known open-ended finals and undeclared milestone keys are excluded and counted as data-quality exceptions. Unmatched finish reports stay visible as data-quality evidence. A legacy completed goal remains a legacy goal. Preserve the analytics contract with each production source pin when updating release history; never assign a current contract retroactively to an unknown historical release.

Open-to-start conversion follows the first retained open in the selected UTC window, matched by source/browser/view across idle-session rotations. A tab opened before the window does not add a denominator or conversion to the later window. Session-based returns can happen after 30 idle minutes; they are not necessarily next-day returns. The browser directory's repeat-session count covers retained history, while its session count covers the selected window. The default dashboard range is 14 inclusive days; D7 requires at least eight inclusive days and an eligible cohort.

Delivery prioritizes journey boundaries over diagnostics in the bounded 100-event client queue. In-flight records remain claimed until acknowledgement/retry. When even the queue's journey events exceed its finite capacity, loss remains possible and is exposed by the client's dropped count; this is not durable offline storage. New clients send X-Riff-Analytics-Ack: partial-v1. Only negotiated collector acknowledgements may include rejected:[{eventId,code}] with invalid_time or diagnostic_capacity; accepted, duplicate and rejected IDs must partition the sent batch exactly. Legacy clients without that header retain strict whole-batch timestamp/capacity failures and the original accepted/duplicate response shape; rejected records are never falsely reported as accepted or duplicates. Invalid timestamps are isolated only after the entire batch's structural, release, privacy and ID validation succeeds. Arbitrarily wrong device clocks remain untrusted; the server does not silently rewrite event times. Malformed/private payloads and conflicting IDs still fail atomically.

The collector reserves the top 30 percent of its existing event capacity for journey events: impressions, opens, starts, milestones, finals, endings, explicit skips, sharing outcomes and nickname observations. Lower-priority diagnostic samples receive explicit diagnostic_capacity rejections once total occupancy including incoming journey events would exceed the 70 percent boundary. Exact retries do not consume capacity. This protects against diagnostic saturation, not forged semantic traffic or distributed abuse. No new paid service is required.

Read scope for raw events and the browser directory begins with profiles present in the requested date/app/actor window and includes their retained history and complete session traffic evidence. Summary/evidence reads seed the union of that report window and its rolling seven-day window, so players seen only earlier in the week still contribute to repeat usage. Unrelated prior-only profiles no longer fill a narrowed report. A genuinely busy selected profile can still exceed the hard 10,000-row report cap even though storage allows more; this returns read_scope_too_large and no partial totals. Date narrowing is not guaranteed to make an oversized profile readable. Future-only ranges return a validation error. Indexed rollups/pagination and stronger per-profile admission remain separately scoped scaling work.

Privacy wording: the existing authorized private observation includes the generated nickname identifier as well as its alias. That identifier may persist across analytics browser-ID rotations and therefore permits correlation; rotation is not an unlinkability promise. The directory continues to key on the analytics browser ID and does not automatically merge profiles or relink cleared storage. Altering nickname collection or retention is a separate policy decision. Public feedback and score consent remain separate. The UI calls weak visitor evidence “human-like signals,” not verified humanity; real-browser agents can have those signals. Signed QA enrollment remains session-scoped and expires; it does not permanently label every future use of a browser as testing.

Feed likes and shares — October 5, 2026

The Feed uses the same private first-party collector, browser/session identity, pinned app release, observation context, traffic filters and delivery queue as the existing analytics framework. Heart transitions emit like-changed with exactly {liked: boolean} and no gameplay attempt. Restoring a favorite from storage does not emit another like; previous favorites are not backfilled. Like/unlike events are journey-priority facts, not diagnostic clicks, so a control diagnostic cannot double-count them.

Opening the share panel emits share-attempt. A resolved clipboard write emits share-result {method: 'clipboard'}; a resolved native-share promise emits native; a browser copy command over the full displayed link emits manual. Native cancellation emits cancelled, and failed clipboard/native operations emit failed. Selecting text, showing a fallback link or opening the panel is not a successful copy or delivery. Native returns and manual copy commands do not verify receipt. A late asynchronous result stays attributed to the Rifflet/version whose link was shared, even after the viewer moves to another card. Share URLs, recipients and clipboard contents are never sent as event detail.

Private summaries, per-app/release reports, daily JSON trends and browser-profile/per-app details include likes, unlikes, likingBrowsers, shareAttempts, copiedLinks, nativeShareReturns, manualCopies, cancelledShares and failedShares. These are actions during the selected dates, not a current worldwide favorite count or verified unique people. Existing date/app/actor/traffic/test filters apply unchanged. Events are idempotent by event ID; distinct repeat actions remain distinct. Older Feed social actions were not recorded and cannot be reconstructed from click diagnostics. Analytics may be unavailable because of privacy settings, blocked storage/network or finite retention/capacity; the controls still work. Favorites remain local and are not publicly published by these metrics.

Rifflet rankings and report pivots — October 5, 2026

The private dashboard includes a By rifflet view, with numeric sorting by unique players, total play time, play time per player and repeat visits per player over seven days. Every selected registry app remains listed, including apps with no observed starts. Undefined averages display as unavailable. Counts are scoped estimates, never verified people or lifetime totals.

Report dates apply to the first three metrics. The repeat window is independent of the report From date and ends at the earlier of the report To day’s end (UTC) or server now. The response supplies exact UTC repeatWindow.from and repeatWindow.to, durationDays:7, and retentionLimited. A historical window overlapping the 30-day retention cutoff is explicitly limited; no full seven-day history is promised then. This measure is separate from exact-day D7 retention and from repeat attempts within a single visit.

Aggregate metric objects add linkedActiveSeconds, unlinkedActiveSeconds, activeSecondsPerPlayer, playingSessions, repeatPlayingSessions, repeatPlayingBrowsers and repeatSessionsPerPlayer. Each app adds rolling7d with the five playing/repeat session metrics. These are aggregate numbers only; no browser IDs, session IDs or nickname histories enter this ranking payload. Existing traffic, test-agent, legacy and nickname filters apply to complete session evidence before aggregation, including sibling-app evidence through the report end. Later evidence cannot change an earlier report.

Summary-card links navigate to useful breakdowns using the server-reported scope of the displayed report. A returned scope that differs from the request is disclosed; dependent directory reads and app pivots retain that reported scope. Unapplied form edits cannot silently change a linked view. Rifflet detail actions scope the report to that app before opening progress or browser details. Private ranking data follows the existing logout, authentication-failure and page-exit clearing rules. See the current release receipt for deployment status; this contract is not itself a rollout receipt.

Analytics before publication and approval

Before publishing a preview or approving any new app/version, follow [Analytics publish and approval checks](docs/analytics/PUBLISH_APPROVAL_CHECKS.md). Review App Stats and Platform Health in the simulator, verify the exact release/submission identity and a marked server receipt (test_agent=1), and check meaningful starts, intermediate milestones and final completion separately. Unknown or local-only telemetry is not verified hosted analytics. Uploaded foreground time and historical family aggregates cannot prove semantic coverage or a new revision's correctness. Record gaps explicitly; preserve existing ownership and approval boundaries.