Skip to content

About

Personal website (experimental)

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

50 Commits

Folders and files

Repository files navigation

Portfolio Traffic Tracker

This repository hosts Matthew Zhou's portfolio and its traffic tracker. GitHub Pages serves the portfolio and browser scripts. The Cloudflare Worker overseer receives tracking events, stores them in D1, and serves the analytics dashboard. An optional Resend integration emails a daily summary.

What the tracker records

Feature Data collected
Sessions and page views Random browser session ID, first and latest page-view times, total views, page paths, and entry referrer when available. A new session starts after 30 minutes without another tracked page load. The stored page history has a 100-entry limit, and the view count continues to increase.
Network and device Public IP, network organization, IP-derived country, region, city, postal code, estimated coordinates and time zone, raw user-agent, and desktop, mobile, or tablet classification.
Engagement Time with each page visible and focused, plus the deepest scroll percentage. Focused time can include time when a visitor leaves the tab open and steps away.
Scroll behavior Distance, bursts, direction reversals, timing and speed variation, pauses, wheel/touch/keyboard counts, scrolls linked to recent input, sampled pointer-move and click counts, and a compact trajectory of up to 24 points.
Tracked links Résumé PDF, email, and GitHub clicks. The Worker stores the source page, link target, click count, and first and latest click times.
Replay Timestamps, approximate viewport dimensions, document height, site release ID, scroll positions, mouse or pen movement, in-site navigation, tracked clicks, and lightbox actions. A lightbox opening includes the image path and caption.

A home connection generally shows the ISP as the network organization. A campus or corporate connection may show the organization operating that network. VPNs can show their exit network and location. The session ID identifies a browser session, and IP-based location is approximate.

Dashboard and session reports

Open the Portfolio Analytics dashboard. The history covers all stored sessions, with 50 per page, ordered by the most recent recorded page view.

  • Search matches IP, session ID, page path, referrer, location, network organization, device type, and user-agent.
  • Filters combine a date range, location, network organization, and device. The date range includes both endpoints and uses the session's start date in Eastern Time. Clear resets the filters and Refresh reruns the applied search.
  • View report → Summary shows the session overview, pages viewed, per-page focused time and scroll behavior, scroll-over-time graphs, tracked click counts, and entry referrer. The chart can use the compact scroll trajectory when detailed replay samples are unavailable.
  • View report → Replay lets you select a page view, play or pause, scrub the timeline, and change playback speed. The viewer reconstructs scrolling and lightbox actions over the published page. A cursor dot and a short trail follow mouse or pen movement. Navigation and tracked clicks appear in the event list.

The browser samples scroll and cursor movement at a nominal 25 ms interval while moving, up to 2,400 samples of each type and 5,200 events per page view. Replay chunks are sent on the 15-second timer, after selected actions, or when the chunk reaches 250 events. The site release ID helps identify the originally visited version because the viewer loads the currently published page. The tracker excludes screenshots, typed text, and form contents.

Legacy visit records remain searchable. Old replays can show their original scroll and action data. Cursor playback requires data from the updated browser script. The daily Worker schedule removes detailed replay data after approximately 60 days. Session summaries, engagement metrics, and compact scroll profiles remain available.

Deploy an update

1. Check the D1 database

  1. In the Cloudflare dashboard, open Workers & Pages → overseer → Bindings and identify the D1 database bound as DB.

  2. Open that database's Console under D1 SQL Database and run the following query.

    PRAGMA table_info(visits);
  3. If ip_organization is missing, run migration-ip-organization.sql once. Search, filters, and cursor replay use existing tables.

For an older installation, apply missing migrations in the order below. The migrations assume the original visits table exists. Run each migration only once.

Migration Schema change
Session grouping Adds session ID, page-view timestamps, view count, and page history to visits.
Engagement metrics Adds device type and the session_page_metrics and session_actions tables.
Scroll behavior Adds session_page_scroll_profiles for per-page scroll statistics.
Session replay Adds session_replay_pages and the original session_replay_events table.
Replay chunks Adds session_replay_chunks for newer replay uploads. The Worker also reads legacy replay event rows.
Network organization Adds the network organization column to visits.

2. Deploy the Worker

  1. Open Workers & Pages → overseer → Edit code.
  2. Replace the deployed script with the full contents of worker/index.js, then select Deploy.
  3. Open the dashboard and confirm the history filters and page controls appear.

The Worker accepts tracking POST requests from the portfolio origin configured in ALLOWED_ORIGIN. It serves the dashboard at /admin and its data at /admin-data.

3. Publish the browser scripts

Publish js/analytics.js and js/lightbox.js through the GitHub Pages publishing branch after deploying the Worker. Update SITE_VERSION in the tracker when a release changes what visitors see, so replay reports can identify the recorded version.

Add this script before the closing body tag on additional pages you want to track. Portfolio galleries use the lightbox script to record and replay image opens and closes.

<script src="/js/analytics.js"></script>

4. Verify the live tracker

  1. Open the published portfolio in a fresh private desktop window. Scroll, move the mouse, and wait about 15 seconds. Visit a project in the same window, open a gallery image, or click a tracked link.
  2. Refresh the dashboard and look for a single session containing the page views. Open View report → Replay and check that scrolling and the cursor follow the scrubber. If you opened an image, verify that the right image appears.
  3. Filter for an older date range or search for a known historical visit to confirm the archive is accessible. Older rows can show Unknown for network organization.

Daily email and replay cleanup

At 11:59 p.m. Eastern Time, the scheduled Worker deletes expired replay data. When Resend is configured, it also emails a summary of sessions that started that Eastern calendar day. The report includes sessions, page views, average focused time, average deepest scroll depth, popular pages, tracked clicks, device types, and visitor locations.

  1. Create a sending API key in Resend. The Worker's test sender, onboarding@resend.dev, sends to the email address associated with the Resend account.

  2. In Workers & Pages → overseer → Settings → Variables and Secrets, add RESEND_API_KEY and REPORT_TO as secrets. Use the Resend account email for REPORT_TO.

  3. Under Triggers → Cron Triggers, add both UTC schedules. The Worker checks Eastern Time so email and cleanup run once per day across daylight-saving changes. Leave the triggers configured if you use replay cleanup without email.

    59 3 * * *
    59 4 * * *
    

Access and troubleshooting

The Worker has no built-in login for /admin or /admin-data. Verify external access protection for both routes because they expose visit history, IP-derived data, and replays. The tracking POST endpoint needs to stay reachable by site visitors.

Symptom Check
Dashboard fails or shows a missing table or column Confirm the DB binding points to the migrated database. Use the migration table above to identify the missing schema.
Fresh replays lack cursor samples Verify that Cloudflare and GitHub Pages both serve the updated code. Retry with mouse movement in a private desktop window and allow time for the upload.
Network organization is Unknown Cloudflare may lack organization metadata, or the row may predate its collection. A new page view can fill the field for an existing session if it comes from the stored IP and supplies the metadata.
Daily email is missing Check both Worker secrets, both cron triggers, and the Resend logs. Verify the recipient matches the Resend account email.
A Worker deployment needs to be reverted Roll back to the previous version in overseer → Deployments. The added D1 column can stay in place.

About

Personal website (experimental)

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages