docs
/
AI skills

Website traffic and visitor activity

How the site records each visit, and what it leaves out. Read a site's traffic (visitors, pages, campaigns, countries, devices) and say what each figure really counts; see who is on the site now and what one visitor or one customer looked at; erase a person's visits when asked. Explains why traffic reads zero and which panels mislead. It only reads, except a chat invite or an erase, and each of those waits for a yes.

Every Appmint-hosted site records its own visits. There is no tag to add and no switch to turn on. Each visit is a row in the business's web_visit collection, and the Analytic Center's Website Analytics, the Live View and each customer's activity timeline are all read from those rows.

Reading reports in general (any dashboard, the period before, building charts of your own) is Dashboards and reports. Google Analytics and the Meta Pixel are separate tags with their own reports: Google Analytics and the Facebook Pixel. This page covers what Appmint's own visit tracking records, and how to read it right.

Ask first

  • Which site? Traffic is reported one site at a time. List them with call_appengine GET /analytics/sites. The answer names each site, its domains, and which one is the default.
  • Which period? Without dates you get the last 30 days. Say which dates you used.
  • One visitor, or everyone? For one person, you need their email (a customer who signed in) or the visitor's device id (from the Live View).
  • Anything that reaches the visitor (a chat invite), or erasing someone's visits: wait for a yes (steps 4 and 5).

How a visit is recorded

The site's own tracker runs on every page, in every visitor's browser (base-app components/ActivityTracker.tsx, lib/activity-tracker.ts):

WhenWhat is sentRow
A page opens, and on every in-site route changethe full URL, page title, referrer, browser, OS, device type, screen, language, time zone, the device id, the campaign (utm_*), the signed-in customer's email if anya page view (no type), source: "base-app"
The visitor leaves the pagethe same, plus time on the page (duration, ms) and how far they scrolled (scrollDepth, %)type: "unload", source: "chat-client"

They go to POST /tools/web-visit-indirect, and the site's server adds the visitor's IP address. The engine then fills in country and city from the IP, the site's name from the domain, and the campaign fields utmSource, utmMedium, utmCampaign… from the URL (tools/tools.service.ts, tools/web-visit-normalize.ts).

  • The device id is made on the first visit and kept in the browser (chatDeviceId, in local storage and a two-year cookie). It is the same id the chat widget uses. It is how one visitor's pages are tied together.
  • A customer's email is added when they are signed in, and to later visits from a device once its owner is known.

Not recorded (tested on a local engine, tools/web-visit-filter.ts):

Left outWhy
Crawlers, uptime checks, scripts and headless browsersa bot-like user agent: Googlebot, curl, HeadlessChrome, Lighthouse, Pingdom…
Visits from a private network address (10.…, 192.168.…, 127.…)treated as the platform's own traffic
A site opened on localhost or a .local addressa developer's machine
Files and probe paths (.js, .png, wp-admin…)not pages
More than 60 hits a minute from one IP addressa flood
The same page load reported twice, by the tracker and the chat widgetcounted once

The tracker doesn't wait for cookie consent. It runs for every visitor, and sets the chatDeviceId cookie on the first page, consent banner or not. A cookie banner on the site doesn't stop it. See Site cookies and consent and Site notice.

Steps

1. Analytic Center: the site's traffic

call_appengine GET /analytics/website with query: { "siteName": "<site>", "startDate": "2026-09-01", "endDate": "2026-09-30" }. A date-only endDate includes that whole day (UTC).

On screen: Analytic Center (/analytics) › Website Analytics, with the site and the dates in the header.

The answer (appengine analytics/analytics.service.ts 480–1240). The screen shows the first group; the API has them all:

On screenFieldWhat it counts
Visitorsoverview.totalVisitorsdistinct devices (else email, else IP)
Page Viewsoverview.pageViewspage-view rows
Sessionsoverview.sessionsone per device in the period. A visitor who comes back next week is still one session (below)
Bounce Rateoverview.bounceRatesessions with a single page view
Avg Sessionoverview.avgSessionDuration (seconds)time on page from leave rows, each capped at 30 minutes
Conversion Rateoverview.conversionRatesessions with a form_submit, purchase, checkout_complete or signup event. null ("Not tracked") when none was recorded
Daily Visitorstrafficdistinct visitors per day
On the Site NowrealTimeUsersdistinct visitors in the last 5 minutes, but see the cache warning
Top PagestopPagesviews per full URL
Countries, DevicesgeographicData, deviceBreakdownshare of sessions
Traffic SourcestrafficSourcesnot where visitors came from (warning below)
—topReferrers, entryPages, exitPagesthe referring URL, the first page and the last page
—utmAttribution.bySource, .byMedium, .byCampaignsessions by campaign tag. Use this for "did the campaign bring people".
—newVsReturning, topCities, browserBreakdown, osBreakdown, languageBreakdown, hourHeatmap, dayOfWeekBreakdown, scrollDepthBuckets, formAnalytics, topSearchesas named
—period, comparisonthe dates used, and each overview figure against the same length of time just before

Read it in plain words, with the dates: "1,240 visitors and 3,900 page views, 1–30 September, up 8% on August. Most came from your newsletter (utm_source=newsletter)."

"Traffic Sources" names the tracker, not the channel. It groups rows by their source field, which the site's tracker sets to base-app on page views and chat-client on leave rows (base-app lib/activity-tracker.ts 177, 207). So the panel reads Base App and Chat Client, each near 100%, and adds up to more than 100% (tested; appengine analytics/analytics.service.ts 694–699). Never report it as search, social or direct traffic. For where visitors came from, use utmAttribution and topReferrers.

