Events

Handle user actions and order lifecycle through callback functions. The event system is consistent across all platforms.

Cross-Platform Consistency

Event names and payloads are identical across Web, iOS, and Android. Only the callback mechanism differs (callbacks vs delegates vs listeners). See SDK Reference for platform-specific type definitions.

Handling Events

Pass callback functions in the configuration:

import { MarketfrontClient } from '@gett/marketfront';

// Get session token from your backend
const { sessionToken } = await fetch('/api/gett/session').then(r => r.json());

const client = new MarketfrontClient({
  sessionToken,

  // Handle events via callbacks
  onReady: () => console.log('Ready'),
  onOrderComplete: (order) => {
    console.log('Order placed:', order.id);
  },
});

client.mount('#container');

Event Reference

Lifecycle Events

onReady

Called when the marketfront has fully initialized and is ready for interaction.

const client = new MarketfrontClient({
  sessionToken,
  onReady: () => {
    console.log('Marketfront ready');
    hideLoadingSpinner();
  },
});

Payload: None

onError

Called when an error occurs.

const client = new MarketfrontClient({
  sessionToken,
  onError: (error) => {
    console.error('Error:', error.message);
    showErrorNotification(error.message);
  },
});

Payload:

interface MarketfrontError {
  code: string;           // Error code (e.g., "INIT_FAILED")
  message: string;        // Human-readable message
  details?: unknown;      // Additional context
}

Store Events

onStoreSelected

Called when the user selects a store to order from.

const client = new MarketfrontClient({
  sessionToken,
  onStoreSelected: (store) => {
    console.log('Selected:', store.name);
    trackStoreView(store.storeId);
  },
});

Payload:

interface StoreEvent {
  storeId: string;
  name: string;
  distance?: number;           // In miles
  estimatedDeliveryTime?: number; // In minutes
}

Cart Events

onItemAdded

Called when an item is added to the cart.

const client = new MarketfrontClient({
  sessionToken,
  onItemAdded: (item) => {
    console.log(`Added: ${item.name} ($${item.price})`);
    trackAddToCart(item);
  },
});

Payload:

interface ItemAddedEvent {
  lineItemId: string;
  itemId: string;
  name: string;
  quantity: number;
  price: number;
  modifiers?: Array<{
    name: string;
    price: number;
  }>;
}

Checkout Events

onCheckoutStarted

Called when the user begins the checkout process.

const client = new MarketfrontClient({
  sessionToken,
  onCheckoutStarted: (checkout) => {
    trackCheckoutStart(checkout.subtotal, checkout.itemCount);
  },
});

Payload:

interface CheckoutStartedEvent {
  storeId: string;
  itemCount: number;
  subtotal: number;
}

Order Events

onOrderComplete

Called when the order is successfully placed. This is the most important event for most integrations.

const client = new MarketfrontClient({
  sessionToken,
  onOrderComplete: (order) => {
    console.log('Order placed:', order.id);

    // Track purchase
    trackPurchase(order);

    // Navigate to confirmation
    router.push(`/order/${order.id}`);
  },
});

Payload:

interface Order {
  id: string;
  storeId: string;
  storeName: string;
  total: number;
  fulfillmentType: 'DeliveryByMerchant' | 'PickUp';
  estimatedTime?: string; // e.g., "45-55 min"
  items: Array<{
    name: string;
    quantity: number;
    price: number;
  }>;
}

onOrderFailed

Called when order placement fails.

const client = new MarketfrontClient({
  sessionToken,
  onOrderFailed: (error) => {
    console.error('Order failed:', error.reason);
    showErrorMessage(error.message);
  },
});

Payload:

interface OrderFailedEvent {
  reason: string;   // Error code (e.g., "PAYMENT_FAILED")
  message: string;  // Human-readable message
}

Analytics Integration

Use event callbacks to track user behavior:

import { MarketfrontClient } from '@gett/marketfront';

const client = new MarketfrontClient({
  sessionToken,

  // Google Analytics 4 integration
  onItemAdded: (item) => {
    gtag('event', 'add_to_cart', {
      currency: 'USD',
      value: item.price,
      items: [{
        item_id: item.itemId,
        item_name: item.name,
        price: item.price,
        quantity: item.quantity,
      }],
    });
  },

  onCheckoutStarted: (checkout) => {
    gtag('event', 'begin_checkout', {
      currency: 'USD',
      value: checkout.subtotal,
    });
  },

  onOrderComplete: (order) => {
    gtag('event', 'purchase', {
      transaction_id: order.id,
      value: order.total,
      currency: 'USD',
      items: order.items.map(item => ({
        item_name: item.name,
        price: item.price,
        quantity: item.quantity,
      })),
    });
  },
});

Framework Examples

React

import { useEffect, useRef, useCallback } from 'react';
import { useNavigate } from 'react-router-dom';
import { MarketfrontClient, Order } from '@gett/marketfront';

function OrderPage() {
  const containerRef = useRef<HTMLDivElement>(null);
  const clientRef = useRef<MarketfrontClient>();
  const navigate = useNavigate();

  const handleOrderComplete = useCallback((order: Order) => {
    // Track analytics
    trackPurchase(order);

    // Navigate to confirmation
    navigate(`/order/${order.id}`);
  }, [navigate]);

  useEffect(() => {
    clientRef.current = new MarketfrontClient({
      sessionToken,
      onReady: () => console.log('Ready'),
      onOrderComplete: handleOrderComplete,
      onError: (error) => showToast(error.message),
    });

    clientRef.current.mount(containerRef.current!);

    return () => {
      clientRef.current?.unmount();
    };
  }, [handleOrderComplete]);

  return <div ref={containerRef} style={{ minHeight: 600 }} />;
}

Vue

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';
import { useRouter } from 'vue-router';
import { MarketfrontClient, Order } from '@gett/marketfront';

const router = useRouter();
const container = ref<HTMLElement>();
let client: MarketfrontClient;

function handleOrderComplete(order: Order) {
  router.push(`/order/${order.id}`);
}

onMounted(() => {
  client = new MarketfrontClient({
    sessionToken,
    onReady: () => console.log('Ready'),
    onOrderComplete: handleOrderComplete,
    onError: (error) => console.error(error),
  });

  client.mount(container.value!);
});

onUnmounted(() => {
  client?.unmount();
});
</script>

<template>
  <div ref="container" style="min-height: 600px" />
</template>

Angular

import { Component, ElementRef, OnDestroy, OnInit, ViewChild } from '@angular/core';
import { Router } from '@angular/router';
import { MarketfrontClient, Order } from '@gett/marketfront';

@Component({
  selector: 'app-order',
  template: '<div #container style="min-height: 600px"></div>',
})
export class OrderComponent implements OnInit, OnDestroy {
  @ViewChild('container', { static: true }) container!: ElementRef;
  private client?: MarketfrontClient;

  constructor(private router: Router) {}

  ngOnInit() {
    this.client = new MarketfrontClient({
      sessionToken,
      onReady: () => console.log('Ready'),
      onOrderComplete: (order: Order) => {
        this.router.navigate(['/order', order.id]);
      },
      onError: (error) => {
        console.error('Marketfront error:', error);
      },
    });

    this.client.mount(this.container.nativeElement);
  }

  ngOnDestroy() {
    this.client?.unmount();
  }
}

Complete Event Handler Example

import { MarketfrontClient } from '@gett/marketfront';

const client = new MarketfrontClient({
  sessionToken,

  // Lifecycle
  onReady: () => {
    console.log('Marketfront initialized');
    hideLoadingSpinner();
  },
  onError: (error) => {
    console.error(`[${error.code}] ${error.message}`);
    showErrorNotification(error.message);
  },

  // Store
  onStoreSelected: (store) => {
    console.log('Store selected:', store.name);
    analytics.track('store_viewed', { storeId: store.storeId });
  },

  // Cart
  onItemAdded: (item) => {
    analytics.track('add_to_cart', item);
  },

  // Checkout
  onCheckoutStarted: (checkout) => {
    analytics.track('checkout_started', {
      subtotal: checkout.subtotal,
      itemCount: checkout.itemCount,
    });
  },

  // Order
  onOrderComplete: (order) => {
    analytics.track('purchase', {
      orderId: order.id,
      total: order.total,
    });
    router.push(`/order/${order.id}`);
  },
  onOrderFailed: (error) => {
    analytics.track('order_failed', { reason: error.reason });
    showErrorModal(error.message);
  },
});

client.mount('#order-container');

Next Steps

• Sessions — Session creation and consumer context
• PCI Compliance — Payment security