How to Integrate Lovable with Amplitude

Start by setting up your Amplitude project and getting the credentials you need. Log in to your Amplitude account at app.amplitude.com. If you are creating a new project, click 'Create Project' from the home screen — give it the name of your Lovable app and select 'Web' as the platform. If you already have an Amplitude project, navigate to Settings (gear icon in the bottom-left sidebar) and select Projects from the left panel. Click on your project name to open its settings. In the General tab, you will find your API Key — a 32-character hexadecimal string. This is the public project identifier used to authenticate your events. Note that Amplitude also has a Secret Key on this page, which is used for specific management API calls. For standard event tracking (both client-side SDK and HTTP API v2 server-side), only the API Key is needed. Copy the API Key. Now go to your Lovable project in the browser. Click the + icon next to the Preview button to open the Cloud tab. Click Secrets in the panel. Click Add secret. Add VITE_AMPLITUDE_API_KEY with your API key value — the VITE_ prefix makes it accessible as import.meta.env.VITE_AMPLITUDE_API_KEY in your React components. Also add AMPLITUDE_API_KEY with the same value for use in Edge Functions via Deno.env.get('AMPLITUDE_API_KEY'). Click Save for each secret. In Amplitude's settings, also configure your project's User Property schema. Go to Settings → Project Settings → Schema and review the default user properties. This is also a good time to enable Session Replay if you are on a paid plan — it provides visual session recordings alongside your event data, giving valuable context for behavioral analysis without any additional code.

Install the @amplitude/analytics-browser package and create a centralized Amplitude utility module that all components import. This utility handles the three core Amplitude patterns: initialization with your API key and configuration options, user identification when a user logs in, and event tracking with typed properties. Amplitude's Browser SDK v2 (the current major version) uses a modular architecture — import only the functions you need from @amplitude/analytics-browser to keep your bundle size minimal. The most important functions are init (initialization), identify (user identification), setUserId (link device to authenticated user), and track (event tracking). The SDK automatically captures device information, platform, OS version, app version (from your package.json), and session data — you do not need to add these to every event manually. Configure the SDK with production-appropriate settings: disable autocapture of all events initially (Amplitude's autocapture can generate noisy data — enable specific autocapture events intentionally), set the logLevel to LogLevel.Warn in production, and configure the flushIntervalMillis to control how frequently events are batched and sent to Amplitude's servers. A lower interval means more real-time data but more HTTP requests; 10 seconds is a good balance for most apps. The identify pattern in Amplitude is slightly different from Mixpanel. Instead of an explicit identify() call with user properties, Amplitude uses setUserId() to link the device to the authenticated user, then uses the Identify class to set user properties. The setUserId should be called immediately when the user's Supabase session is established. When the user logs out, call setUserId(undefined) to reset the association between the device and the logged-out user — this prevents the next user on the same device from inheriting the previous user's identity.

1// src/lib/amplitude.ts
2import * as amplitude from '@amplitude/analytics-browser';
3import { Identify } from '@amplitude/analytics-browser';
4
5const API_KEY = import.meta.env.VITE_AMPLITUDE_API_KEY;
6let initialized = false;
7
8export function initAmplitude() {
9  if (!API_KEY) {
10    console.warn('Amplitude API key not configured. Analytics disabled.');
11    return;
12  }
13  amplitude.init(API_KEY, {
14    logLevel: import.meta.env.DEV ? amplitude.Types.LogLevel.Debug : amplitude.Types.LogLevel.Warn,
15    autocapture: {
16      sessions: true,
17      pageViews: true,
18      formInteractions: false,
19      fileDownloads: false,
20    },
21    flushIntervalMillis: 10000,
22  });
23  initialized = true;
24}
25
26export function identify(userId: string, properties?: Record<string, unknown>) {
27  if (!initialized) return;
28  amplitude.setUserId(userId);
29  if (properties) {
30    const identifyEvent = new Identify();
31    Object.entries(properties).forEach(([key, value]) => {
32      identifyEvent.set(key, value as string | number | boolean);
33    });
34    amplitude.identify(identifyEvent);
35  }
36}
37
38export function track(eventName: string, properties?: Record<string, unknown>) {
39  if (!initialized) return;
40  amplitude.track(eventName, properties);
41}
42
43export function reset() {
44  if (!initialized) return;
45  amplitude.setUserId(undefined);
46  amplitude.reset();
47}