Figures can be 5 minutes old. Each part of the report is cached for 5 minutes (analytics/analytics-query.ts). On the Site Now is cached too, so it can read 0 while someone is on the site (tested). For "who is here now", use the Live View (step 2), which is cached for 15 seconds.

More things to say plainly when you report:

  • Top Pages splits one page by its address. /shop?utm_source=email and /shop are two rows. Add them up for "how did the shop page do".
  • Time on page reads 0 for every page. The leave rows carry the time, but the page list averages the page-view rows, which never do (analytics.service.ts 611–612). The session average (avgSessionDuration) is right.
  • A session is a device, not a visit. Sessions are grouped by device id with no timeout, so sessions is close to totalVisitors, and avgPagesPerSession is pages per visitor over the period.
  • No traffic at all is answered as an empty report (the screen says No website traffic yet). Check, in order: is the site published and opened by real people on its real domain (not localhost, not from the office network on a private address)? Is the right site picked? Is the period right? Do the site's domains in GET /analytics/sites include the one people use?
  • Staff count as visitors when they browse the live site from an ordinary connection.

Hands on: the figures and the dates. Check: the person sees the same numbers on Website Analytics for the same site and dates. Allow for the 5-minute cache.

2. Customer Activity: who is on the site now

call_appengine GET /analytics/live-view with query: { "minutes": 15 } (default 15). It answers { visitors, minutes, count }: one row per visitor seen in that window, across all the business's sites. Each row merges that visitor's rows: their device id, site, country and city, IP address, current page, entry page, device, page count, time on site, scroll depth, and isActive (seen in the last minute). Visitors connected to the chat widget are added as active.

On screen: CRM › Customer Activity (/customer-activity), the Visitors and Map tabs. They refresh every 15 seconds. (Analytic Center's Live View tab is the same view.)

Hands on: a visitor's device id, and their email if they are known. Check: the person sees them on the Visitors tab.

3. One visitor's journey, one customer's history

  • One device: GET /analytics/live-view/<deviceId>/journey (limit, default 100). It answers timeline.events (every row, newest first) and summary: first and last seen, page views, devices, countries, active time. On screen: the visitor's Journey action on the Visitors tab.
  • One customer, by email: GET /crm/customer-activity/<email>/timeline (types, from, to, limit, page) and GET /crm/customer-activity/<email>/summary (first and last seen, top pages, devices, locations, an engagement score). On screen: the visitor's Insights action, for known visitors only.

Browsing from before they signed in isn't on their email timeline. A customer's timeline holds only rows that carry their email. Tested: three pages viewed anonymously, then one while signed in, on the same device. The email timeline showed one page; the device journey showed all four. For "what did they look at before buying", read the device journey too.

Say what you saw in plain words: "She came from your September newsletter on the 12th, read the sizing guide twice and bought two days later."

Hands on: nothing.

4. Live chat: say hello to a visitor (only if asked)

The Visitors tab's Engage action sends the visitor a chat invite: a message in the site's chat widget with a Reply button. Staff send it. Through the API it is POST /chat/engage with { "deviceId": "<id>", "kind": "chat-invite", "message": "…" }.

Stop: this reaches a real person on the site. Show the message and who it goes to, and wait for yes. It needs the chat widget on the site: see Live chat on the site.

5. Erase a person's visits (only if asked)

For a privacy request: call_appengine POST /crm/customer-activity/erase with { "email": "<their email>" }. It answers { "deleted": <rows> }.

Stop: it can't be undone, and the rows don't go to Trash. Say what will go and wait for yes.

  • It deletes only rows that carry that email (tested). Their anonymous visits stay, under their device id. To remove those too, find them with repo_find on web_visit with { "data.deviceId": "<id>" } and delete each one with repo_delete. That is also a Stop.
  • Their customer record, orders and messages are not touched. Those are separate requests.

Check: their timeline answers no events, and, if you removed them, the device journey too.

When it's done

Tell the person:

  • the figures, for which site and which dates, with the change on the period before;
  • where visitors came from, from campaigns and referrers, never from "Traffic Sources";
  • anything that can make a figure misleading (an address split in Top Pages, the 5-minute cache, the office network not counted);
  • for one person, what they did, from the device journey as well as the email timeline.

Point them to Analytic Center › Website Analytics and Customer Activity.

What it can't do yet

  • No real traffic channels. "Traffic Sources" groups by which tracker sent the row (step 1 warning). There is no search, social or direct breakdown. Campaign tags (utm_*) on your own links are the way to tell.
  • No consent gating. Visits are recorded and the device cookie set before any consent (above).
  • Per-page time is always 0 (step 1).
  • Sessions never end. A session is a device over the whole period.
  • Figures lag up to 5 minutes, "On the Site Now" included.
  • Visits from private addresses and dev machines are dropped, so a site tried from the office network can show nothing.
  • Anonymous browsing isn't joined to the customer's email timeline once they sign in (step 3).

Don'ts

  • Don't report "Traffic Sources" as where visitors came from.
  • Don't say "nobody is on the site" from On the Site Now. Use the Live View.
  • Don't add up rows from different addresses as different pages without saying so.
  • Don't send a chat invite or erase anything without a yes.
  • Don't tell a business its tracking waits for consent. It doesn't.
  • Don't compare these numbers one-for-one with Google Analytics. They count differently (bots, sessions, consent).