How to Integrate Lovable with Segment

Segment organizes event collection through Sources — each Source represents one data origin (your web app, mobile app, backend server) with its own Write Key. Creating separate Sources for your development and production environments is essential for keeping test events out of your production analytics data. Log in to your Segment workspace at app.segment.com. In the left sidebar, click 'Sources', then click 'Add Source'. Select 'JavaScript Website' as the Source type — this is the correct source type for a Lovable Vite+React single-page application. Give it a name matching your app and environment (for example, 'My App - Production'). Click 'Add Source'. After creation, you will see the Source's Write Key on the Overview page — a URL-safe string starting with a random series of characters. Copy this value. Also create a second Source named 'My App - Development' for testing — you will use the development Source's Write Key in your local environment file (.env.local) and the production Source's Write Key in Lovable's Cloud Secrets. Go to your Lovable project, open the Cloud tab, click Secrets, and add VITE_SEGMENT_WRITE_KEY with your production Write Key value. Also add SEGMENT_WRITE_KEY with the same value for use in Edge Functions. These are technically the same key — the Write Key is public and can only be used to send data to Segment, not to read data. Using separate variable names for client and server is good practice. For Segment destinations, go to your Source → Destinations → Add Destination. Add Mixpanel, GA4, or Amplitude to route events without any additional code in your Lovable app. Each destination requires providing the relevant API key (Mixpanel Project Token, GA4 Measurement ID, or Amplitude API Key) in Segment's destination configuration interface.

Install the @segment/analytics-next package and create a centralized Segment utility module. Analytics.js 2.0 (the 'next' package) is Segment's modern browser SDK with improved performance, tree-shaking, and middleware support compared to the legacy analytics.js snippet approach. The utility should export typed wrappers around Segment's four core tracking methods: page() for pageview tracking, track() for custom events, identify() for user identification, and group() for account-level tracking. Centralizing these calls through a utility ensures consistent event formatting across your entire Lovable app and makes it easy to add default properties (app version, environment, current page) to every event. Segment's Analytics.js 2.0 is initialized with the AnalyticsBrowser.load() static method, passing your Write Key. Unlike older analytics libraries, the 2.0 SDK returns a promise-based interface and handles initialization asynchronously — you do not need to wait for initialization before calling track events, as the SDK queues events internally until initialization completes. This makes it safe to call track() immediately after component mount without checking whether the SDK is ready. For page tracking in a React Router SPA, create a hook that listens to location changes and calls analytics.page() with the current path, title, and any relevant page properties. SPA navigation does not trigger the browser's native page load event, so explicit page() calls on route changes are required for accurate pageview data in destination tools like GA4 and Mixpanel. For user identification, hook into the Supabase auth state change event and call analytics.identify() with the Supabase user UUID as the userId and key user traits as the second argument. Segment's identify() call is idempotent — calling it multiple times with the same userId and traits is safe. For new user signups, call analytics.alias(newUserId) before identify() to merge the anonymous device session with the newly created user identity.

1// src/lib/segment.ts
2import { AnalyticsBrowser } from '@segment/analytics-next';
3
4const writeKey = import.meta.env.VITE_SEGMENT_WRITE_KEY;
5
6export const analytics = writeKey
7  ? AnalyticsBrowser.load({ writeKey })
8  : null;
9
10if (!writeKey) {
11  console.warn('Segment Write Key not configured. Analytics disabled.');
12}
13
14export async function page(
15  name?: string,
16  properties?: Record<string, unknown>
17) {
18  await analytics?.page(name, properties);
19}
20
21export async function track(
22  event: string,
23  properties?: Record<string, unknown>
24) {
25  await analytics?.track(event, properties);
26}
27
28export async function identify(
29  userId: string,
30  traits?: Record<string, unknown>
31) {
32  await analytics?.identify(userId, traits);
33}
34
35export async function group(
36  groupId: string,
37  traits?: Record<string, unknown>
38) {
39  await analytics?.group(groupId, traits);
40}
41
42export async function alias(previousId: string) {
43  await analytics?.alias(previousId);
44}
45
46export async function reset() {
47  await analytics?.reset();
48}

With the Segment utility in place, add tracking calls at the most important behavioral moments in your application. Segment's value is maximized when you have a complete event taxonomy that flows to multiple destinations — getting the tracking right at the source level means all downstream tools receive clean, consistent data. For authentication events, hook into the Supabase auth state change to call identify() after login and reset() after logout. For new signups, use the alias + identify pattern: immediately after the new user's account is created, call alias(newUserId) to merge the anonymous session, then call identify(newUserId, traits) to set the user's profile. Call track('Signed Up') with the signup method and plan. This sequence correctly handles the critical identity stitching that connects pre-signup and post-signup behavior in Segment's identity graph. For page tracking, create a useSegmentPageTracking hook that calls analytics.page() on every React Router location change. Page tracking in Segment is the foundation of session analysis — most analytics destinations (GA4, Mixpanel, Amplitude) use page events to detect session boundaries and calculate time-on-site metrics. Without page events, session-level metrics in these tools will be incomplete. For feature tracking, add analytics.track() calls at the key user actions in your app. Use Segment's naming conventions: object-action format in title case ('Project Created', 'File Exported', 'Plan Upgraded'). Include contextual properties on each event — the user's current plan, the feature name, the outcome. These properties are forwarded to all destination tools and can be used for segmentation in Mixpanel, Amplitude, and marketing automation tools. For B2B applications, call analytics.group() after login when the user is associated with an organization, passing the organization's ID and properties (name, plan, employee count, industry). This enables account-level analytics in tools like Salesforce, Mixpanel Groups, and Amplitude Accounts.

