Velt View Analytics Best Practices

Velt View Analytics Best Practices

Implementation guide for the Velt View Analytics feature — a "who viewed this document today" indicator with a trigger badge, a recent-viewers dialog (desktop) and bottom sheet (mobile), and observable / hook APIs for aggregating views by user or by date.

When to Apply

Reference these guidelines when:

• Placing <VeltViewAnalytics> (or <velt-view-analytics>) in your toolbar
• Scoping to a sub-document with type="location" + location-id
• Reading unique-view counts from React (useUniqueViewsByUser, useUniqueViewsByDate hooks) or non-React (client.getViewsElement().get*().subscribe(...)) code
• Building a fully custom trigger badge / viewer list using the wireframe tags (<velt-view-analytics-wireframe>, <velt-view-analytics-dialog-wireframe>, <velt-view-analytics-bottom-sheet-wireframe>)
• Reading componentConfig.* template variables (todayViewsCount, totalUniqueViewsCount, treadsVisible, userViews, bottomSheetMode, etc.)

For general SDK setup, see velt-setup-best-practices for VeltProvider, auth, and document identity.

Naming gotcha — getViewsElement (plural)

The element handle is client.getViewsElement() (plural) — not getViewElement (singular). Calling getViewElement() is a common hallucination from base models; it does not exist. The plural form is consistent with the hook/observable names (getUniqueViewsByUser, getUniqueViewsByDate).

treadsVisible (intentional spelling)

The wireframe-variable name for "dialog is open" is componentConfig.treadsVisible — spelled treads (not threads). This is an SDK-side legacy spelling; using threadsVisible returns undefined silently. Bind dialog open/close styling on treadsVisible.

Rule Categories by Priority

Quick Reference

API (HIGH)

• api-setup — <VeltViewAnalytics> placement; type="location" + location-id props for location-scoped trigger
• api-views-subscriptions — React hooks (useViewsElement for the handle; useUniqueViewsByUser / useUniqueViewsByDate for data) and non-React observable form (client.getViewsElement().get*().subscribe); canonical return types (Observable<ViewsByUser[]> / Observable<ViewsByDate[]>); optional locationId filter; subscription cleanup

Wireframe Variables (MEDIUM)

• wireframe-variables-view-analytics — three wireframe tags (trigger / dialog / bottom-sheet); full componentConfig.* reference for each scope; treadsVisible spelling; flat-config access pattern (always use componentConfig.<path>)

How to Use

Read individual rule files for detailed explanations and code examples:

rules/shared/api/api-setup.md
rules/shared/api/api-views-subscriptions.md
rules/shared/wireframe-variables/wireframe-variables-view-analytics.md

Each rule contains:

• Why it matters
• React / Next.js + Other Frameworks code samples
• Common pitfalls
• Verification checklist
• Source pointers to official docs

Compiled Documents

• AGENTS.md — Compressed index of all rules with file paths (start here)
• AGENTS.full.md — Full verbose guide with all rules expanded inline