User Source Tracking

Good to know

This feature is available from version v2.2.0 onwards. If you're using an earlier version, please refer to the changelog for upgrade instructions.

Feature Introduction

Understanding where your users come from is crucial for effective marketing and growth tracking.

When users visit your application with UTM parameters or other tracking parameters (e.g., http://localhost:3000/?utm_source=nexty), the system automatically captures these parameters and stores them in browser cookies:

When users login for the first time, the values recorded in cookies are saved to the referral field in the users table, and the cookie is deleted simultaneously. If no tracking parameters were present when the user first visited (i.e., no cookies exist), the referral field defaults to direct, indicating organic or direct traffic.

Customization and Extensions

Modifying Tracking Parameters

To customize which URL parameters are tracked, modify the referralParams array in your middleware.ts. Parameters are checked in order, with the first matching parameter taking priority:

const referralParams = ['utm_source', 'ref', 'via', 'aff', 'referral', 'referral_code'];

Setting Cookie Expiration Time

By default, referral cookies are session-based and expire when the browser closes. To persist source information across browser sessions, configure a custom expiration time:

supabaseResponse.cookies.set('referral_source', referralValue, {
  maxAge: 7 * 24 * 60 * 60 // 7 days
});

Adding Other Login Methods

When implementing additional OAuth providers or login methods, ensure referral information is preserved by passing it through the authentication flow:

const signInWithGithub = async () => {
  const redirectUrl = new URL(`${window.location.origin}/auth/callback`);
 
  // Add source information
  const referral = getReferral();
  redirectUrl.searchParams.set("referral", referral || "direct");
 
  if (next) {
    redirectUrl.searchParams.set("next", next);
  }
  return await supabase.auth.signInWithOAuth({
    provider: "github",
    options: {
      redirectTo: redirectUrl.toString(),
    },
  });
};

Saving to Database

In your authentication callback handler, save the referral information to the user's profile:

await supabase.rpc(
  'update_my_profile',
  {
    new_full_name: user.user_metadata?.full_name || user.user_metadata?.name || '',
    new_avatar_url: user.user_metadata?.avatar_url || '',
    new_referral: referral
  }
);