Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(docs): add page-view + referrer + search tracking via Viewer-Counter (#2982)

t0saki1352096b0cb1
diff --git a/.github/workflows/_docs-deploy.yml b/.github/workflows/_docs-deploy.yml
index 144d82fa7..2eaf6337b 100644
--- a/.github/workflows/_docs-deploy.yml
+++ b/.github/workflows/_docs-deploy.yml
@@ -34,6 +34,7 @@ jobs:
working-directory: docs
env:
DOCS_BASE: /
+ VITE_COUNTER_URL: ${{ vars.VITE_COUNTER_URL }}
- name: Configure GitHub Pages
uses: actions/configure-pages@v6
diff --git a/.github/workflows/docs-tos.yml b/.github/workflows/docs-tos.yml
index 2d66e098c..d2f49259d 100644
--- a/.github/workflows/docs-tos.yml
+++ b/.github/workflows/docs-tos.yml
@@ -36,6 +36,8 @@ jobs:
- name: Build docs
run: npm run docs:build
working-directory: docs
+ env:
+ VITE_COUNTER_URL: ${{ vars.VITE_COUNTER_URL }}
- name: Check TOS configuration
id: tos_config
diff --git a/docs/.vitepress/theme/OpenVikingSearch.vue b/docs/.vitepress/theme/OpenVikingSearch.vue
index 5f2262c67..992920616 100644
--- a/docs/.vitepress/theme/OpenVikingSearch.vue
+++ b/docs/.vitepress/theme/OpenVikingSearch.vue
@@ -4,6 +4,7 @@ import { useData, withBase } from 'vitepress'
import { searchCopyForLocale } from './openviking-search-i18n'
import { localizeSearchResultTitles } from './openviking-search-results'
+import { trackEvent } from './track'
import type { RemoteSearchFailureReason } from './openviking-search-i18n'
import type {
DocsIndexRecord,
@@ -202,6 +203,8 @@ async function runSearch() {
return
}
+ trackEvent('docs-search')
+
isLoading.value = true
const controller = new AbortController()
activeSearchController = controller
diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
index 4499da9bb..f64625294 100644
--- a/docs/.vitepress/theme/index.ts
+++ b/docs/.vitepress/theme/index.ts
@@ -1,8 +1,10 @@
import { h } from 'vue'
import DefaultTheme from 'vitepress/theme'
+import type { EnhanceAppContext } from 'vitepress'
import CopyMarkdownButton from './CopyMarkdownButton.vue'
import LlmsTxtLink from './LlmsTxtLink.vue'
import OpenVikingSearch from './OpenVikingSearch.vue'
+import { trackPageView } from './track'
import './custom.css'
type OpenVikingPreference = {
@@ -304,5 +306,16 @@ export default {
'doc-footer-before': () => h(LlmsTxtLink),
'nav-bar-content-before': () => h(OpenVikingSearch)
})
+ },
+ enhanceApp({ router }: EnhanceAppContext) {
+ if (import.meta.env.SSR || typeof window === 'undefined') return
+
+ trackPageView(window.location.pathname)
+
+ const previousHook = router.onAfterRouteChanged
+ router.onAfterRouteChanged = (to: string) => {
+ previousHook?.(to)
+ trackPageView(to.split('?')[0].split('#')[0])
+ }
}
}
diff --git a/docs/.vitepress/theme/track.ts b/docs/.vitepress/theme/track.ts
new file mode 100644
index 000000000..c261c1d97
--- /dev/null
+++ b/docs/.vitepress/theme/track.ts
@@ -0,0 +1,88 @@
+/**
+ * Minimal usage beacons to a Viewer-Counter instance
+ * (https://github.com/t0saki/Viewer-Counter).
+ *
+ * Disabled unless VITE_COUNTER_URL is set at build time, so default/local/PR
+ * builds carry no tracking. Page views are reported with the route pathname;
+ * the search action
+ * is reported as an event pseudo-page under /e/ (the counter is configured to
+ * skip visitor dedup for that prefix, so events keep raw counts while page
+ * views stay deduplicated).
+ *
+ * The `site` dimension is derived from the current hostname so the docs served
+ * on openviking.ai and openviking.net are counted separately.
+ *
+ * Beacons are fire-and-forget: failures are swallowed and never surface to the
+ * page.
+ */
+
+const COUNTER_URL = (
+ (import.meta.env.VITE_COUNTER_URL as string | undefined) ?? ''
+).replace(/\/+$/, '')
+
+export type TrackEventName = 'docs-search'
+
+function resolveSite(): string {
+ if (typeof window === 'undefined') return 'docs'
+ const host = window.location.hostname
+ if (host === 'openviking.ai' || host.endsWith('.openviking.ai')) return 'docs-ai'
+ if (host === 'openviking.net' || host.endsWith('.openviking.net')) return 'docs-net'
+ return 'docs'
+}
+
+function beacon(page: string, ref?: string): void {
+ if (!COUNTER_URL) return
+ const params = new URLSearchParams({ page, site: resolveSite() })
+ if (ref) params.set('ref', ref)
+ const url = `${COUNTER_URL}/api/v1/hit?${params.toString()}`
+ try {
+ // Prefer sendBeacon; fall through to the Image() beacon whenever it is
+ // unavailable, throws, or reports the payload was not queued.
+ if (typeof navigator !== 'undefined' && typeof navigator.sendBeacon === 'function') {
+ if (navigator.sendBeacon(url)) return
+ }
+ } catch {
+ // fall through to the Image() fallback below
+ }
+ try {
+ new Image().src = url
+ } catch {
+ // Tracking must never break the page.
+ }
+}
+
+/** Reduce the referrer to origin + pathname so query strings never leave the page. */
+function normalizeReferrer(raw: string): string | undefined {
+ if (!raw) return undefined
+ try {
+ const url = new URL(raw)
+ return `${url.origin}${url.pathname}`
+ } catch {
+ return undefined
+ }
+}
+
+let lastPath: string | null = null
+let referrerSent = false
+
+/**
+ * Report a page view. Consecutive duplicates (e.g. search-param-only
+ * navigations resolving to the same pathname) are collapsed. The first call
+ * attaches document.referrer as the traffic source — the beacon's own Referer
+ * header would only echo the docs URL.
+ */
+export function trackPageView(pathname: string): void {
+ if (pathname === lastPath) return
+ lastPath = pathname
+ let ref: string | undefined
+ if (!referrerSent) {
+ referrerSent = true
+ ref = normalizeReferrer(document.referrer)
+ }
+ beacon(pathname, ref)
+}
+
+/** Report a user action as an /e/ pseudo-page. */
+export function trackEvent(name: TrackEventName): void {
+ beacon(`/e/${name}`)
+}