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

# Analytics

> Track storefront events and measure ordering funnel performance.

The Crave SDK includes a built-in analytics module that tracks key events across the ordering funnel. Use it to measure conversion rates, identify drop-off points, and understand customer behavior.

## Event types

The SDK supports four funnel events:

| Event           | When to fire                                          | Funnel stage  |
| --------------- | ----------------------------------------------------- | ------------- |
| `SCAN`          | Customer scans a QR code or visits the storefront URL | Entry         |
| `CART_VIEW`     | Customer opens the cart panel                         | Consideration |
| `CHECKOUT_VIEW` | Customer reaches the checkout page                    | Intent        |
| `ORDER_PLACED`  | Payment succeeds and order is created                 | Conversion    |

## Track events with the SDK

<CodeGroup>
  ```ts SDK theme={null}
  import { storefront } from '@/lib/storefront';

  // Track a storefront visit
  await storefront.analyticsEvents.track(locationId, {
    eventType: 'SCAN',
  });

  // Track cart view with metadata
  await storefront.analyticsEvents.track(locationId, {
    cartId,
    eventType: 'CART_VIEW',
    metadata: {
      itemCount: cart.totalQuantity,
      total: cart.orderTotalWithServiceFee,
    },
  });

  // Track checkout view
  await storefront.analyticsEvents.track(locationId, {
    cartId,
    eventType: 'CHECKOUT_VIEW',
    metadata: {
      fulfillmentMethod: cart.fulfilmentMethod,
    },
  });

  // Track order placed
  await storefront.analyticsEvents.track(locationId, {
    cartId,
    eventType: 'ORDER_PLACED',
    metadata: {
      total: cart.orderTotalWithServiceFee,
      currency: cart.currency,
      itemCount: cart.totalQuantity,
    },
  });
  ```

  ```bash REST theme={null}
  curl -X POST "https://api.craveup.com/api/v1/locations/loc_123/analytics-events" \
    -H "X-API-Key: $CRAVEUP_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "cartId": "cart_456",
      "eventType": "ORDER_PLACED",
      "metadata": { "total": "27.98", "currency": "usd" }
    }'
  ```
</CodeGroup>

The API returns `{ "status": "accepted" }` on success. Events are processed asynchronously.

## Where to fire events

Place analytics calls at these points in your storefront:

```tsx filename="src/app/page.tsx" theme={null}
// SCAN — fire on storefront load
useEffect(() => {
  storefront.analyticsEvents.track(locationId, { eventType: 'SCAN' });
}, []);
```

```tsx filename="src/components/CartPanel.tsx" theme={null}
// CART_VIEW — fire when cart panel opens
function CartPanel({ isOpen }: { isOpen: boolean }) {
  useEffect(() => {
    if (isOpen && cartId) {
      storefront.analyticsEvents.track(locationId, {
        cartId,
        eventType: 'CART_VIEW',
      });
    }
  }, [isOpen]);
  // ...
}
```

```tsx filename="src/app/checkout/page.tsx" theme={null}
// CHECKOUT_VIEW — fire on checkout page mount
useEffect(() => {
  if (cartId) {
    storefront.analyticsEvents.track(locationId, {
      cartId,
      eventType: 'CHECKOUT_VIEW',
    });
  }
}, [cartId]);
```

```tsx filename="src/app/order/confirmation/page.tsx" theme={null}
// ORDER_PLACED — fire on confirmation page
useEffect(() => {
  if (cartId) {
    storefront.analyticsEvents.track(locationId, {
      cartId,
      eventType: 'ORDER_PLACED',
      metadata: { total: cart.orderTotalWithServiceFee },
    });
  }
}, [cartId]);
```

## Custom metadata

The `metadata` field accepts any key-value pairs. Use it to attach context to events:

```ts theme={null}
await storefront.analyticsEvents.track(locationId, {
  cartId,
  eventType: 'CART_VIEW',
  metadata: {
    source: 'qr_code',
    campaignId: 'summer_promo_2025',
    deviceType: 'mobile',
    itemCount: cart.totalQuantity,
    total: cart.orderTotalWithServiceFee,
  },
});
```

## Google Analytics integration

Forward Crave events to Google Analytics for unified reporting:

```ts filename="src/lib/analytics.ts" theme={null}
import { storefront } from '@/lib/storefront';

type FunnelEvent = 'SCAN' | 'CART_VIEW' | 'CHECKOUT_VIEW' | 'ORDER_PLACED';

const GA_EVENT_MAP: Record<FunnelEvent, string> = {
  SCAN: 'storefront_visit',
  CART_VIEW: 'view_cart',
  CHECKOUT_VIEW: 'begin_checkout',
  ORDER_PLACED: 'purchase',
};

export async function trackEvent(
  locationId: string,
  eventType: FunnelEvent,
  cartId?: string,
  metadata?: Record<string, unknown>
) {
  // Send to Crave
  await storefront.analyticsEvents.track(locationId, {
    cartId,
    eventType,
    metadata,
  });

  // Forward to Google Analytics
  if (typeof window !== 'undefined' && window.gtag) {
    window.gtag('event', GA_EVENT_MAP[eventType], {
      currency: metadata?.currency ?? 'USD',
      value: metadata?.total ?? 0,
      items: metadata?.items ?? [],
    });
  }
}
```

## View analytics in the Dashboard

Analytics data is available in the Crave Dashboard under **Analytics > Storefront**. The dashboard shows:

* **Funnel visualization** — conversion rates between each stage
* **Event timeline** — raw event stream with metadata
* **Location comparison** — performance across multiple locations
* **Time-based trends** — daily, weekly, and monthly patterns

## Best practices

* **Fire events once** — deduplicate using a ref or flag to prevent double-counting on re-renders
* **Don't block the UI** — fire analytics calls without `await` to keep the interface responsive
* **Include metadata** — the more context you attach, the more useful your Dashboard reports
* **Test in test mode** — test API keys still record analytics events, visible in the Dashboard

```ts theme={null}
// Fire-and-forget pattern (don't await)
storefront.analyticsEvents.track(locationId, {
  cartId,
  eventType: 'CART_VIEW',
}).catch(console.error);
```

## Next steps

<CardGroup cols={2}>
  <Card title="Order Tracking" icon="map-pin" href="/guides/order-tracking">
    Track order status after checkout.
  </Card>

  <Card title="Deployment" icon="rocket" href="/guides/deployment">
    Deploy your storefront and go live.
  </Card>
</CardGroup>