Analytics

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 public SDK accepts three cart-authorized interaction events. Crave records ORDER_PLACED server-side only after payment succeeds and the order is created, so clients cannot forge a conversion.

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`	Recorded automatically by Crave after order creation	Conversion

Track events with the SDK

import { storefront } from '@/lib/storefront';

// Track a storefront visit
await storefront.analyticsEvents.track(locationId, {
  cartId,
  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,
  },
});

curl -X POST "https://api.craveup.com/api/v1/storefront/locations/loc_123/analytics-events" \
  -H "Content-Type: application/json" \
  -H "X-Cart-Token: CART_CAPABILITY" \
  -H "Idempotency-Key: analytics_01" \
  -d '{
    "cartId": "cart_456",
    "eventType": "CHECKOUT_VIEW"
  }'

The API returns { "status": "accepted" } after it authorizes the cart and records or deduplicates the event.

Where to fire events

Place analytics calls at these points in your storefront:

// SCAN — fire after the ordering session creates or restores the cart
useEffect(() => {
  if (cartId) {
    storefront.analyticsEvents.track(locationId, { cartId, eventType: "SCAN" });
  }
}, [cartId]);

// 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]);
  // ...
}

// CHECKOUT_VIEW — fire on checkout page mount
useEffect(() => {
  if (cartId) {
    storefront.analyticsEvents.track(locationId, {
      cartId,
      eventType: "CHECKOUT_VIEW",
    });
  }
}, [cartId]);

Do not send ORDER_PLACED from a browser or mobile client. Poll the authoritative order result for the UI; the API writes the conversion event during server-side order creation.

Custom metadata

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

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:

import { storefront } from "@/lib/storefront";

type PublicFunnelEvent = "SCAN" | "CART_VIEW" | "CHECKOUT_VIEW";

const GA_EVENT_MAP: Record<PublicFunnelEvent, string> = {
  SCAN: "storefront_visit",
  CART_VIEW: "view_cart",
  CHECKOUT_VIEW: "begin_checkout",
};

export async function trackEvent(
  locationId: string,
  eventType: PublicFunnelEvent,
  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 ?? [],
    });
  }
}

If you also send a Google Analytics purchase event, do so only after checkout.getOrderResult() returns completed; do not forward that event to the Crave public analytics endpoint.

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 outside production first — confirm events appear in the intended Dashboard environment

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

Platform

Getting Started

Quickstarts

Implementation

AI

Ordering Flow

More Guides

Integrations

Reference

Event types

Track events with the SDK

Where to fire events

Custom metadata

Google Analytics integration

View analytics in the Dashboard

Best practices

Next steps

Order Tracking

Deployment

​Event types

​Track events with the SDK

​Where to fire events

​Custom metadata

​Google Analytics integration

​View analytics in the Dashboard

​Best practices

​Next steps

Order Tracking

Deployment

Event types

Track events with the SDK

Where to fire events

Custom metadata

Google Analytics integration

View analytics in the Dashboard

Best practices

Next steps