How to Integrate Lovable with UserTesting

UserTesting's API access requires an API key from your account. The process for obtaining this key varies depending on your UserTesting plan — on Enterprise accounts, API keys are typically available in Account Settings → Integrations or Developer Settings. On Plus accounts, you may need to contact UserTesting support to request API access. Log in to your UserTesting account and navigate to your account settings — look for 'Integrations', 'Developer', or 'API' sections in the settings menu. UserTesting's API uses token-based authentication. Depending on the API version your account has access to, authentication may use a Bearer token, a client ID + client secret combination for OAuth2, or an API key passed as a header. The most common setup for UserTesting's v1 REST API uses an API key in the Authorization header formatted as 'Bearer [api_key]' or as a custom 'X-API-Token' header — consult UserTesting's API documentation at developers.usertesting.com for the exact header format your account uses. If you are on a plan that requires OAuth2, you will need a client_id and client_secret from your developer settings. The OAuth2 flow generates access tokens with expiration — for a backend integration, use the client credentials grant type to generate long-lived tokens that can be stored in Cloud Secrets and refreshed when they expire. Once you have your credentials, go to your Lovable project, open the Cloud tab by clicking the + icon next to Preview, click Secrets, and add USERTESTING_API_KEY with your API key value. If using OAuth2, add USERTESTING_CLIENT_ID and USERTESTING_CLIENT_SECRET. Also store the API base URL as USERTESTING_BASE_URL — UserTesting's API base URL is typically https://app.usertesting.com/api/v1 but may vary by account region. Save all secrets.

Create a Supabase Edge Function that acts as a secure proxy between your Lovable React components and the UserTesting API. This function reads the API key from Deno.env.get('USERTESTING_API_KEY'), constructs authenticated requests to UserTesting's API, and returns the response data to the frontend. The most useful UserTesting API endpoints for a research dashboard are: GET /tests (list all tests with status, dates, and participant counts), GET /tests/{test_id} (test details including all tasks, metrics configuration, and result summary), GET /tests/{test_id}/sessions (individual participant session records with task completion data and scores), and GET /tests/{test_id}/highlights (video highlight clips curated from the test). Design the proxy function to accept a 'resource' parameter identifying which UserTesting endpoint to call, and optional 'test_id' and pagination parameters. The function validates the resource type, constructs the appropriate UserTesting API URL, makes the authenticated request, and returns the response. Include error handling for common UserTesting API errors: 401 (invalid or expired API key), 403 (insufficient plan access for API), 404 (test not found), and 429 (rate limit exceeded). For the authorization header format, UserTesting's API documentation specifies the exact format for your plan type. A common format is 'Bearer [token]' — test this against the API before deploying to ensure authentication succeeds. UserTesting may also require specific Accept headers or API version headers on requests. To avoid hitting UserTesting's API rate limits on dashboard page loads, implement a caching layer: store fetched test results in a Supabase 'research_cache' table with a fetched_at timestamp, and return cached data if it is less than 30 minutes old. Only make fresh API calls when the cache is stale. This is especially important for test lists that change infrequently.