With the Amplitude utility in place, add identification and event tracking at the key behavioral moments in your application. The most important events to track are the ones that predict retention — the actions that separate users who stay from users who leave. For most SaaS apps, these are completing onboarding, using a core feature within the first session, and returning within 3 days. For user identification, hook into your Supabase auth state change event — the same pattern used for Mixpanel. When the 'SIGNED_IN' event fires, call your identify function with the Supabase user ID and key user properties: email (if you want to enable email-based user lookup in Amplitude), plan, account creation date, and any custom attributes relevant to your product. Amplitude's user properties persist across sessions — once you set a user's plan, it is available on all subsequent events without needing to pass it explicitly. For event tracking, follow a naming convention that makes Amplitude's charts readable: use subject-verb pairs in title case ('Project Created', 'Export Downloaded', 'Subscription Upgraded'). Include contextual properties on each event — the current state of the user when the event happened. For a 'Feature Used' event, include: which feature, how many times the user has used it before (to distinguish first-time versus repeat usage), and the user's current plan. These properties enable Amplitude's property filter in charts, allowing you to slice any chart by any event property. Amplitude's Group Analytics feature (available on paid plans) lets you analyze events at the organization or account level rather than the individual user level — useful for B2B apps where you care about company-level retention. To use groups, call setGroup() with the group type and group ID when a user is associated with an organization in your app.

1// src/hooks/useAmplitudeTracking.ts
2import { useEffect } from 'react';
3import { supabase } from '@/integrations/supabase/client';
4import { identify, track, reset } from '@/lib/amplitude';
5
6export function useAmplitudeTracking() {
7  useEffect(() => {
8    const { data: { subscription } } = supabase.auth.onAuthStateChange(
9      async (event, session) => {
10        if (event === 'SIGNED_IN' && session?.user) {
11          const user = session.user;
12          identify(user.id, {
13            email: user.email,
14            plan: 'free', // fetch from your users/profiles table
15            created_at: user.created_at,
16            signup_method: user.app_metadata?.provider ?? 'email',
17          });
18          track('Session Started');
19        }
20        if (event === 'SIGNED_OUT') {
21          track('Session Ended');
22          reset();
23        }
24      }
25    );
26    return () => subscription.unsubscribe();
27  }, []);
28}
29
30// Helper for feature tracking across components
31export function trackFeatureUse(featureName: string, additionalProperties?: Record<string, unknown>) {
32  track('Feature Used', {
33    feature_name: featureName,
34    timestamp: new Date().toISOString(),
35    ...additionalProperties,
36  });
37}

For server-side event tracking — payment completions, email deliveries, scheduled job results, and any event that needs to be recorded regardless of the user's browser state — create a Supabase Edge Function that calls Amplitude's HTTP API v2 directly. This API accepts JSON event payloads and supports batched event uploads, making it efficient for high-volume server-side event streams. Amplitude's HTTP API v2 endpoint is https://api2.amplitude.com/2/httpapi. The request body is a JSON object containing your API key and an array of event objects. Each event object requires an event_type string and either a user_id (for authenticated users) or a device_id (for anonymous tracking). Events can optionally include event_properties (key-value pairs specific to this event), user_properties (updates to the user's profile), and a time field (Unix timestamp in milliseconds — defaults to the current time if omitted). The Edge Function should accept a POST request from your Lovable frontend or from other Edge Functions (such as the Stripe webhook handler) with the event data as a JSON body. Validate the inputs, format them as an Amplitude HTTP API v2 payload, and POST to Amplitude's endpoint. The function reads the API key from Deno.env.get('AMPLITUDE_API_KEY') — never hardcode it. An important consideration for server-side events: the user_id must match the same user_id used in the client-side SDK (the Supabase user UUID). If the IDs do not match, Amplitude creates separate user profiles for the same person, fragmenting their journey across your reports. Always use the Supabase user UUID consistently across both client-side and server-side tracking calls.

