429 lines
41 KiB
Markdown
429 lines
41 KiB
Markdown
|
# Website Analytics — flesh-out plan
|
|||
|
|
|
|||
|
|
**Goal:** rebuild `/{portSlug}/website-analytics` so it feels like a polished native CRM panel that _mirrors_ Umami's idiom rather than reading as a stripped-down embed. Keep a "View in Umami →" deep-link in the header for power users; render most data in-app via the API. Also extend usage into adjacent CRM surfaces (dashboard tiles, inquiry detail, email open-tracking) so Umami stops being "the analytics page" and becomes a cross-cutting data layer.
|
|||
|
|
|
|||
|
|
**Inputs to this plan:**
|
|||
|
|
|
|||
|
|
1. Live API capabilities reference — `docs/umami-api-capabilities.md` (verified empirically against v3.1.0 on analytics.portnimara.com).
|
|||
|
|
2. Live UI tour via Playwright — screenshots `umami-tour-1-overview.png` through `umami-tour-9-compare.png` (10 surfaces captured).
|
|||
|
|
3. Pixel-tracking probe — confirmed the `/p/<slug>` and `/q/<slug>` endpoints + their UI creation forms.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1. What Umami's UI actually does — design patterns to mirror
|
|||
|
|
|
|||
|
|
Tour findings (from 17 sub-pages + 4 team pages):
|
|||
|
|
|
|||
|
|
| Surface | Visual idiom | Adopt for CRM? |
|
|||
|
|
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
|
|||
|
|
| **Overview** | 5-tile KPI row (Visitors / Visits / Views / Bounce rate / Visit duration) — each tile shows headline number + colored arrow chip (green ↑ 58% / red ↓ 39%) + percentage delta. Single stacked bar chart below for traffic time-series (visitors stacked over visits, dual-shade blue). Filter pill + date-range nav top-right. | **Yes** — already mostly there, missing the bounce-rate + visit-duration tiles. |
|
|||
|
|
| **Events** | List of custom event names with per-event count + time-series spark. | **Yes** — needs marketing-site event firing first (Phase 4). |
|
|||
|
|
| **Sessions** | Dense table: avatar + per-session row showing Visits / Views / Events / Location (flag + city, country) / Browser icon / OS icon / Device icon / Last seen. Tabs for Activity vs Properties (custom session props). | **Yes** — high-leverage; lets reps see _who_ is browsing right now. |
|
|||
|
|
| **Realtime** | 4 stat tiles (Views/Visitors/Events/Countries) + auto-refreshing line chart of last 30 min. | **Yes** — already partial via the glance tile. |
|
|||
|
|
| **Performance** | Likely page-speed / Core Web Vitals. | Skip — not relevant to marina sales. |
|
|||
|
|
| **Compare** | Pick two date ranges side-by-side. | **Partial** — single `compare=prev` overlay on the existing trend chart suffices. |
|
|||
|
|
| **Breakdown** | Pivot table view across dimensions. | Skip in v1; expose via Reports later. |
|
|||
|
|
| **Goals** | Define event/page-view goals, see completion rate over time. | **Yes** — defer to Phase 5. |
|
|||
|
|
| **Funnels** | Multi-step conversion funnel (e.g. /berths → /berths/A12 → /inquire → submit). | **Yes** — Phase 5; high-value for inquiry conversion. |
|
|||
|
|
| **Journeys** | Most common navigation paths (Sankey-like). | **Maybe** — defer; nice-to-have. |
|
|||
|
|
| **Retention** | Cohort retention grid. | Skip — wrong fit for one-and-done marina inquiry traffic. |
|
|||
|
|
| **Replays** | Session replay (likely paid). | Skip — unavailable on our tier. |
|
|||
|
|
| **Segments / Cohorts** | Saved filters / user groups. | Skip in v1. |
|
|||
|
|
| **UTM** | Campaign attribution by UTM params. | **Yes** — Phase 5 for paid-campaign tracking. |
|
|||
|
|
| **Revenue** | Revenue attribution. | Skip — would require firing `purchase` events from CRM after EOI close (consider Phase 6 if leadership wants funnel→revenue). |
|
|||
|
|
| **Attribution** | First/last-click attribution model. | **Maybe** — defer. |
|
|||
|
|
| **Team-Boards / Websites / Links / Pixels** | Account admin surfaces. | **Pixels + Links: YES — see Phase 4.** Boards/Websites stay in Umami. |
|
|||
|
|
|
|||
|
|
### Visual specifics worth copying
|
|||
|
|
|
|||
|
|
- **KPI tile design**: large bold number, label above in muted-grey, arrow + percentage delta below in a colored chip (green-bg for positive, red-bg for negative, fixed-width for alignment). Our `KPITile` already does the right shape — we just need to add the missing two metrics.
|
|||
|
|
- **Stacked bar chart for traffic**: dual-shade single bar (visitors as light-blue base, views stacked dark-blue on top). Reads cleaner than two overlapping lines.
|
|||
|
|
- **Location rendering**: flag emoji + "City, Country" inline. Use `getCountryName()` + a flag library (twemoji or unicode regional indicators).
|
|||
|
|
- **Browser/OS/Device icons**: small colored brand glyphs inline. Use `simple-icons` or `lucide` equivalents.
|
|||
|
|
- **Filter chip + date nav**: `<` `>` arrows step through the date range; dropdown opens to preset list. Adopt the same pattern on our shell — currently we only have presets, no step-arrows.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2. Phased build plan
|
|||
|
|
|
|||
|
|
### Phase 1 — Fill out the Overview tiles & chart (~3-4h)
|
|||
|
|
|
|||
|
|
Quick wins that close visual parity with Umami's Overview:
|
|||
|
|
|
|||
|
|
| Task | File | Effort |
|
|||
|
|
| -------------------------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
|
|||
|
|
| Add **Bounce rate** KPI tile | `website-analytics-shell.tsx` | derive `bounces / visits * 100`; service field already there |
|
|||
|
|
| Add **Avg visit duration** KPI tile | `website-analytics-shell.tsx` | derive `totaltime / visits` formatted as `Xm Ys`; service field already there |
|
|||
|
|
| Add **`<` `>` date-step arrows** on the date-range chip | `date-range-picker.tsx` | step the current preset by one window (today→yesterday, 7d→prior-7d, etc.) |
|
|||
|
|
| Convert pageviews trend to **stacked bar** (visitors vs views) | `pageviews-chart.tsx` | recharts `BarChart` stacked, light/dark blue |
|
|||
|
|
| Add **`compare=prev` overlay toggle** on the trend chart | `pageviews-chart.tsx` + service `getPageviewsSeries` | optional "vs prior period" series rendered as dashed line |
|
|||
|
|
| Add **Top browsers / OS / devices** ranked-list cards | new `<TopList>` consumers; service already exposes via `getMetric(type)` | mirror Top Pages/Referrers/Countries layout |
|
|||
|
|
| **World choropleth heatmap** card (already queued separately) | new `visitor-world-map.tsx` (Natural Earth topojson + react-simple-maps) | ~4-6h on its own |
|
|||
|
|
|
|||
|
|
**Cumulative result:** Overview surface reads at ~80% parity with Umami's Overview.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### Phase 2 — Sessions surface (~4-5h)
|
|||
|
|
|
|||
|
|
New `/website-analytics/sessions` tab + supporting service wrappers:
|
|||
|
|
|
|||
|
|
| Task | File | Effort |
|
|||
|
|
| ------------------------------------------------------------------------------------------------------------------------ | ------------------ | ------- |
|
|||
|
|
| Service: `getSessions(portId, range, opts)` → `/api/websites/:id/sessions` (paged) | `umami.service.ts` | ~30 min |
|
|||
|
|
| Service: `getSession(portId, sessionId)` → single-session detail | `umami.service.ts` | ~15 min |
|
|||
|
|
| Service: `getSessionActivity(portId, sessionId, range)` → event timeline | `umami.service.ts` | ~15 min |
|
|||
|
|
| Service: `getSessionsWeekly(portId, range)` → hour-of-week heatmap | `umami.service.ts` | ~15 min |
|
|||
|
|
| API route: `/api/v1/website-analytics?metric=sessions[&sessionId=...]` | route.ts | ~30 min |
|
|||
|
|
| UI: `sessions-table.tsx` — dense rows mirroring Umami (avatar + location flag + browser/OS/device icons + Last seen) | new component | ~2h |
|
|||
|
|
| UI: `session-detail-sheet.tsx` — right-side Sheet drawer showing the session's full event timeline when a row is clicked | new component | ~1h |
|
|||
|
|
| UI: `weekly-heatmap-card.tsx` — 7×24 grid colour-scaled by session count, hover for tooltip | new component | ~1h |
|
|||
|
|
|
|||
|
|
**Unlock:** rep can see "who is currently browsing right now, where from, on what device, what they're looking at" — directly actionable for sales follow-up.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### Phase 3 — Events surface (~3-4h, BLOCKED on Phase 4a)
|
|||
|
|
|
|||
|
|
| Task | File | Effort |
|
|||
|
|
| -------------------------------------------------------------------------------------------- | ------------------ | ------- |
|
|||
|
|
| Service: `getEvents(portId, range, opts)` → `/events` paged list | `umami.service.ts` | ~30 min |
|
|||
|
|
| Service: `getEventsStats(portId, range)` → totals | `umami.service.ts` | ~15 min |
|
|||
|
|
| Service: `getEventsSeries(portId, range, eventName, unit)` → per-event time-series | `umami.service.ts` | ~15 min |
|
|||
|
|
| API route addition | route.ts | ~30 min |
|
|||
|
|
| UI: `events-tab.tsx` — list of event names with per-event count + spark + drill-in | new component | ~1.5h |
|
|||
|
|
| UI: `event-detail-sheet.tsx` — single event's time-series chart + filter by payload property | new component | ~1h |
|
|||
|
|
|
|||
|
|
**Dependency:** the marketing site must fire `umami.track(name, payload)` calls (Phase 4a). Without this, Events tab is empty.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### Phase 4 — Pixel tracking + link tracking + marketing-site event push
|
|||
|
|
|
|||
|
|
**Phase 4a — Marketing-site event tracking (~2-3h on marketing repo)**
|
|||
|
|
|
|||
|
|
Add `umami.track()` calls in the marketing site:
|
|||
|
|
|
|||
|
|
- `inquiry-submitted` with `{berth, source}` payload — fires on EOI form submit
|
|||
|
|
- `brochure-download` with `{brochureId}` — fires on brochure download
|
|||
|
|
- `berth-detail-viewed` with `{berthId, mooring}` — fires on `/berths/[mooring]` page view
|
|||
|
|
- `phone-revealed` / `email-revealed` — fires when contact details are exposed
|
|||
|
|
|
|||
|
|
These light up the Events tab + enable funnel analysis in Phase 5.
|
|||
|
|
|
|||
|
|
**Phase 4b — Pixel-based email open tracking (~3-4h CRM-side)**
|
|||
|
|
|
|||
|
|
Probe finding: Umami exposes pixel URLs at `https://analytics.portnimara.com/p/<slug>` — fetching the URL records an event. Use case: embed in HTML emails as a 1x1 image.
|
|||
|
|
|
|||
|
|
**Two architecture options:**
|
|||
|
|
|
|||
|
|
**Option A — One Umami pixel per email type** (simple, low fidelity)
|
|||
|
|
|
|||
|
|
- Create a pixel manually in Umami for each templated email type (`portal-invite`, `eoi-sent`, `reservation-reminder`, etc.)
|
|||
|
|
- Embed the static pixel URL in each template
|
|||
|
|
- Pro: zero CRM-side code beyond template HTML. Open rates roll up in Umami by pixel.
|
|||
|
|
- Con: can't tell _which recipient_ opened — only aggregate counts per template.
|
|||
|
|
|
|||
|
|
**Option B — One Umami pixel + CRM-side per-send tracking endpoint** (richer, recommended)
|
|||
|
|
|
|||
|
|
- Build `GET /api/public/email-pixel/:sendId.gif` in our CRM that:
|
|||
|
|
1. Returns a 1×1 transparent GIF
|
|||
|
|
2. Records the open in `document_sends.opened_at` (already a table; per CLAUDE.md "send-from accounts" section)
|
|||
|
|
3. Optionally proxies the hit to Umami via `POST /api/send` with the email type + send id as event properties for cross-correlation
|
|||
|
|
- Embed `<img src="https://crm.portnimara.com/api/public/email-pixel/{sendId}.gif" width="1" height="1" />` in every templated email
|
|||
|
|
- Pro: per-recipient open tracking + open-time + CRM-attached. Funnels by email type via Umami too.
|
|||
|
|
- Con: needs the public endpoint + a schema column (or reuse `document_sends.opened_at`).
|
|||
|
|
|
|||
|
|
**Recommendation: ship Option B.** The CRM-side hook gives us per-deal attribution ("client X opened the EOI reminder twice but hasn't signed"), and Umami still gets the aggregate.
|
|||
|
|
|
|||
|
|
| Task | File | Effort |
|
|||
|
|
| ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ------- |
|
|||
|
|
| New endpoint `/api/public/email-pixel/[sendId]/route.ts` returning a 1×1 GIF + recording open | new route | ~1h |
|
|||
|
|
| Migration: add `opened_at`, `open_count`, `last_opened_user_agent` to `document_sends` if not present | drizzle migration | ~30 min |
|
|||
|
|
| Email template helper: inject the pixel HTML into every transactional template | `src/lib/email/render.ts` | ~30 min |
|
|||
|
|
| UI surface: on each `document_sends` row in the activity feed, show "Opened N times, last at X" badge | `email-activity-row.tsx` | ~1h |
|
|||
|
|
| Cross-post to Umami via `trackEvent('email-opened', {emailType, sendId})` so Umami funnel data includes opens | new `trackEvent` wrapper in `umami.service.ts` | ~30 min |
|
|||
|
|
| Privacy: respect `EMAIL_REDIRECT_TO` dev gate; don't fire pixels for redirected dev emails | ditto | ~15 min |
|
|||
|
|
|
|||
|
|
**Phase 4c — Tracked redirect links (~1.5h)**
|
|||
|
|
|
|||
|
|
Umami's `/q/<slug>` endpoint is a tracked redirect — records a click then 302s to the destination URL. Use for outbound CTAs:
|
|||
|
|
|
|||
|
|
- "View brochure" links in emails → wrap via Umami link → records click → opens brochure
|
|||
|
|
- "Schedule a viewing" buttons → wrap via Umami link → click attribution
|
|||
|
|
- Marketing-site CTAs → wrap → measure engagement
|
|||
|
|
|
|||
|
|
| Task | File | Effort |
|
|||
|
|
| ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ------- |
|
|||
|
|
| Service: `createTrackedLink(name, destinationUrl)` → POST to Umami's links endpoint via authenticated API | `umami.service.ts` | ~45 min |
|
|||
|
|
| Email template helper: `<trackedLink href="..." name="...">` JSX wrapper that auto-creates the Umami link on first render + caches the slug | `src/lib/email/components/` | ~45 min |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### Phase 5 — Reports surfaces (Funnels, UTM, Journeys) (~6-8h)
|
|||
|
|
|
|||
|
|
| Task | File | Effort |
|
|||
|
|
| ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------ |
|
|||
|
|
| Service: `getReport(reportType, body)` POST wrapper covering `/funnel`, `/journey`, `/utm`, `/goals`, `/retention`, `/revenue`, `/attribution` | `umami.service.ts` | ~1h |
|
|||
|
|
| UI: `/website-analytics/funnels` page — admin-configurable funnel definitions (steps as event names or URL paths), per-step drop-off chart | new page | ~3h |
|
|||
|
|
| UI: `/website-analytics/utm` page — UTM source/medium/campaign breakdown with click-through to attributed sessions | new page | ~2h |
|
|||
|
|
| UI: `/website-analytics/journeys` page — top navigation paths rendered as ranked list (skip Sankey for v1) | new page | ~1.5h |
|
|||
|
|
| Defer: Goals / Retention / Revenue / Attribution to v2 (low signal for marina sales) | | |
|
|||
|
|
|
|||
|
|
**High-leverage funnels to wire as defaults:**
|
|||
|
|
|
|||
|
|
- **Inquiry funnel**: `/` → `/berths` → `/berths/[mooring]` → `inquiry-submitted` event → CRM `eoi-signed` (cross-system!) → CRM `reservation-paid` (cross-system!)
|
|||
|
|
- **Email funnel**: `email-sent` → `email-opened` (pixel) → tracked-link click → CRM action
|
|||
|
|
|
|||
|
|
The cross-system funnels require Phase 4 to be live first.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### Phase 6 — CRM → Umami event push for outcome attribution (~2-3h)
|
|||
|
|
|
|||
|
|
Close the funnel from "marketing site click" → "CRM closed deal" by firing CRM-side events back into Umami via `POST /api/send`:
|
|||
|
|
|
|||
|
|
| Event | Fired by | Payload |
|
|||
|
|
| ---------------------- | -------------------------------------------- | --------------------------------------- |
|
|||
|
|
| `crm-inquiry-created` | `createInterest()` in `interests.service.ts` | `{interestId, source, leadCategory}` |
|
|||
|
|
| `crm-eoi-sent` | `generateAndSign()` after EOI dispatch | `{interestId, berth, pathway}` |
|
|||
|
|
| `crm-eoi-signed` | Documenso `DOCUMENT_COMPLETED` webhook | `{interestId, berth}` |
|
|||
|
|
| `crm-reservation-paid` | manual stage advance to `deposit_paid` | `{interestId, berth, amount, currency}` |
|
|||
|
|
| `crm-contract-signed` | manual stage advance to `contract` | `{interestId, berth, amount, currency}` |
|
|||
|
|
|
|||
|
|
| Task | File | Effort |
|
|||
|
|
| ----------------------------------------------------------------------------------------- | ------------------- | -------- |
|
|||
|
|
| Service: `trackEvent(name, payload, sessionId?)` → `POST /api/send` on the Umami instance | `umami.service.ts` | ~45 min |
|
|||
|
|
| Hook into the 5 service entry points above (one event per outcome milestone) | each service file | ~1.5h |
|
|||
|
|
| Audit log entry per event sent so we can verify Umami received it | `audit_logs` insert | included |
|
|||
|
|
|
|||
|
|
**Unlock:** Umami's Revenue + Attribution reports start showing CRM outcomes attributed to marketing-site channels — closes the leadership question "which traffic sources actually generate signed deals, not just leads?"
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### Phase 7 — Cross-cutting CRM placements (~3-4h)
|
|||
|
|
|
|||
|
|
Beyond the dedicated `/website-analytics` page, surface Umami data inside CRM context:
|
|||
|
|
|
|||
|
|
| Placement | What | Effort |
|
|||
|
|
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ------------------------------------ |
|
|||
|
|
| **Dashboard rail tile** (already shipped) — Pageviews + active now | already done in this session | — |
|
|||
|
|
| **Inquiry detail page** — "Source attribution" card showing the inquiry's UTM params, landing page, time-on-site, pages-viewed-before-submit. Pulls from `getSession(sessionId)` if the inquiry's create payload includes a session ID (requires marketing-site change to pass it). | new `inquiry-attribution-card.tsx` | ~1.5h + marketing-site change |
|
|||
|
|
| **Client detail page** — "Website activity" card: total sessions, pageviews, last-seen, top pages visited. Requires `umami.identify({email})` on marketing site to link sessions back to clients. | new `client-web-activity-card.tsx` | ~1.5h + marketing-site identify call |
|
|||
|
|
| **Berth detail page** — "Marketing demand" card: pageviews to `/berths/{mooring}` over time + referrer breakdown. Drives "this berth is being viewed but not inquired-about — flag for outreach." | new `berth-demand-card.tsx` | ~1h |
|
|||
|
|
| **Document send activity** — pixel opens per recipient (from Phase 4b) | inline on existing `document_sends` rows | included in 4b |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2b. Library adoptions (changes the plan materially)
|
|||
|
|
|
|||
|
|
Context7 lookup surfaced three official libraries that reshape the plan. **Adopt all three.**
|
|||
|
|
|
|||
|
|
### `@umami/api-client` — official read-side client
|
|||
|
|
|
|||
|
|
Covers every read endpoint we need including all the report types. Built-in filter support, login/JWT auth handled internally, `{ok, data}` discriminated union for clean error handling.
|
|||
|
|
|
|||
|
|
**Replaces:** ~60-70% of our current `umami.service.ts` (drop `umamiFetch`, JWT cache, decrypt boilerplate; keep thin wrappers with existing signatures so consumers don't change).
|
|||
|
|
|
|||
|
|
**One-time refactor (~2h):**
|
|||
|
|
|
|||
|
|
```ts
|
|||
|
|
const clientByPort = new Map<string, UmamiApiClient>();
|
|||
|
|
|
|||
|
|
async function getClient(portId: string): Promise<UmamiApiClient | null> {
|
|||
|
|
if (clientByPort.has(portId)) return clientByPort.get(portId)!;
|
|||
|
|
const cfg = await loadUmamiConfig(portId);
|
|||
|
|
if (!cfg) return null;
|
|||
|
|
const client = new UmamiApiClient({
|
|||
|
|
apiEndpoint: `${cfg.apiUrl}/api`,
|
|||
|
|
apiKey: cfg.apiToken ?? undefined,
|
|||
|
|
});
|
|||
|
|
if (!cfg.apiToken && cfg.username && cfg.password) await client.login(cfg.username, cfg.password);
|
|||
|
|
clientByPort.set(portId, client);
|
|||
|
|
return client;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
export async function getStats(portId: string, range: DateRange) {
|
|||
|
|
const client = await getClient(portId);
|
|||
|
|
if (!client) return null;
|
|||
|
|
const { from, to } = rangeToBounds(range);
|
|||
|
|
const result = await client.getWebsiteStats(WEBSITE_ID, {
|
|||
|
|
startAt: from.getTime(),
|
|||
|
|
endAt: to.getTime(),
|
|||
|
|
});
|
|||
|
|
return result.ok ? result.data : null;
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Same pattern for `getPageviewsSeries`, `getMetric`, `getActiveVisitors`, plus new ones from the SDK: `getRealtime`, `getWebsiteSessionStats`, `runFunnelReport`, `runJourneyReport`, etc.
|
|||
|
|
|
|||
|
|
### `@umami/node` — official write-side SDK
|
|||
|
|
|
|||
|
|
For Phase 6 (CRM → Umami push) and Phase 4b cross-post:
|
|||
|
|
|
|||
|
|
```ts
|
|||
|
|
const umami = new Umami({ websiteId, hostUrl });
|
|||
|
|
await umami.track({
|
|||
|
|
url: '/crm/eoi-signed',
|
|||
|
|
name: 'crm-eoi-signed',
|
|||
|
|
data: { interestId, berth, dealValue },
|
|||
|
|
});
|
|||
|
|
await umami.identify({ sessionId, email, interestId });
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**Replaces:** the planned hand-rolled `trackEvent()` wrapper. Single line per outcome milestone.
|
|||
|
|
|
|||
|
|
### `react-simple-maps` — for the world heatmap (Phase 1b)
|
|||
|
|
|
|||
|
|
Declarative SVG choropleth on d3-geo + topojson-client. SSR-safe. Use `topojson/world-atlas` (110m resolution ~30KB) cached in `public/`. Bundle ~30-50KB + topojson 30-100KB.
|
|||
|
|
|
|||
|
|
```jsx
|
|||
|
|
<ComposableMap projection="geoMercator">
|
|||
|
|
<Geographies geography="/world-110m.json">
|
|||
|
|
{({ geographies }) =>
|
|||
|
|
geographies.map((geo) => (
|
|||
|
|
<Geography
|
|||
|
|
key={geo.rsmKey}
|
|||
|
|
geography={geo}
|
|||
|
|
fill={scaleByVisitorCount(visitorsByCountry[geo.properties.iso_a2] ?? 0)}
|
|||
|
|
onClick={() => onCountryClick(geo.properties.iso_a2)}
|
|||
|
|
/>
|
|||
|
|
))
|
|||
|
|
}
|
|||
|
|
</Geographies>
|
|||
|
|
</ComposableMap>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**Chose this over visx/Nivo/Chart.js Geo:** visx is overkill for one map; Nivo + Chart.js force a different charting idiom (we use recharts everywhere); react-simple-maps' compose-primitives shape matches our recharts pattern.
|
|||
|
|
|
|||
|
|
### Net effect on phase efforts
|
|||
|
|
|
|||
|
|
| Phase | Original estimate | Revised after library adoption |
|
|||
|
|
| ---------------------------------------- | ----------------- | --------------------------------------------------------------- |
|
|||
|
|
| Service refactor (one-time) | — | **+2h** (one-time foundation; pays back across all phases) |
|
|||
|
|
| Phase 1 — Overview parity | 3-4h | 3-4h (unchanged; api-client makes the filter additions trivial) |
|
|||
|
|
| Phase 1b — World heatmap | 4-6h | 3-4h (library choice locked in) |
|
|||
|
|
| Phase 2 — Sessions | 4-5h | 3-4h (api-client has session methods built-in) |
|
|||
|
|
| Phase 3 — Events | 3-4h | 2-3h (api-client provides) |
|
|||
|
|
| Phase 4b — Pixel hybrid | 3-4h | 2.5-3h (cross-post is one line) |
|
|||
|
|
| Phase 5 — Reports (funnels/UTM/journeys) | 6-8h | 3-4h (every report method pre-wrapped) |
|
|||
|
|
| Phase 6 — CRM → Umami push | 2-3h | 1.5h (`@umami/node` handles transport) |
|
|||
|
|
|
|||
|
|
**Total scope drops from ~30-40h to ~22-28h** with these adoptions.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 3. Service-layer additions consolidated
|
|||
|
|
|
|||
|
|
Add to `src/lib/services/umami.service.ts` (each is a thin wrapper around existing `umamiFetch` / new `umamiPost`):
|
|||
|
|
|
|||
|
|
```ts
|
|||
|
|
// Sessions (Phase 2)
|
|||
|
|
getSessions(portId, range, { page?, pageSize?, query? }) → /sessions
|
|||
|
|
getSession(portId, sessionId) → /sessions/:id
|
|||
|
|
getSessionActivity(portId, sessionId, range) → /sessions/:id/activity
|
|||
|
|
getSessionProperties(portId, sessionId) → /sessions/:id/properties
|
|||
|
|
getSessionsWeekly(portId, range, timezone) → /sessions/weekly
|
|||
|
|
|
|||
|
|
// Events (Phase 3)
|
|||
|
|
getEvents(portId, range, opts) → /events
|
|||
|
|
getEventsStats(portId, range) → /events/stats
|
|||
|
|
getEventsSeries(portId, range, eventName, unit) → /events/series
|
|||
|
|
getEventDataProperties(portId, range) → /event-data/properties
|
|||
|
|
|
|||
|
|
// Realtime (Phase 1)
|
|||
|
|
getRealtime(portId, range) → /api/realtime/:id (richer than /active)
|
|||
|
|
|
|||
|
|
// Reports (Phase 5)
|
|||
|
|
getReport(portId, reportType, body) → POST /api/reports/:type (funnel/journey/utm/goals/retention/revenue/attribution)
|
|||
|
|
|
|||
|
|
// CRM → Umami (Phase 6)
|
|||
|
|
trackEvent(portId, name, payload, sessionId?) → POST /api/send
|
|||
|
|
|
|||
|
|
// Links + Pixels admin (Phase 4)
|
|||
|
|
createTrackedLink(portId, name, destinationUrl) → POST team-level /links
|
|||
|
|
createTrackingPixel(portId, name) → POST team-level /pixels
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Plus a new `umamiPost(config, path, body)` helper alongside the existing `umamiFetch` since GET-only doesn't cover reports + send.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 4. Pixel-tracking answer (the user's specific question)
|
|||
|
|
|
|||
|
|
**Q: Can we use Umami's pixel tracking for email opens?**
|
|||
|
|
|
|||
|
|
**A: Yes — and recommended in hybrid form.** Direct verification on the live instance:
|
|||
|
|
|
|||
|
|
- Pixel UI at `/teams/[teamId]/pixels` lets an admin create named pixels. Each gets an auto-generated slug.
|
|||
|
|
- The pixel URL is `https://analytics.portnimara.com/p/<slug>` — fetching it records an event (no auth required from the email client side; the slug is the credential).
|
|||
|
|
- Embedded as `<img src="..." width="1" height="1" />` in HTML emails, it fires when the email is rendered (Outlook/Apple Mail/etc.).
|
|||
|
|
- Standard caveats: Apple Mail privacy protection pre-fetches images server-side → opens may be over-counted for iOS users. Some recipients block images entirely → opens under-counted. Same caveats as every email tracking pixel ever.
|
|||
|
|
|
|||
|
|
**Recommended hybrid (Phase 4b above):** build a CRM-side pixel endpoint `/api/public/email-pixel/[sendId].gif` that:
|
|||
|
|
|
|||
|
|
- Returns the 1×1 GIF
|
|||
|
|
- Records `opened_at` in `document_sends`
|
|||
|
|
- Cross-posts the hit to Umami via `POST /api/send` so the Umami Events tab + funnels include opens
|
|||
|
|
|
|||
|
|
This way: per-recipient attribution in the CRM, aggregate roll-ups in Umami, single source of truth for both.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 5. Effort summary + prioritization
|
|||
|
|
|
|||
|
|
| Phase | Scope | Effort | Priority |
|
|||
|
|
| ----- | ------------------------------------------------------------------------------------ | ---------------------- | ------------------------------------------------------------ |
|
|||
|
|
| 1 | Overview parity (KPI tiles, stacked-bar chart, date arrows, browser/OS/device cards) | ~3-4h | **High** — most visible polish, no dependencies |
|
|||
|
|
| 1b | World choropleth heatmap (already queued separately) | ~4-6h | **High** if leadership wants the visual |
|
|||
|
|
| 2 | Sessions surface (table + detail sheet + weekly heatmap) | ~4-5h | **High** — biggest "wow" + actionable |
|
|||
|
|
| 3 | Events surface | ~3-4h | **Medium** — blocked on 4a |
|
|||
|
|
| 4a | Marketing-site event tracking | ~2-3h (marketing repo) | **High** — unblocks 3 + 5 |
|
|||
|
|
| 4b | Pixel-based email open tracking (hybrid) | ~3-4h | **High** — direct ask + immediate value |
|
|||
|
|
| 4c | Tracked redirect links | ~1.5h | **Medium** |
|
|||
|
|
| 5 | Reports (Funnels, UTM, Journeys) | ~6-8h | **Medium** — depends on 4a being live |
|
|||
|
|
| 6 | CRM → Umami event push for outcome attribution | ~2-3h | **Medium-high** — needed to close marketing→outcome loop |
|
|||
|
|
| 7 | Cross-cutting placements (inquiry / client / berth detail cards) | ~3-4h | **Medium** — depends on `umami.identify()` on marketing site |
|
|||
|
|
|
|||
|
|
**Recommended build order (updated 2026-05-19 per user):**
|
|||
|
|
|
|||
|
|
1. ✅ **Service refactor** — Kept hand-rolled `umamiFetch` (the official `@umami/api-client` transitively pulls `next-basics` which requires React at module-import time, breaking SSR + tsx scripts). Adopted `@umami/node` for the write side.
|
|||
|
|
2. ✅ **Phase 1** — Overview parity (KPI tiles + browser/OS/device cards + date arrows + stacked-bar chart + `compare=prev` overlay)
|
|||
|
|
3. ✅ **Phase 1b** — World heatmap. **Switched from `react-simple-maps` to ECharts + `public/world-map/echarts-world.json`** — the `world-atlas/110m` topojson has antimeridian-crossing polygons (Russia/Fiji/Antarctica) that render a horizontal line through the equator regardless of projection. ECharts' world.json is pre-cleaned.
|
|||
|
|
4. ✅ **Phase 4b** — Pixel-based email open tracking. `document_send_opens` table + `/api/public/email-pixel/[sendId]` endpoint + `injectTrackingPixel` helper wired into `performSend`. Per-port kill switch `email_open_tracking_enabled` (admin UI on `/admin/website-analytics`). Cross-posts to Umami as `email-opened`.
|
|||
|
|
5. ✅ **Phase 2** — Sessions surface. `SessionsList` (paginated, click-through to detail), `SessionDetailSheet` (full activity stream), `WeeklyHeatmap` (7×24 grid). API endpoints `sessions`, `session`, `session-activity`, `sessions-weekly`.
|
|||
|
|
6. ✅ **Phase 6** — CRM → Umami event push. `trackEvent` calls wired into `createInterest` (`interest-created`), `updateInterestStage` (`interest-stage-changed`), `setInterestOutcome` (`interest-outcome-set`).
|
|||
|
|
7. ✅ **Phase 7** — Cross-cutting placements. `email-sent` (in `performSend`), `eoi-signed` (in `handleDocumentCompleted`). Remaining placements (inquiry / berth detail attribution cards) defer until UI surfaces them.
|
|||
|
|
8. ✅ **Phase 4c** — Tracked redirect links. `tracked_links` + `tracked_link_clicks` tables + `/q/[slug]` redirect endpoint + `createTrackedLink` / `buildTrackedUrl` service helpers. Email-composer integration deferred to UI follow-up.
|
|||
|
|
9. **Phase 3 + Phase 5 — DEFERRED to the end.** Events tab is empty until marketing-site `umami.track()` calls land (Phase 4a, deferred). Funnels save for the end per user direction — pageview-only marketing funnel is the v1; richer event-based funnels come later.
|
|||
|
|
10. **Phase 4a + cross-system funnels** — when there's appetite for marketing-site repo changes, unlock Events tab + cross-system funnels.
|
|||
|
|
|
|||
|
|
**Total scope: ~22-28h** with library adoptions, of which ~13-15h is the high-priority Phases 1 + 1b + 4b + 2 + 6 that ship first.
|
|||
|
|
|
|||
|
|
Total scope: ~30-40h end-to-end for the full flesh-out.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 6. What stays in Umami vs. mirrored in CRM
|
|||
|
|
|
|||
|
|
| In CRM (mirror) | In Umami only (deep-link) |
|
|||
|
|
| ----------------------------------------------------------- | ----------------------------------------------------------------- |
|
|||
|
|
| Overview / KPI tiles / trend chart | Replays (paid) |
|
|||
|
|
| Sessions list + detail | Retention (low signal) |
|
|||
|
|
| Top pages / referrers / countries / browsers / OS / devices | Saved Boards (admin power-user) |
|
|||
|
|
| Events + per-event drill | Pixels/Links admin CRUD (use Umami for setup; render data in CRM) |
|
|||
|
|
| Funnels + UTM + Journeys | Performance / Web Vitals |
|
|||
|
|
| World heatmap | Cohorts / Segments (defer until use case emerges) |
|
|||
|
|
| Email open tracking | Multi-website CRUD |
|
|||
|
|
|
|||
|
|
Every page header in the CRM analytics surface gets a small "View in Umami →" outbound link in the corner for power users who want the full feature surface.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7. Open questions for the user before implementation
|
|||
|
|
|
|||
|
|
1. **Marketing site repo access**: Phase 4a (umami.track calls), Phase 4 (umami.identify for client linkage), and Phase 7 (passing sessionId to inquiry intake) all require changes there. Confirm whoever owns the marketing site is in the loop.
|
|||
|
|
2. **Pixel hybrid vs Umami-only**: do you want per-recipient open tracking (hybrid) or just aggregate (Umami-only)? Recommended hybrid above; switch to Umami-only if the engineering cost isn't worth it.
|
|||
|
|
3. **Funnel definitions**: who defines the canonical funnels? Suggest admins set them up via a CRM-side admin page that POSTs to Umami's `/api/reports/funnel`, with the most important funnels (inquiry, email-conversion) seeded as defaults at install time.
|
|||
|
|
4. **Privacy / GDPR**: email pixel tracking + `umami.identify({email})` linkage both touch PII. Confirm consent model — likely already handled by the marketing-site cookie banner, but the email pixel needs explicit opt-out handling (e.g. don't fire pixel if the recipient is in a do-not-track list).
|