Migrating to UrlHistory v2: What Changed and How to Upgrade

How to implement UrlHistory tracking in your app

Goals

• Record page visits (URL, title, timestamp, user/session id).
• Keep storage bounded and performant.
• Respect privacy (store minimal PII, provide deletion/expiry).

Data model (example)

• id (string)
• url (string)
• title (string)
• visitedAt (ISO 8601 timestamp)
• sessionId (string, optional)
• referrer (string, optional)
• metadata (JSON, optional)

Where to store

• Client-only single-user apps: localStorage or IndexedDB (IndexedDB preferred for large/history).
• Multi-user server-backed apps: server database (Postgres/Mongo). Use server-side deduplication and retention rules.
• Hybrid: buffer in IndexedDB and batch-upload to server when online.

Capture points

1. Single-page apps (SPA): listen to router events (e.g., history.pushState, popstate, framework router hooks).
2. Multi-page apps: instrument link clicks and page load events (DOMContentLoaded / load).
3. Programmatic navigation: wrap navigation functions to emit history events.

Implementation outline (client-side, SPA)

1. Hook router navigation events.
2. Build record {url, title, visitedAt, sessionId, referrer}.
3. Save to IndexedDB (append) and enforce max entries (e.g., 10k) by deleting oldest.
4. Optional: batch-send to server every N records or on idle/network online.
5. Provide APIs: getRecent(n), search(query), delete(id), clearOlderThan(date).

Server-side considerations

• Authenticate uploads; associate with user id only if necessary.
• Rate-limit and validate URLs to prevent abuse.
• Schema: table with indexed visitedAt, url, userId.
• Retention policy: auto-delete older than X days or keep summary-only.
• Use deduplication (collapse identical URL visits within short window).

Privacy and security

• Store minimal personal data; hash or omit identifiers when possible.
• Encrypt sensitive fields in transit and at rest.
• Provide UI to view and delete history; honor “Do Not Track” preference.
• Implement retention and automatic expiry.

Performance tips

• Use IndexedDB for large volumes.
• Batch writes and uploads; use requestIdleCallback or background sync.
• Index common query fields (url, visitedAt).
• Compress or summarize old entries (daily aggregates).

Example libraries & APIs to use

• IndexedDB wrappers: Dexie.js.
• Background sync: Service Worker Background Sync / navigator.sendBeacon for unload.
• Server: Postgres for relational querying, or Elasticsearch for text search.

Minimal sample flow (pseudocode)

• onNavigation(newUrl):
  • record = {url:newUrl, title:document.title, visitedAt:now()}
  • saveIndexedDB(record)
  • if buffer.length >= 50 or idle: uploadBatch()

Recommended defaults

• Max local entries: 10,000
• Server retention: 90 days (adjust per legal/privacy needs)
• Batch upload size: 50–200 records

If you want, I can: provide a small code example for your framework (React/Angular/Vue) or a server schema for Postgres.