1// supabase/functions/amplitude-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
9interface AmplitudeEvent {
10  event_type: string;
11  user_id?: string;
12  device_id?: string;
13  event_properties?: Record<string, unknown>;
14  user_properties?: Record<string, unknown>;
15  time?: number;
16}
17
18serve(async (req) => {
19  if (req.method === 'OPTIONS') {
20    return new Response('ok', { headers: corsHeaders });
21  }
22
23  try {
24    const apiKey = Deno.env.get('AMPLITUDE_API_KEY');
25    if (!apiKey) {
26      console.error('AMPLITUDE_API_KEY not configured');
27      return new Response(JSON.stringify({ success: false }), {
28        status: 200,
29        headers: { ...corsHeaders, 'Content-Type': 'application/json' },
30      });
31    }
32
33    const body = await req.json();
34    // Support both single event and events array
35    const events: AmplitudeEvent[] = Array.isArray(body.events)
36      ? body.events
37      : [{ event_type: body.event_type, user_id: body.user_id, device_id: body.device_id,
38           event_properties: body.event_properties, user_properties: body.user_properties }];
39
40    const validEvents = events.filter(e => e.event_type && (e.user_id || e.device_id));
41    if (validEvents.length === 0) {
42      return new Response(
43        JSON.stringify({ error: 'Each event requires event_type and user_id or device_id' }),
44        { status: 400, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
45      );
46    }
47
48    const payload = {
49      api_key: apiKey,
50      events: validEvents.map(e => ({ ...e, time: e.time ?? Date.now() })),
51    };
52
53    const response = await fetch('https://api2.amplitude.com/2/httpapi', {
54      method: 'POST',
55      headers: { 'Content-Type': 'application/json', 'Accept': '*/*' },
56      body: JSON.stringify(payload),
57    });
58
59    const result = await response.json();
60    console.log('Amplitude HTTP API response:', response.status, result);
61
62    return new Response(JSON.stringify({ success: true, events_ingested: validEvents.length }), {
63      headers: { ...corsHeaders, 'Content-Type': 'application/json' },
64    });
65  } catch (error) {
66    console.error('Amplitude track error:', error);
67    return new Response(JSON.stringify({ success: false }), {
68      status: 200,
69      headers: { ...corsHeaders, 'Content-Type': 'application/json' },
70    });
71  }
72});

With tracking implemented, set up the Amplitude reports that provide immediate product insight. The three most valuable reports for a new Lovable app are: a Retention Analysis chart showing day-1, day-7, and day-30 return rates; a User Journey chart showing the common paths through your app after signup; and a Funnel chart measuring onboarding completion rates. For the Retention Analysis, go to Amplitude → Charts → New Chart → Retention Analysis. Set the 'Did event A' condition to your signup event (the event that marks a new user), and set the 'and came back to do event B' condition to any session event (like a pageview or 'Session Started'). Set the date range to the last 90 days. Amplitude calculates what percentage of users from each signup cohort return each subsequent day, week, or month. This chart is the most important early-stage product metric — if day-1 retention is below 30%, focus on onboarding improvements before anything else. For the User Journey report, go to Charts → Pathfinder. Set the starting event to your signup or onboarding completion event. The chart visualizes the most common paths users take through your app in the first session, revealing which features are discovered organically versus which are hidden. Features with unexpectedly low discovery rates may need better UI placement. For the Funnel Analysis, go to Charts → Funnel Analysis and add the events in your critical conversion path — signup → onboarding step 1 → onboarding step 2 → first value action → subscription. The chart shows conversion rates at each step and, crucially, the time each step takes. Long completion times at specific steps often indicate friction points. For complex Amplitude implementations or integrating Amplitude Experiment for A/B testing in your Lovable app, RapidDev's team can help set up the experiment SDK and result analysis workflows.