> ## Documentation Index
> Fetch the complete documentation index at: https://storekit.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tracciamento eventi

> Riferimento per gli eventi di comportamento dei clienti raccolti da storekit e come si integrano con piattaforme di analytics come Google Analytics, GTM e Meta Pixel.

storekit raccoglie eventi comportamentali per aiutarti a comprendere i percorsi dei clienti, ottimizzare le conversioni e alimentare integrazioni di marketing. Questa pagina spiega cosa tracciamo, come fluiscono i dati e come gli eventi si integrano con piattaforme di terze parti.

## Raccolta nativa degli eventi

storekit raccoglie automaticamente gli eventi su web e app native senza richiedere codice aggiuntivo.

### Eventi commerce principali

<AccordionGroup>
  <Accordion title="active_on_site">
    Attivato quando un cliente arriva sullo store.

    ```json theme={null}
    {
      "event": "active_on_site",
      "properties": {
        "accountId": "40586258-8a99-4651-b79f-0a1ab602a926",
        "id": 8709,
        "slug": "your-store"
      }
    }
    ```
  </Accordion>

  <Accordion title="menu_loaded">
    Attivato quando il menu è completamente caricato.

    ```json theme={null}
    {
      "event": "menu_loaded",
      "properties": {
        "menuId": 12345
      }
    }
    ```
  </Accordion>

  <Accordion title="viewed_product">
    Attivato quando un cliente apre il modale di un prodotto.

    ```json theme={null}
    {
      "event": "viewed_product",
      "properties": {
        "id": 98765,
        "name": "Flat White",
        "currency": "GBP",
        "price": 350,
        "image": "https://cdn.storekit.com/products/flat-white.jpg",
        "plu": "FW001",
        "sku": "SKU-FW-001"
      }
    }
    ```
  </Accordion>

  <Accordion title="add_to_cart">
    Attivato quando un articolo viene aggiunto al carrello.

    ```json theme={null}
    {
      "event": "add_to_cart",
      "properties": {
        "id": 98765,
        "name": "Flat White",
        "price": 400,
        "image": "https://cdn.storekit.com/products/flat-white.jpg",
        "modifiers": [
          {
            "id": 111,
            "name": "Oat Milk",
            "price": 50
          }
        ]
      }
    }
    ```
  </Accordion>

  <Accordion title="remove_from_cart">
    Attivato quando un articolo viene rimosso dal carrello.

    ```json theme={null}
    {
      "event": "remove_from_cart",
      "properties": {
        "id": 98765,
        "name": "Flat White",
        "price": 400,
        "image": "https://cdn.storekit.com/products/flat-white.jpg",
        "modifiers": []
      }
    }
    ```
  </Accordion>

  <Accordion title="started_checkout">
    Attivato quando il cliente apre la schermata di checkout.

    ```json theme={null}
    {
      "event": "started_checkout",
      "properties": {
        "currency": "GBP",
        "items": [
          {
            "id": 98765,
            "name": "Flat White",
            "price": 400,
            "quantity": 2,
            "modifiers": []
          }
        ],
        "venueSlug": "your-store",
        "value": 8.00
      }
    }
    ```
  </Accordion>

  <Accordion title="order_completed">
    Attivato quando il pagamento è confermato e l'ordine è effettuato.

    ```json theme={null}
    {
      "event": "order_completed",
      "properties": {
        "orderId": "ord_789xyz",
        "total": 12.50,
        "currency": "GBP",
        "venueSlug": "your-store",
        "order": {
          "items": [...],
          "fulfillmentMethod": "delivery",
          "customer": {...}
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

### Eventi di ricerca e scoperta

<AccordionGroup>
  <Accordion title="products_searched">
    Attivato quando un cliente effettua una ricerca (con debounce di 1 secondo).

    ```json theme={null}
    {
      "event": "products_searched",
      "properties": {
        "query": "coffee",
        "resultCount": 12
      }
    }
    ```
  </Accordion>

  <Accordion title="cross_sell_modal_view">
    Attivato quando viene mostrato il modale di upsell/cross-sell.

    ```json theme={null}
    {
      "event": "cross_sell_modal_view",
      "properties": {
        "productCount": 4,
        "crossSellType": "product"
      }
    }
    ```

    `crossSellType` è `"product"` o `"category"` a seconda della configurazione.
  </Accordion>
</AccordionGroup>

### Eventi sconto

<AccordionGroup>
  <Accordion title="discount_entered">
    Attivato quando un cliente invia un codice sconto.

    ```json theme={null}
    {
      "event": "discount_entered",
      "properties": {
        "code": "SUMMER20"
      }
    }
    ```
  </Accordion>

  <Accordion title="discount_applied">
    Attivato quando un codice sconto viene applicato con successo.

    ```json theme={null}
    {
      "event": "discount_applied",
      "properties": {
        "discount_id": 456,
        "discount_name": "Summer Sale",
        "discount_amount": 500,
        "discount_type": "percentage"
      }
    }
    ```
  </Accordion>

  <Accordion title="discount_denied">
    Attivato quando un codice sconto viene rifiutato.

    ```json theme={null}
    {
      "event": "discount_denied",
      "properties": {
        "discount_code": "EXPIRED10",
        "reason": "Code has expired",
        "status_code": 400
      }
    }
    ```
  </Accordion>
</AccordionGroup>

### Eventi offerte promozionali

<AccordionGroup>
  <Accordion title="viewed_offer">
    Attivato quando un'offerta promozionale diventa visibile.

    ```json theme={null}
    {
      "event": "viewed_offer",
      "properties": {
        "offerId": 123,
        "linkId": "link_abc",
        "type": "banner",
        "value": "20% off"
      }
    }
    ```
  </Accordion>

  <Accordion title="click_offer">
    Attivato quando un cliente clicca su un'offerta promozionale.

    ```json theme={null}
    {
      "event": "click_offer",
      "properties": {
        "offerId": 123,
        "linkId": "link_abc",
        "type": "banner",
        "value": "20% off"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

### Eventi Stories

<AccordionGroup>
  <Accordion title="story_viewer_opened">
    Attivato quando un cliente apre il visualizzatore di storie.

    ```json theme={null}
    {
      "event": "story_viewer_opened",
      "properties": {
        "storyId": 789,
        "storyIndex": 0,
        "storyTitle": "New Summer Menu",
        "totalStories": 5,
        "source": "menu_page"
      }
    }
    ```
  </Accordion>

  <Accordion title="story_viewed">
    Attivato quando una pagina di una storia viene visualizzata.

    ```json theme={null}
    {
      "event": "story_viewed",
      "properties": {
        "storyId": 789,
        "storyTitle": "New Summer Menu",
        "pageIndex": 2,
        "totalPages": 4,
        "hasVideo": true,
        "hasCta": true
      }
    }
    ```
  </Accordion>

  <Accordion title="story_navigation">
    Attivato quando un cliente naviga tra le pagine di una storia.

    ```json theme={null}
    {
      "event": "story_navigation",
      "properties": {
        "storyId": 789,
        "fromPage": 1,
        "toPage": 2,
        "direction": "forward",
        "method": "tap"
      }
    }
    ```
  </Accordion>

  <Accordion title="story_cta_clicked">
    Attivato quando un cliente clicca una CTA all'interno di una storia.

    ```json theme={null}
    {
      "event": "story_cta_clicked",
      "properties": {
        "storyId": 789,
        "pageIndex": 2,
        "ctaType": "product",
        "ctaLabel": "Order Now",
        "ctaData": { "productId": 456 },
        "videoProgressPercent": 75
      }
    }
    ```
  </Accordion>

  <Accordion title="story_completed">
    Attivato quando un cliente visualizza tutte le pagine di una storia.

    ```json theme={null}
    {
      "event": "story_completed",
      "properties": {
        "storyId": 789,
        "storyTitle": "New Summer Menu",
        "totalPages": 4,
        "timeSpentSeconds": 32
      }
    }
    ```
  </Accordion>

  <Accordion title="story_viewer_closed">
    Attivato quando il visualizzatore di storie viene chiuso.

    ```json theme={null}
    {
      "event": "story_viewer_closed",
      "properties": {
        "storyId": 789,
        "pageIndex": 2,
        "totalStoriesViewed": 3,
        "totalPagesViewed": 8,
        "timeSpentSeconds": 45,
        "closeMethod": "swipe_down"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

### Eventi di sperimentazione

<AccordionGroup>
  <Accordion title="viewed_experiment">
    Attivato quando un cliente viene esposto a una variante di test A/B.

    ```json theme={null}
    {
      "event": "viewed_experiment",
      "properties": {
        "experimentId": "checkout-flow-v2",
        "variationId": 1,
        "venueId": 8709,
        "accountId": "40586258-8a99-4651-b79f-0a1ab602a926",
        "venueSlug": "your-store"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Risoluzione dell'item ID

Quando invia eventi alle piattaforme di analytics, storekit risolve l'`item_id` usando la seguente priorità:

1. **PLU** - Codice di lookup del punto vendita (preferito per store connessi a POS)
2. **SKU** - Stock keeping unit
3. **POS ID** - Identificatore del sistema POS esterno
4. **ID** - ID prodotto interno di storekit (fallback)

Questo assicura che i tuoi dati di analytics usino gli stessi identificatori del tuo sistema POS per reporting e attribuzione accurati.

```
item_id = product.plu || product.sku || product.posId || product.id
```

<Tip>
  Per i migliori risultati, assicurati che i tuoi prodotti abbiano codici PLU configurati se stai usando un'integrazione POS. Questo mantiene i tuoi dati di analytics coerenti con i report del tuo POS.
</Tip>

## Integrazioni con le piattaforme

storekit inoltra gli eventi a piattaforme di terze parti nel loro formato nativo. Gli eventi vengono trasformati automaticamente — non è richiesto alcun mapping.

### Meta (Facebook) Pixel

Gli eventi vengono inviati all'API Pixel di Meta. Un evento `PageView` viene attivato automaticamente all'inizializzazione.

<AccordionGroup>
  <Accordion title="AddToCart">
    Attivato da `add_to_cart`

    ```json theme={null}
    {
      "content_ids": [98765],
      "content_name": "Flat White",
      "currency": "GBP",
      "value": "4.00",
      "content_type": "product"
    }
    ```
  </Accordion>

  <Accordion title="InitiateCheckout">
    Attivato da `started_checkout`

    ```json theme={null}
    {
      "currency": "GBP",
      "value": 8.00
    }
    ```
  </Accordion>

  <Accordion title="Purchase">
    Attivato da `order_completed`

    ```json theme={null}
    {
      "currency": "GBP",
      "value": "12.50",
      "content_type": "product"
    }
    ```
  </Accordion>
</AccordionGroup>

<Info>
  Meta Pixel fornisce un'attribuzione migliore rispetto ai pixel solo del browser, soprattutto con i cambiamenti sulla privacy di iOS e gli ad blocker.
</Info>

### Google Analytics 4 / Google Tag Manager

Gli eventi vengono inviati al `dataLayer` seguendo lo schema e-commerce di GA4.

<AccordionGroup>
  <Accordion title="active_on_site">
    ```json theme={null}
    {
      "event": "active_on_site",
      "userId": null,
      "sessionId": null,
      "pagePath": null
    }
    ```
  </Accordion>

  <Accordion title="view_item">
    Attivato da `viewed_product`

    ```json theme={null}
    {
      "event": "view_item",
      "currency": "GBP",
      "value": 3.50,
      "items": [
        {
          "item_id": "FW001",
          "item_name": "Flat White"
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="add_to_cart">
    ```json theme={null}
    {
      "event": "add_to_cart",
      "value": 4.00,
      "currency": "GBP",
      "items": [
        {
          "item_name": "Flat White",
          "item_id": "FW001",
          "price": 4.00,
          "quantity": 1
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="begin_checkout">
    Attivato da `started_checkout`

    ```json theme={null}
    {
      "event": "begin_checkout",
      "value": 8.00,
      "currency": "GBP",
      "items": [
        {
          "item_name": "Flat White",
          "affiliation": "your-store",
          "item_id": "FW001",
          "price": 4.00,
          "quantity": 2,
          "category": "Hot Drinks",
          "item_variant": "Oat Milk"
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="purchase">
    Attivato da `order_completed`

    ```json theme={null}
    {
      "event": "purchase",
      "transaction_id": "ord_789xyz",
      "value": 12.50,
      "currency": "GBP",
      "items": [
        {
          "item_name": "Flat White",
          "affiliation": "your-store",
          "item_id": "FW001",
          "price": 4.00,
          "quantity": 2,
          "category": "Hot Drinks",
          "item_variant": "Oat Milk"
        }
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

### Klaviyo

Gli eventi vengono inviati a Klaviyo per l'automazione di email marketing. L'identità del cliente viene collegata tramite email quando disponibile usando `klaviyo.identify()`.

<AccordionGroup>
  <Accordion title="Active on Site">
    Attivato da `active_on_site`

    ```json theme={null}
    {
      "AccountId": "40586258-8a99-4651-b79f-0a1ab602a926",
      "VenueId": 8709,
      "VenueSlug": "your-store"
    }
    ```
  </Accordion>

  <Accordion title="Viewed Product">
    Attivato da `viewed_product`

    ```json theme={null}
    {
      "ProductId": 98765,
      "ProductName": "Flat White",
      "ProductPrice": 350,
      "ProductImage": "https://cdn.storekit.com/products/flat-white.jpg"
    }
    ```
  </Accordion>

  <Accordion title="Added to Cart">
    Attivato da `add_to_cart`

    ```json theme={null}
    {
      "ProductId": 98765,
      "ProductName": "Flat White",
      "ProductPrice": 400,
      "ProductImage": "https://cdn.storekit.com/products/flat-white.jpg"
    }
    ```
  </Accordion>

  <Accordion title="Started Checkout">
    Attivato da `started_checkout`

    ```json theme={null}
    {
      "Currency": "GBP",
      "Value": 8.00
    }
    ```
  </Accordion>
</AccordionGroup>

### Raccolta eventi first-party

Per i clienti che vogliono la piena proprietà dei dati, storekit può inviare gli eventi direttamente al tuo data warehouse. Tutti gli eventi includono automaticamente le proprietà del contesto base.

**Contesto base (incluso in tutti gli eventi):**

```json theme={null}
{
  "account_id": "40586258-8a99-4651-b79f-0a1ab602a926",
  "venue_id": 8709,
  "venue_slug": "your-store"
}
```

<AccordionGroup>
  <Accordion title="venue_loaded">
    Attivato da `active_on_site`. Identifica anche l'utente.

    ```json theme={null}
    {
      "event": "venue_loaded"
    }
    ```
  </Accordion>

  <Accordion title="menu_loaded">
    ```json theme={null}
    {
      "event": "menu_loaded",
      "menu_id": 12345
    }
    ```
  </Accordion>

  <Accordion title="product_modal_view">
    Attivato da `viewed_product`

    ```json theme={null}
    {
      "event": "product_modal_view",
      "product_id": 98765,
      "product_name": "Flat White",
      "product_price": 350,
      "product_image": "https://cdn.storekit.com/products/flat-white.jpg",
      "product_plu": "FW001"
    }
    ```
  </Accordion>

  <Accordion title="add_to_cart">
    ```json theme={null}
    {
      "event": "add_to_cart",
      "product_id": 98765,
      "product_name": "Flat White",
      "product_price": 400,
      "product_image": "https://cdn.storekit.com/products/flat-white.jpg",
      "product_quantity": 1,
      "product_plu": "FW001",
      "add_to_cart_source": null
    }
    ```
  </Accordion>

  <Accordion title="remove_from_cart">
    ```json theme={null}
    {
      "event": "remove_from_cart",
      "product_id": 98765,
      "product_name": "Flat White",
      "product_price": 400,
      "product_image": "https://cdn.storekit.com/products/flat-white.jpg",
      "product_quantity": 1,
      "product_plu": "FW001"
    }
    ```
  </Accordion>

  <Accordion title="order_completed">
    ```json theme={null}
    {
      "event": "order_completed",
      "orderId": "ord_789xyz",
      "total": 12.50,
      "currency": "GBP"
    }
    ```
  </Accordion>

  <Accordion title="cross_sell_modal_view">
    ```json theme={null}
    {
      "event": "cross_sell_modal_view",
      "product_count": 4,
      "cross_sell_type": "product"
    }
    ```
  </Accordion>

  <Accordion title="viewed_offer">
    ```json theme={null}
    {
      "event": "viewed_offer",
      "offer_id": 123,
      "link_id": "link_abc",
      "type": "banner",
      "value": "20% off"
    }
    ```
  </Accordion>

  <Accordion title="clicked_offer">
    Attivato da `click_offer`

    ```json theme={null}
    {
      "event": "clicked_offer",
      "offer_id": 123,
      "link_id": "link_abc",
      "type": "banner",
      "value": "20% off"
    }
    ```
  </Accordion>

  <Accordion title="products_searched">
    ```json theme={null}
    {
      "event": "products_searched",
      "query": "coffee",
      "result_count": 12
    }
    ```
  </Accordion>

  <Accordion title="experiment_viewed">
    Attivato da `viewed_experiment`

    ```json theme={null}
    {
      "event": "experiment_viewed",
      "experiment_key": "checkout-flow-v2",
      "variation_id": 1,
      "account_id": "40586258-8a99-4651-b79f-0a1ab602a926",
      "venue_id": 8709,
      "venue_slug": "your-store"
    }
    ```
  </Accordion>

  <Accordion title="story_viewer_opened">
    ```json theme={null}
    {
      "event": "story_viewer_opened",
      "story_id": 789,
      "story_index": 0,
      "story_title": "New Summer Menu",
      "total_stories": 5,
      "source": "menu_page"
    }
    ```
  </Accordion>

  <Accordion title="story_viewed">
    ```json theme={null}
    {
      "event": "story_viewed",
      "story_id": 789,
      "story_title": "New Summer Menu",
      "page_index": 2,
      "total_pages": 4,
      "has_video": true,
      "has_cta": true
    }
    ```
  </Accordion>

  <Accordion title="story_navigation">
    ```json theme={null}
    {
      "event": "story_navigation",
      "story_id": 789,
      "from_page": 1,
      "to_page": 2,
      "direction": "forward",
      "method": "tap"
    }
    ```
  </Accordion>

  <Accordion title="story_cta_clicked">
    ```json theme={null}
    {
      "event": "story_cta_clicked",
      "story_id": 789,
      "page_index": 2,
      "cta_type": "product",
      "cta_label": "Order Now",
      "cta_data": { "productId": 456 },
      "video_progress_percent": 75
    }
    ```
  </Accordion>

  <Accordion title="story_completed">
    ```json theme={null}
    {
      "event": "story_completed",
      "story_id": 789,
      "story_title": "New Summer Menu",
      "total_pages": 4,
      "time_spent_seconds": 32
    }
    ```
  </Accordion>

  <Accordion title="story_viewer_closed">
    ```json theme={null}
    {
      "event": "story_viewer_closed",
      "story_id": 789,
      "page_index": 2,
      "total_stories_viewed": 3,
      "total_pages_viewed": 8,
      "time_spent_seconds": 45,
      "close_method": "swipe_down"
    }
    ```
  </Accordion>
</AccordionGroup>

## Configurazione

### Abilitare le integrazioni

1. Vai su **Settings > Integrations** nella tua dashboard
2. Seleziona la piattaforma di analytics
3. Inserisci l'ID pixel/measurement o la chiave API:
   * **Google Tag Manager**: ID del container (GTM-XXXXX)
   * **Meta Pixel**: ID pixel
   * **Klaviyo**: chiave API
4. Gli eventi iniziano a fluire immediatamente

### Integrazioni chat supportate

Il sistema di analytics inizializza anche i widget chat quando configurati:

* Front Chat
* Superchat
* Tawk.to
* Intercom

## Risoluzione dei problemi

<AccordionGroup>
  <Accordion title="Gli eventi non compaiono in Meta/Google">
    Verifica che il tuo ID pixel sia corretto e che l'integrazione sia abilitata. Gli eventi lato server possono impiegare fino a 24 ore per comparire in alcune dashboard a causa dei ritardi di elaborazione della piattaforma.
  </Accordion>

  <Accordion title="I valori di ricavo non corrispondono">
    Assicurati che la tua piattaforma di analytics sia configurata per la valuta corretta. storekit invia i valori nella valuta locale dello store. Nota che i prezzi negli eventi sono in unità minori (pence/centesimi) se non diversamente specificato.
  </Accordion>

  <Accordion title="Identità utente mancante">
    I visitatori anonimi vengono tracciati con un ID basato sul dispositivo. L'identità dell'utente viene associata una volta che fornisce la sua email al checkout.
  </Accordion>

  <Accordion title="Modalità Store Designer">
    L'analytics è disabilitato quando si visualizza lo store in modalità Store Designer per evitare di contaminare i tuoi dati con traffico di test.
  </Accordion>
</AccordionGroup>


## Related topics

- [Importazione massiva di sconti](/docs/it/guides/discounts/bulk-import.md)
- [Eventi webhook](/docs/it/developers/webhooks/webhook-events.md)
- [Google Tag Manager e Meta Pixel](/docs/it/guides/integrations/marketing/google-tag-manager.md)
- [Tracciamento scorte condivise](/docs/it/guides/tips-tricks/shared-inventory.md)
- [Configurazione dei webhook](/docs/it/developers/webhooks/setting-up-webhooks.md)