Menu

User Source & Attribution

In SaaS products, user source and attribution is a critical infrastructure component used for user analysis, growth analysis, and advertising campaign analysis.

Starting from version v3.2.10, NEXTY.DEV has added the userSource table with built-in user source tracking functionality, which can be toggled via the NEXT_PUBLIC_USER_SOURCE_TRACKING_ENABLED environment variable.

Key Features

NEXTY.DEV is the first SaaS boilerplate to provide developers with user source tracking and attribution functionality, giving your product these capabilities from day one:

  • One-Click Toggle: Control whether to store data via NEXT_PUBLIC_USER_SOURCE_TRACKING_ENABLED.
  • Comprehensive Source Data:
    • Client-side captures UTM / referrer / landing page / device / language, etc.
    • Server-side completes geographic information and parses browser data.
  • Privacy-Friendly: If you enable Cookie Consent (NEXT_PUBLIC_COOKIE_CONSENT_ENABLED), tracking cookies won't be written when users explicitly decline cookies, protecting user privacy.
  • Non-Invasive: Source tracking logic is completely isolated from business code and won't affect your existing business logic.
  • Extensible: user_source.metadata (jsonb) is reserved for extension, making it easy to integrate custom parameters, advertising platform click IDs, etc. in the future.

Usage

1) Enable/Disable Feature

Set the environment variable NEXT_PUBLIC_USER_SOURCE_TRACKING_ENABLED to enable or disable. true enables it, false disables it. Default is true.

NEXT_PUBLIC_USER_SOURCE_TRACKING_ENABLED="true"

2) Enable Cookie Consent (Optional)

Some regions have strict privacy compliance requirements that require explicit user consent before using cookies. You can enable Cookie Consent via the NEXT_PUBLIC_COOKIE_CONSENT_ENABLED environment variable. true enables it, false disables it. Default is false.

NEXT_PUBLIC_COOKIE_CONSENT_ENABLED="true"

When you enable Cookie Consent, users will see a cookie consent modal on their first visit, where they can choose to accept or decline.

When users choose Decline Cookies, the client won't write user_tracking_data.

Table Structure: user_source

Below are the core fields recorded in this table:

  • Channel & Affiliate

    • aff_code: From URL parameters aff / via / ref

  • UTM Parameters

    • utm_source / utm_medium / utm_campaign / utm_term / utm_content

  • Source & Landing Page

    • referrer: Complete referrer URL
    • referrer_domain: Domain parsed from referrer
    • landing_page: First recorded landing page URL

  • Device & Browser (User-Agent + Client Supplement)

    • user_agent
    • browser / browser_version
    • os / os_version
    • device_type
    • device_brand / device_model
    • screen_width / screen_height
    • language / timezone

  • Network & Geography

    • ip_address
    • country_code

  • Extension

    • metadata (jsonb): Reserved extension field (click ID, custom parameters, experiment groups, etc.)

Below are the files involved in the user source module. If you need secondary development, you can have AI complete custom requirements.

  • lib/db/schema.ts: user_source table structure
  • lib/tracking/client.ts: Client-side collection and cookie writing
  • lib/tracking/server.ts: Server-side completion and database writing
  • lib/tracking/shared.ts: Types and common methods
  • lib/auth/index.ts: Better Auth hook to write user_source after user creation
  • actions/users/admin.ts: Admin user data query example

Usage in Admin Dashboard

The boilerplate user management feature has been upgraded to support joined queries. You can see user source data in the user list.

user list

You can extend and add data based on your needs:

  • Display user source data charts or order conversion data charts on the Overview page
  • Show each user's order count or historical payment amount in the user list

This feature only requires simple modifications to a few query statements, but since it's not essential for every product, the boilerplate doesn't include it by default.