Quickstart: data collection in 30 minutes

Questa è una lezione pratica, e anche qui il binario è quello tabellare: gli eventi che imposti oggi finiranno in tabelle su cui farai query domani. In mezz’ora non costruisci una piattaforma completa. Puoi però evitare gli errori che rendono inutili i primi report: eventi senza definizione, proprietà incoerenti, identità non risolta e nessun test di qualità. Questo quickstart porta a un setup piccolo, verificabile e già governato. Pochi eventi, definiti bene, inviati in modo ripetibile e controllati subito.

L’obiettivo del quickstart

Questo quickstart attiva in trenta minuti un tracciamento minimo con eventi definiti, identità risolta e controlli di qualità già operativi. Niente di più, ma nemmeno di meno.

Il percorso in cinque tappe

1. Crea source e destination e installa lo snippet di raccolta.

2. Implementa tre chiamate che coprono identità, azione di business e navigazione.

3. Verifica nel debugger che gli eventi arrivino tipati alla destination.

4. Documenta ogni evento con proprietà, tipi, fonte e owner in the tracking plan.

5. Attiva un alert sul volume per intercettare interruzioni del tracciamento.

Setup minimo in dieci minuti

Si parte dall’infrastruttura minima. Crea un account gratuito su segment.com e una source di tipo JavaScript Website. Copia lo snippet analytics.js nel sito. Connetti una destination, per esempio Google Sheets o PostgreSQL how warehouse gratuito.

Verdetto: una source web più un warehouse gratuito batte qualsiasi setup senza destination verificabile.

I primi tre eventi

Tre chiamate coprono i casi fondamentali: associare un utente, registrare un’azione di business e tracciare la navigazione.

// Identify: associate anonymous user to known ID
analytics.identify('user_123', {
  email: '[email protected]',
  plan: 'pro',
  signup_date: '2024-01-15'
});

// Track: business event
analytics.track('Product Added to Cart', {
  product_id: 'SKU-456',
  product_name: 'Premium Hoodie',
  price: 49.99,
  quantity: 1,
  size: 'L'
});

// Page: navigation
analytics.page('Product Page', {
  name: 'Premium Hoodie',
  category: 'Apparel',
  url: '/products/premium-hoodie'
});

Ogni evento porta identificativo, proprietà tipate e contesto di pagina separato dal business.

Validazione e tracking plan

Prima di fidarti dei dati verifica che arrivino. Apri il Segment Debugger per vedere gli eventi in tempo reale. Controlla che raggiungano la destination e che tutte le proprietà siano presenti e ben tipate. Documenta su un foglio l’evento Product Added to Cart con tipi, fonte, metrica e owner. I tipi sono product_id string, price number e quantity int. A fine setup devi spuntare cinque punti: SDK caricato, tre eventi implementati, eventi visibili in debugger e destination, plan documentato e alert sul volume.

Verdetto: debugger plus destination verificata più scheda di plan valgono più di dieci eventi non documentati.

Una vista SQL per osservare il setup

La vista seguente crea una base settimanale per fonte e dispositivo per confrontare periodi e segmenti senza riscrivere la logica.

WITH base_events AS (
  SELECT
    user_id,
    account_id,
    event_type,
    event_time,
    DATE_TRUNC('week', event_time) AS week,
    source,
    device_type
  FROM events
  WHERE event_time >= CURRENT_DATE - INTERVAL '180 days'
    AND user_id IS NOT NULL
),
weekly_user_metrics AS (
  SELECT
    week,
    user_id,
    COALESCE(source, 'unknown') AS source,
    COALESCE(device_type, 'unknown') AS device_type,
    COUNT(*) AS total_events,
    COUNT(DISTINCT DATE(event_time)) AS active_days,
    COUNT(DISTINCT event_type) AS event_diversity,
    MAX(CASE WHEN event_type IN ('purchase', 'subscribe', 'activation') THEN 1 ELSE 0 END) AS reached_key_outcome
  FROM base_events
  GROUP BY week, user_id, source, device_type
)
SELECT
  week,
  source,
  device_type,
  COUNT(DISTINCT user_id) AS users,
  ROUND(AVG(active_days), 2) AS avg_active_days,
  ROUND(AVG(event_diversity), 2) AS avg_event_diversity,
  ROUND(AVG(reached_key_outcome) * 100, 2) AS key_outcome_rate
FROM weekly_user_metrics
GROUP BY week, source, device_type
ORDER BY week, source, device_type;

Serve a creare una superficie di osservazione con trend, segmenti e differenze tra canali.

Un controllo Python di stabilità

Una metrica utile resta stabile per decidere e sensibile per segnalare cambiamenti reali.

# df contiene: week, segment, users, key_outcome_rate
# key_outcome_rate espresso in percentuale, es. 12.4

df = df.sort_values(['segment', 'week']).copy()
df['previous_rate'] = df.groupby('segment')['key_outcome_rate'].shift(1)
df['wow_change_pp'] = df['key_outcome_rate'] - df['previous_rate']
df['rolling_mean'] = df.groupby('segment')['key_outcome_rate'].transform(
    lambda s: s.rolling(4, min_periods=2).mean()
)
df['rolling_std'] = df.groupby('segment')['key_outcome_rate'].transform(
    lambda s: s.rolling(4, min_periods=2).std()
)
df['z_score'] = (df['key_outcome_rate'] - df['rolling_mean']) / df['rolling_std']

anomalies = df[df['z_score'].abs() >= 2].sort_values('z_score')
print(anomalies[['week', 'segment', 'key_outcome_rate', 'wow_change_pp', 'z_score']])

In azienda questo controllo alimenta alert, review settimanali e retrospettive di prodotto.

Typical mistakes

L’errore più frequente è trattare il setup come sequenza di click invece che come strumento decisionale. Si pubblica un grafico senza decisione, una metrica senza baseline e una conclusione senza assunzione dichiarata. Poi si aggrega troppo presto e si nascondono segmenti opposti. Duplicati, tracking incompleto e timezone incoerenti producono conclusioni false. Infine, correlazione non è causalità.

Verdetto: tre eventi governati e monitorati battono trenta eventi senza owner.

Il caso che dà il nome al metodo

Segment nasce nel 2011 come startup di analytics e diventa lo standard per raccogliere eventi una volta sola e instradarli a decine di destinazioni. Nell’ottobre 2020 Twilio la acquisisce per 3,2 miliardi di dollari, la sua acquisizione più grande di sempre. La raccolta pulita alla fonte vale più di qualsiasi dashboard a valle. Il quickstart applica la stessa intuizione su scala minima: pochi eventi, nomi stabili e identità risolta dal primo giorno.

[SQL]Try it yourself

Write a query to count how many 'purchase' events each source (Google, Facebook, Direct, LinkedIn) generated. Order by descending number of purchases.

RunCtrl+Enter to runHintSolution

Controlla di aver capito

1. Quali tre chiamate coprono identità, business e navigazione nel setup minimo?

2. Come verifichi che gli eventi arrivino tipati alla destination?

3. Cosa deve contenere la scheda di tracking plan per ogni evento?

4. Quale alert configuri per accorgerti di un crollo di volume?