1// supabase/functions/usertesting-proxy/index.ts
2import { serve } from 'https://deno.land/std@0.168.0/http/server.ts';
3import { createClient } from 'https://esm.sh/@supabase/supabase-js@2';
4
5const corsHeaders = {
6  'Access-Control-Allow-Origin': '*',
7  'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type',
8};
9
10serve(async (req) => {
11  if (req.method === 'OPTIONS') return new Response('ok', { headers: corsHeaders });
12
13  try {
14    const apiKey = Deno.env.get('USERTESTING_API_KEY');
15    const baseUrl = Deno.env.get('USERTESTING_BASE_URL') ?? 'https://app.usertesting.com/api/v1';
16
17    if (!apiKey) {
18      return new Response(JSON.stringify({ error: 'UserTesting API key not configured' }), {
19        status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' },
20      });
21    }
22
23    const supabase = createClient(
24      Deno.env.get('SUPABASE_URL') ?? '',
25      Deno.env.get('SUPABASE_SERVICE_ROLE_KEY') ?? ''
26    );
27
28    const { resource, test_id, page = 1, per_page = 20 } = await req.json();
29
30    // Check cache for test list
31    if (resource === 'tests') {
32      const { data: cached } = await supabase
33        .from('research_cache')
34        .select('data, fetched_at')
35        .eq('cache_key', 'tests_list')
36        .single();
37      const cacheAge = cached?.fetched_at
38        ? (Date.now() - new Date(cached.fetched_at).getTime()) / 60000
39        : Infinity;
40      if (cached && cacheAge < 30) {
41        return new Response(JSON.stringify(cached.data), {
42          headers: { ...corsHeaders, 'Content-Type': 'application/json', 'X-From-Cache': 'true' },
43        });
44      }
45    }
46
47    const utHeaders = {
48      'Authorization': `Bearer ${apiKey}`,
49      'Content-Type': 'application/json',
50      'Accept': 'application/json',
51    };
52
53    let apiUrl = '';
54    switch (resource) {
55      case 'tests': apiUrl = `${baseUrl}/tests?page=${page}&per_page=${per_page}`; break;
56      case 'test-detail': apiUrl = `${baseUrl}/tests/${test_id}`; break;
57      case 'sessions': apiUrl = `${baseUrl}/tests/${test_id}/sessions?per_page=${per_page}`; break;
58      case 'highlights': apiUrl = `${baseUrl}/tests/${test_id}/highlights`; break;
59      default:
60        return new Response(JSON.stringify({ error: 'Invalid resource' }), {
61          status: 400, headers: { ...corsHeaders, 'Content-Type': 'application/json' },
62        });
63    }
64
65    const response = await fetch(apiUrl, { headers: utHeaders });
66    const data = await response.json();
67
68    // Update cache for test list
69    if (resource === 'tests' && response.ok) {
70      await supabase.from('research_cache').upsert({
71        cache_key: 'tests_list',
72        data,
73        fetched_at: new Date().toISOString(),
74      }, { onConflict: 'cache_key' });
75    }
76
77    return new Response(JSON.stringify(data), {
78      status: response.status,
79      headers: { ...corsHeaders, 'Content-Type': 'application/json' },
80    });
81  } catch (error) {
82    return new Response(JSON.stringify({ error: String(error) }), {
83      status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' },
84    });
85  }
86});

Create a React component that calls the usertesting-proxy Edge Function and displays UserTesting research data in a clear, actionable format for the product team. The dashboard should show the most important research metrics at a glance without requiring team members to log into UserTesting. The dashboard component should fetch the test list on mount, display a summary row for each test (test name, completion date, participant count, and average satisfaction score), and provide links to open the full test in UserTesting for detailed analysis. For each test, the satisfaction score is typically represented as a numeric rating from 1-5 that UserTesting aggregates across all participants — display this as a star rating or colored score indicator. For the test detail view, create a separate component or modal that fetches and displays session-level metrics when a test is selected. Show task completion rates (percentage of participants who successfully completed each task), average time to complete each task, and any highlight clips available via the API. Highlight clips are short video segments that testers or researchers have marked as significant — displaying their titles and linking to UserTesting for playback surfaces the most important moments from each test. Add a loading state for the initial data fetch and an error state for when the API is unavailable or the API key is invalid. The research cache means the dashboard loads quickly on repeat visits, showing cached data with a 'Last updated X minutes ago' indicator and a manual refresh button for when fresh data is needed. For the caching approach in the Supabase Edge Function, you will need a research_cache table in your Supabase database. Ask Lovable to create this table with columns: cache_key (text, primary key), data (jsonb), and fetched_at (timestamptz). Enable Row Level Security with a policy that allows only authenticated users to read from this table.

