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

# Tracking Events

> Send analytics events for widget usage and conversion tracking

Send batched analytics events to track widget usage and conversion funnels. Max 50 events per batch. Tracking failures never block user flow.

## Request

<ParamField body="events" type="array" required>
  Array of event objects. Each contains:

  * `event` (string, required): Event name (e.g. `widget:button_click`)
  * `properties` (object, optional): Custom properties
  * `timestamp` (string, required): ISO 8601 timestamp
  * `$insert_id` (string, required): Unique ID for deduplication
</ParamField>

<ParamField body="context" type="object" required>
  Shared context for all events in the batch: page URL, viewport size, user agent, `session_id` / `$pageview_id`, and
  Genlook-specific fields (`anonymous_id` (`anon_*`), `widget_version` (`wv_*`), `widget_enabled`, `product_id`,
  `variant_id`).
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://your-store.myshopify.com/apps/proxy_genlook-x/public/tracking/events" \
    -H "Content-Type: application/json" \
    -d '{
      "events": [
        {
          "event": "widget:button_click",
          "properties": { "product_id": "gid://shopify/Product/456" },
          "timestamp": "2024-01-15T10:30:00Z",
          "$insert_id": "event_123"
        }
      ],
      "context": {
        "$current_url": "https://yourstore.com/products/tshirt",
        "$host": "yourstore.com",
        "session_id": "sess_abc123",
        "anonymous_id": "anon_550e8400-e29b-41d4-a716-446655440000",
        "widget_version": "custom",
        "widget_enabled": true,
        "product_id": "gid://shopify/Product/456",
        "variant_id": null
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  await fetch("/apps/proxy_genlook-x/public/tracking/events", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      events: [
        {
          event: "widget:button_click",
          properties: { product_id: "gid://shopify/Product/456" },
          timestamp: new Date().toISOString(),
          $insert_id: `evt_${Date.now()}_${Math.random()}`,
        },
      ],
      context: {
        $current_url: location.href,
        $host: location.host,
        session_id: getSessionId(),
        anonymous_id: getAnonymousId(),
        widget_version: WIDGET_VERSION,
        widget_enabled: true,
        product_id: getProductId(),
        variant_id: getVariantId(),
      },
    }),
  });
  ```
</RequestExample>

## Event Types

| Event                        | Description                |
| ---------------------------- | -------------------------- |
| `widget:button_click`        | Widget button clicked      |
| `widget:image_upload`        | User uploaded an image     |
| `widget:generation_start`    | Generation started         |
| `widget:result_view`         | Result displayed           |
| `widget:share_clicked`       | Share button clicked       |
| `widget:download_clicked`    | Download button clicked    |
| `widget:add_to_cart_clicked` | Add to cart from widget    |
| `widget:add_to_cart`         | Add to cart succeeded      |
| `widget:email_collected`     | Email collected            |
| `product_page:page_view`     | Product page viewed        |
| `product_page:cart_add`      | Cart add from product page |

Event names follow `category:action` format with snake\_case.

## Response

For non-Shopify integrations (WooCommerce, WordPress, etc.), use the store API route instead:

```
POST /store/v1/public/tracking/events
```

Authenticate with `x-store-api-key`. Optional identity headers for logged-in shoppers:

* `x-genlook-customer-id`: platform customer id
* `x-genlook-customer-email`: customer email

The request body is identical to the Shopify proxy route above.

<ResponseField name="success" type="boolean" required>
  Whether the batch was processed.
</ResponseField>

<ResponseExample>
  ```json Success theme={null}
  {
    "success": true
  }
  ```
</ResponseExample>