1// src/hooks/useSegmentAuth.ts
2import { useEffect } from 'react';
3import { supabase } from '@/integrations/supabase/client';
4import { identify, track, reset, alias } from '@/lib/segment';
5
6export function useSegmentAuth() {
7  useEffect(() => {
8    const { data: { subscription } } = supabase.auth.onAuthStateChange(
9      async (event, session) => {
10        if ((event === 'SIGNED_IN' || event === 'USER_UPDATED') && session?.user) {
11          const user = session.user;
12          const isNewUser = event === 'SIGNED_IN' &&
13            Math.abs(new Date(user.created_at).getTime() - Date.now()) < 10000;
14
15          if (isNewUser) {
16            await alias(user.id); // Merge anonymous session
17            await track('Signed Up', { method: user.app_metadata?.provider ?? 'email' });
18          } else {
19            await track('Logged In');
20          }
21
22          await identify(user.id, {
23            email: user.email,
24            createdAt: user.created_at,
25            plan: 'free', // fetch from profiles table
26          });
27        }
28        if (event === 'SIGNED_OUT') {
29          await track('Logged Out');
30          await reset();
31        }
32      }
33    );
34    return () => subscription.unsubscribe();
35  }, []);
36}

For server-side events that originate in Edge Functions — payment confirmations, email delivery events, scheduled job results, webhook-triggered conversions — send events to Segment using the HTTP Tracking API. This ensures server-side events flow through the same Segment pipeline as client-side events, routing to all configured destinations. Segment's HTTP Tracking API endpoint is https://api.segment.io/v1. The API supports the same four event types as the browser SDK: Track (/v1/track), Identify (/v1/identify), Page (/v1/page), and Group (/v1/group). Authentication uses HTTP Basic auth with your Write Key as the username and an empty password — format the Authorization header as 'Basic [base64(writeKey:)]'. Each event payload must include a messageId (a unique UUID for deduplication), a timestamp (ISO 8601 format), and either a userId (for identified users) or an anonymousId (for unauthenticated events — use a UUID or session identifier). The Track event payload also requires an event name (string) and optionally a properties object. Include a context object in each payload with app information — this helps Segment distinguish server-side events from client-side events in reports. For payment events triggered by Stripe webhooks, the userId should be the Supabase user UUID associated with the Stripe customer. Look this up from your Supabase database using the Stripe customer ID before sending the Segment event — linking payment events to the correct user identity ensures accurate revenue attribution in tools like Mixpanel, Amplitude, and your data warehouse. The Edge Function should support batching — Segment's HTTP Batch API (/v1/batch) accepts up to 500 events in a single request, making it efficient for bulk server-side event submission. For most webhook handlers, a single event per request is fine, but batch support is useful for data backfill scenarios.

1// supabase/functions/segment-track/index.ts
2import { serve } from 'https://deno.land/std@0.168.0/http/server.ts';
3
4const corsHeaders = {
5  'Access-Control-Allow-Origin': '*',
6  'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type',
7};
8
9function generateId(): string {
10  return crypto.randomUUID();
11}
12
13serve(async (req) => {
14  if (req.method === 'OPTIONS') return new Response('ok', { headers: corsHeaders });
15
16  try {
17    const writeKey = Deno.env.get('SEGMENT_WRITE_KEY');
18    if (!writeKey) {
19      console.error('SEGMENT_WRITE_KEY not configured');
20      return new Response(JSON.stringify({ success: false }), {
21        status: 200, headers: { ...corsHeaders, 'Content-Type': 'application/json' },
22      });
23    }
24
25    const body = await req.json();
26    const { event_type = 'track', user_id, anonymous_id, event_name,
27            properties, traits, page_name } = body;
28
29    if (!user_id && !anonymous_id) {
30      return new Response(JSON.stringify({ error: 'user_id or anonymous_id required' }), {
31        status: 400, headers: { ...corsHeaders, 'Content-Type': 'application/json' },
32      });
33    }
34
35    const payload: Record<string, unknown> = {
36      messageId: generateId(),
37      timestamp: new Date().toISOString(),
38      context: { library: { name: 'lovable-edge-function', version: '1.0.0' } },
39    };
40
41    if (user_id) payload.userId = user_id;
42    if (anonymous_id) payload.anonymousId = anonymous_id;
43
44    if (event_type === 'track') {
45      payload.event = event_name;
46      payload.properties = properties ?? {};
47    } else if (event_type === 'identify') {
48      payload.traits = traits ?? {};
49    } else if (event_type === 'page') {
50      payload.name = page_name;
51      payload.properties = properties ?? {};
52    }
53
54    const credentials = btoa(`${writeKey}:`);
55    const response = await fetch(`https://api.segment.io/v1/${event_type}`, {
56      method: 'POST',
57      headers: {
58        'Authorization': `Basic ${credentials}`,
59        'Content-Type': 'application/json',
60      },
61      body: JSON.stringify(payload),
62    });
63
64    console.log('Segment HTTP API status:', response.status);
65    return new Response(JSON.stringify({ success: true }), {
66      headers: { ...corsHeaders, 'Content-Type': 'application/json' },
67    });
68  } catch (error) {
69    console.error('Segment track error:', error);
70    return new Response(JSON.stringify({ success: false }), {
71      status: 200, headers: { ...corsHeaders, 'Content-Type': 'application/json' },
72    });
73  }
74});