1// src/pages/ResearchDashboard.tsx
2import { useEffect, useState, useCallback } from 'react';
3import { supabase } from '@/integrations/supabase/client';
4import { Card, CardHeader, CardTitle, CardContent } from '@/components/ui/card';
5import { Badge } from '@/components/ui/badge';
6import { Button } from '@/components/ui/button';
7import { RefreshCw, ExternalLink, Star } from 'lucide-react';
8
9interface UTTest {
10  id: number;
11  name: string;
12  created_at: string;
13  status: string;
14  sessions_count: number;
15  avg_satisfaction?: number;
16  url?: string;
17}
18
19export function ResearchDashboard() {
20  const [tests, setTests] = useState<UTTest[]>([]);
21  const [loading, setLoading] = useState(true);
22  const [error, setError] = useState<string | null>(null);
23  const [lastUpdated, setLastUpdated] = useState<Date | null>(null);
24
25  const fetchTests = useCallback(async () => {
26    setLoading(true);
27    setError(null);
28    try {
29      const { data, error: fnError } = await supabase.functions.invoke('usertesting-proxy', {
30        body: { resource: 'tests', per_page: 20 },
31      });
32      if (fnError) throw fnError;
33      setTests(Array.isArray(data?.tests) ? data.tests : []);
34      setLastUpdated(new Date());
35    } catch (err) {
36      setError('Failed to load research data. Check the UserTesting API key in Cloud Secrets.');
37    } finally {
38      setLoading(false);
39    }
40  }, []);
41
42  useEffect(() => { fetchTests(); }, [fetchTests]);
43
44  const avgScore = tests.length > 0
45    ? (tests.reduce((sum, t) => sum + (t.avg_satisfaction ?? 0), 0) / tests.length).toFixed(1)
46    : 'N/A';
47
48  if (loading) return <div className="p-8 animate-pulse"><div className="h-8 bg-gray-200 rounded w-1/4 mb-6" /></div>;
49
50  return (
51    <div className="p-6 space-y-6">
52      <div className="flex items-center justify-between">
53        <h1 className="text-2xl font-bold">Research Dashboard</h1>
54        <Button variant="outline" size="sm" onClick={fetchTests}>
55          <RefreshCw className="h-4 w-4 mr-2" /> Refresh
56        </Button>
57      </div>
58      {lastUpdated && <p className="text-sm text-gray-400">Last updated {lastUpdated.toLocaleTimeString()}</p>}
59      {error && <div className="p-4 bg-red-50 text-red-700 rounded-lg">{error}</div>}
60      <div className="grid grid-cols-2 gap-4">
61        <Card><CardContent className="pt-6"><p className="text-3xl font-bold">{tests.length}</p><p className="text-sm text-gray-500">Total Tests</p></CardContent></Card>
62        <Card><CardContent className="pt-6"><p className="text-3xl font-bold">{avgScore}</p><p className="text-sm text-gray-500">Avg Satisfaction</p></CardContent></Card>
63      </div>
64      <div className="space-y-3">
65        {tests.map((test) => (
66          <Card key={test.id}>
67            <CardHeader>
68              <div className="flex items-start justify-between">
69                <div>
70                  <CardTitle className="text-base">{test.name}</CardTitle>
71                  <p className="text-sm text-gray-500 mt-1">{new Date(test.created_at).toLocaleDateString()}</p>
72                </div>
73                <div className="flex items-center gap-2">
74                  <Badge variant="secondary">{test.sessions_count} participants</Badge>
75                  {test.url && <a href={test.url} target="_blank" rel="noopener noreferrer"><Button variant="ghost" size="sm"><ExternalLink className="h-4 w-4" /></Button></a>}
76                </div>
77              </div>
78            </CardHeader>
79          </Card>
80        ))}
81      </div>
82    </div>
83  );
84}

Extend the research dashboard with a test detail view that shows session-level metrics and highlight clips for individual tests. When a team member clicks a test in the dashboard, fetch and display the participant session data and any highlight clips available via the UserTesting API. UserTesting sessions represent individual participant recordings. Each session record from the API typically includes: the participant's completion status for each task, their ratings for the tasks, the total session duration, and metadata about the participant's device and location. Display task completion rates as percentages — if 8 of 10 participants completed a task, show 80% with a green indicator. Display average task durations to identify which tasks take longer than expected. Highlight clips are curated short video segments that researchers mark as significant during test review. The highlights API endpoint returns clip metadata: the title given to the highlight, the timestamp range in the full session, and potentially a thumbnail URL. Displaying highlight titles and linking to them in UserTesting surfaces the most important moments from each test without requiring team members to watch full sessions. For displaying the session data, a simple table view works well: one row per task, with columns for task description, completion rate, average time, and average satisfaction score. Add color coding — green for high completion rates (above 80%), yellow for medium (60-80%), red for low (below 60%). This gives an immediate visual signal of which tasks need design attention. Create a Supabase table to store processed test metrics so the dashboard can render historical data without API calls. After fetching a test's session data, aggregate the metrics and store them in a 'test_metrics' table with columns: test_id, task_id, task_name, completion_rate, avg_duration_seconds, avg_satisfaction, fetched_at. Query this table for dashboard rendering and refresh on demand.