Skip to content

Organizer analytics: views, referrers and conversion per campaign #252

Closed

Description

@JOY

Why

JOY (2026-11-19) asked for parity with GoFundMe and Kickstarter. Organizers cannot see how their campaign performs. docs/Give-Technical-Design.md §0.1 keeps organizer analytics from the old design; nothing exists today.

Scope

  • Count campaign page views without storing personal data: no IP, no user id; a daily per-campaign counter plus referrer host (direct, facebook.com, zalo, google, other) and share-button clicks. Bots filtered by user agent. Writes through a SECURITY DEFINER RPC or a route handler with the service role, rate limited.
  • An "Thống kê" tab on /me/campaigns/[id]: views per day, top referrers, number of contributions and amount per day (from the ledger, never stored counters), conversion (contributions / views), share clicks.
  • DB changes in DOS/DOS.Me migrations with RLS (only the organizer and admins read) and pgTAP.

Out of scope

Third-party trackers, per-donor tracking, exports.

Done when

On beta: opening a campaign page raises its view count once per day per browser at most; the organizer sees the tab, another user cannot read it; tests pass.

Activity

  1. JOY commented on Nov 18, 2026

    @JOY
    ContributorAuthor

    Campaigns PO (line:campaigns): filed the DOS/DOS.Me database prerequisite as #263 (line:platform -> Give Product Owner). Ready to build the apps/web tracking route & /me/campaigns/[id] "Thống kê" tab as soon as #263 lands on DOS.Me dev.

  2. JOY commented on Nov 21, 2026

    @JOY
    ContributorAuthor

    DB prerequisite #263 has merged into DOS/DOS.Me dev via https://github.com/DOS/DOS.Me/pull/1852 (merge commit db6ccf74fa34c409822d045b8176f9469695d9f1, migration 20261129120000_give_campaign_analytics.sql).

    RPC Contract

    1. Write RPC (service_role only)

    give.record_campaign_event(
      p_campaign_id uuid,
      p_event       text,               -- 'view' | 'share_click' (case-insensitive, trimmed)
      p_referrer    text DEFAULT NULL   -- raw URL, bare host[:port], Android app referrer, or bucket label
    )
    RETURNS TABLE (
      metric_date     date,             -- Vietnam date (Asia/Ho_Chi_Minh)
      event_type      text,             -- 'view' | 'share_click'
      referrer_bucket text,             -- 'direct' | 'facebook.com' | 'zalo' | 'google' | 'other' (for view); 'none' (for share_click)
      event_count     bigint
    )
    • Call via dbService().rpc('record_campaign_event', { p_campaign_id, p_event, p_referrer }) from a rate-limited, bot-filtered Next.js route handler.
    • Accepts public campaigns only (give.is_public_status: live, settling, succeeded, failed, closed).
    • Zero PII stored (give.campaign_daily_analytics stores only aggregate daily counters).
    • Note: pass p_referrer: null (or 'direct') for same-origin navigation (give.vn / beta.give.vn); unknown external hosts map to 'other'.

    2. Read RPC (authenticated only)

    give.get_campaign_analytics(
      p_campaign_id uuid,
      p_days        integer DEFAULT 30  -- 1..365 (NULL defaults to 30)
    )
    RETURNS jsonb
    • Call via dbAs(session.accessToken).rpc('get_campaign_analytics', { p_campaign_id, p_days }).
    • Restricted strictly to the campaign organizer (organizer_id = auth.uid()) and give staff (give.is_admin(): moderator, finance, admin).
    • Money series is computed strictly from give.ledger_entries (never stored money counters):
      • give campaigns: unreversed received + unmatched_in posts bucketed by bank booked_at date (Asia/Ho_Chi_Minh), excluding other_in; cross-day split transfers for a single donation count once in contributions_count on its earliest booked date in the window while keeping each transfer's amount on its own booked_at day.
      • back campaigns: net-positive pledged contributions bucketed by initial positive pledge date (Asia/Ho_Chi_Minh), excluding cancelled/lapsed pledges.

    Returned jsonb Payload Shape

    {
      "campaign_id": "uuid",
      "campaign_type": "give | back",
      "days": 30,
      "start_date": "YYYY-MM-DD",
      "end_date": "YYYY-MM-DD",
      "totals": {
        "views": 0,
        "share_clicks": 0,
        "contributions_count": 0,
        "contributions_amount": 0,
        "conversion_rate": 0
      },
      "daily": [
        {
          "date": "YYYY-MM-DD",
          "views": 0,
          "share_clicks": 0,
          "contributions_count": 0,
          "contributions_amount": 0
        }
      ],
      "referrers": [
        {
          "bucket": "direct | facebook.com | zalo | google | other",
          "views": 0
        }
      ]
    }
    • daily: chronological (date ASC), zero-filled for every Vietnam date from start_date to end_date inclusive (length = days).
    • referrers: view buckets with views > 0 sorted by views DESC, bucket ASC (empty array [] when no views; never includes 'none' from share_click).
    • totals.conversion_rate: round(contributions_count / views, 6) when views > 0, else 0.

    Error Codes

    Code SQLSTATE When
    GIVE_ANALYTICS_EVENT_INVALID 23514 (check_violation) record_campaign_event: p_event is NULL or not 'view'/'share_click'
    GIVE_ANALYTICS_DAYS_INVALID 23514 (check_violation) get_campaign_analytics: p_days < 1 or p_days > 365
    GIVE_CAMPAIGN_NOT_FOUND P0002 (no_data_found) Campaign missing, non-public (on write), or caller is neither organizer nor give staff (on read; no existence leak)
    GIVE_SIGN_IN_REQUIRED 42501 (insufficient_privilege) get_campaign_analytics: auth.uid() is NULL
  3. added
    po:agyOwned by Antigravity PO (mutual-exclusion parallel PO label)
    on Nov 21, 2026
  4. JOY commented on Nov 21, 2026

    @JOY
    ContributorAuthor

    claim: executor=Antigravity session=b3d8a837-d38f-4fd9-a5bc-a376463a6212 scope="apps/web campaign analytics tracking route + /me/campaigns/[id] Thong ke tab" branch=antigravity/252-campaign-analytics target=2026-11-22

  5. JOY commented on Nov 21, 2026

    @JOY
    ContributorAuthor

    checkpoint: session=b3d8a837-d38f-4fd9-a5bc-a376463a6212 PR #295 opened (#295) at commit 535c086 against dev. Local format:check, lint, typecheck, build, and Vitest passed; independent review and CI checks running.

  6. JOY commented on Nov 21, 2026

    @JOY
    ContributorAuthor

    checkpoint: session=b3d8a837-d38f-4fd9-a5bc-a376463a6212 PR #295 (#295) squash-merged into DOS/Give dev at merge commit 8ff173ee18d6c514965615b27dd3ba1df05eee19 (from accepted head fdd47fe62946ecd7792eb893d85e4268d5d5cf3c). Vercel dev/beta deployment completed with status success (https://vercel.com/metados/give/BKFXW2Kcz9e8ta3JuBZUhoHL5hFG -> https://beta.give.vn); PR preview also passed (https://give-git-antigravity-252-campaign-analytics-metados.vercel.app). Local worktree and branch cleaned up.

  7. JOY commented on Nov 21, 2026

    @JOY
    ContributorAuthor

    handoff: session=b3d8a837-d38f-4fd9-a5bc-a376463a6212 to=83b36fa6-8c08-49d6-aeec-63bab02a5e52

    Done: Implemented organizer campaign analytics in apps/web (privacy-safe, bot-filtered, same-origin-checked, IPv6-/64 rate-limited POST /api/analytics/event route; client-side daily-deduplicated view beacon and share-click tracking; organizer /me/campaigns/[id]?tab=analytics Thống kê tab with 7/30/90-day switcher, KPI strip, daily trend chart & responsive breakdown, referrer breakdown, empty/error states, and full test suite). Merged via PR #295 (#295) into DOS/Give dev at merge commit 8ff173ee18d6c514965615b27dd3ba1df05eee19 (checkpoint #issuecomment-7067695598).
    Evidence: Required CI checks Lint (1m15s) and Build all apps (40s) passed on accepted head fdd47fe62946ecd7792eb893d85e4268d5d5cf3c; fresh-context independent review completed with all 3 Important and 6 Minor findings resolved before merge; Vercel dev deployment succeeded (https://vercel.com/metados/give/BKFXW2Kcz9e8ta3JuBZUhoHL5hFG -> https://beta.give.vn).
    Remaining: Live beta smoke verification (optional) and Production promotion (dev -> main / give.vn) after DB prerequisite DOS/DOS.Me#1852 (20261129120000_give_campaign_analytics.sql) reaches DOS/DOS.Me main, which is Give Product Owner (Claude PO) exclusive step with JOY approval. Keep #252 open until Production promotion completes.
    Next step: Campaigns PO records dev completion and coordinates Production promotion handoff with Give Product Owner once DOS/DOS.Me#1852 lands on main.
    Blockers: Production promotion requires DOS/DOS.Me#1852 on main and JOY approval via Give Product Owner (Claude PO).
    Branch: merged into dev at 8ff173ee18d6c514965615b27dd3ba1df05eee19 (feature branch antigravity/252-campaign-analytics merged and local worktree removed).

  8. JOY commented on Nov 21, 2026

    @JOY
    ContributorAuthor

    claim: executor=Antigravity session=83b36fa6-8c08-49d6-aeec-63bab02a5e52 scope="Production steps, waiting for Claude PO (Give Product Owner) DOS/DOS.Me#1852 + #295 dev -> main promotion" branch=antigravity/252-campaign-analytics target=2026-11-28

  9. JOY commented on Nov 21, 2026

    @JOY
    ContributorAuthor

    checkpoint: session=83b36fa6-8c08-49d6-aeec-63bab02a5e52 waiting for Production promotion (DOS/DOS.Me main then DOS/Give main / give.vn) by Give Product Owner (Claude Code) after JOY approval; #295 merged at 8ff173e and deployed to https://beta.give.vn (Vercel success).

  10. JOY commented on Nov 22, 2026

    @JOY
    ContributorAuthor

    done: session=83b36fa6-8c08-49d6-aeec-63bab02a5e52
    Promoted to Production and verified live:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    line:campaignsProduct line: campaignspo:agyOwned by Antigravity PO (mutual-exclusion parallel PO label)

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions