Skip to content

Integration patterns

Examples use SophiTracker.push; equivalent window.sophi_object.* = ... assignments produce the same events after the SDK has started.

Static / server-rendered page

Define sophi_object before the script tag:

<script>
  window.sophi_object = {
    config: {
      apiKey: 'YOUR_API_KEY',
      userId: 'usr-123'
    },
    page: {
      type: 'Product',
      url: 'https://store.com/products/blue-dress',
      title: 'Blue Dress | Store',
      language: 'tr-TR'
    },
    product: {
      id: '1627421',
      category_ids: ['cat-dresses', 'cat-womens'],
      name: 'Blue Dress',
      url: 'https://store.com/products/blue-dress',
      product_image_url: 'https://cdn.store.com/blue.jpg',
      taxonomy: ['Clothing', 'Dresses', 'Evening'],
      currency: 'TRY',
      unit_price: 1200.0,
      unit_sale_price: 990.0,
      in_stock: 1
    }
  };
</script>
<script src="https://cdn.jsdelivr.net/npm/@usesophi/sophi-web-object@latest/dist/sophi.min.js" async></script>

This typically emits page_view (from page) and product_view (from product).

SPA route change

SophiTracker.push({
  page: {
    type: 'Category',
    url: 'https://store.com/womens/dresses',
    category_id: 'cat-dresses'
  },
  listing: {
    category_id: 'cat-dresses',
    name: "Women's Dresses",
    taxonomy: ['Clothing', 'Dresses'],
    total_results: 234,
    page_number: 1,
    page_size: 24,
    items: [
      {
        product_id: '1627421',
        position: 1,
        name: 'Blue Dress',
        url: 'https://store.com/products/blue-dress',
        product_image_url: 'https://cdn.store.com/blue.jpg',
        currency: 'TRY',
        unit_price: 1200.0,
        unit_sale_price: 990.0,
        in_stock: 1
      }
    ]
  }
});

Add to cart

Set event_type explicitly; include product and basket.

SophiTracker.push({
  event_type: 'add_to_cart',
  page: {
    type: 'Product',
    url: 'https://store.com/products/blue-dress'
  },
  product: {
    id: '1627421',
    category_ids: ['cat-dresses'],
    name: 'Blue Dress',
    url: 'https://store.com/products/blue-dress',
    product_image_url: 'https://cdn.store.com/blue.jpg',
    taxonomy: ['Clothing', 'Dresses'],
    currency: 'TRY',
    unit_price: 1200.0,
    unit_sale_price: 990.0,
    in_stock: 1
  },
  basket: {
    currency: 'TRY',
    total: 990.0,
    line_items: [
      {
        product_id: '1627421',
        quantity: 1,
        currency: 'TRY',
        unit_price: 1200.0,
        unit_sale_price: 990.0,
        line_total: 990.0
      }
    ]
  }
});

For remove_from_cart, use the same shape with an updated basket and event_type: 'remove_from_cart'.

Purchase confirmation

SophiTracker.push({
  page: {
    type: 'Confirmation',
    url: 'https://store.com/checkout/confirmation/ORD-99231'
  },
  transaction: {
    order_id: 'ORD-99231',
    currency: 'TRY',
    total: 1989.9,
    subtotal: 1980.0,
    tax: 0.0,
    shipping_cost: 9.9,
    discount_total: 210.0,
    coupon_code: 'SS25',
    payment_method: 'credit_card',
    line_items: [
      {
        product_id: '1627421',
        quantity: 2,
        currency: 'TRY',
        unit_price: 1200.0,
        unit_sale_price: 990.0,
        line_total: 1980.0
      }
    ]
  }
});

User login

SophiTracker.updateUser('usr-8842');

SophiTracker.push({
  user: {
    consent: {
      gdpr_optin: true,
      version: '2026-01-15',
      timestamp: Math.floor(Date.now() / 1000)
    },
    identity: {
      uuid: 'usr-8842',
      email: 'jane@example.com'
    },
    profile: {
      name: 'Jane',
      surname: 'Doe',
      gender: 'F'
    },
    behavior: {
      returning: true,
      has_transacted: true,
      transaction_count: 4
    }
  }
});

User logout

SophiTracker.updateUser(undefined);

Clears session state and establishes a new anonymous session for subsequent events.