Integrating Iterable’s SDK into Shopify Custom or Headless

export async function loader(args) {
  // Start fetching non-critical data without blocking time to first byte
  const deferredData = loadDeferredData(args);

  // Await the critical data required to render initial state of the page
  const criticalData = await loadCriticalData(args);

  const {storefront, env} = args.context;

  // Fetch customer data if user is logged in
  const isLoggedIn = await deferredData.isLoggedIn;
  let customerData;
  if (isLoggedIn) {
    const {data, errors} = await args.context.customerAccount.query(
      CUSTOMER_DETAILS_QUERY,
    );
    customerData = data.customer;
  } else {
    customerData = {};
  }

  return {
    iterableApiKey: env.ITERABLE_API_KEY, // Add this
    customerData, // Add this
    ...deferredData,
    ...criticalData,
    publicStoreDomain: env.PUBLIC_STORE_DOMAIN,
    shop: getShopAnalytics({
      storefront,
      publicStorefrontId: env.PUBLIC_STOREFRONT_ID,
    }),
    consent: {
      checkoutDomain: env.PUBLIC_CHECKOUT_DOMAIN,
      storefrontAccessToken: env.PUBLIC_STOREFRONT_API_TOKEN,
      withPrivacyBanner: false,
      country: args.context.storefront.i18n.country,
      language: args.context.storefront.i18n.language,
    },
  };
}

import {useIterableContext} from '~/context/IterableContext';
import {track} from '@iterable/web-sdk';

export function useIterableEvents() {
  const {isInitialized, isUserIdentified} = useIterableContext();

  /**
   * Track product view events
   * @param {Object} product - Product data from Shopify
   * @param {string} url - Current page URL
   */
  const trackProductView = async (product, url) => {
    if (!isInitialized) {
      console.log(
        'Iterable SDK not initialized, skipping product view tracking',
      );
      return;
    }

    if (!isUserIdentified) {
      console.log(
        'User not identified in Iterable SDK, skipping product view tracking',
      );
      return;
    }

    try {
      const variant = product.selectedOrFirstAvailableVariant;
      const dataFields = {
        product_id: product.id.split('/').pop(),
        product_name: product.title,
        variant_id: variant.id.split('/').pop(),
        image_url: variant.image?.url,
        price: parseFloat(variant.price.amount),
        currency: variant.price.currencyCode,
        sku: variant.sku,
        url,
      };

      await track({eventName: 'Product Viewed', dataFields});
      console.log('✅ Successfully tracked product view for:', product.title);
      return true;
    } catch (error) {
      console.error('❌ Error tracking product view:', error);
      return false;
    }
  };

  return {
    trackProductView,
  };
}

import {useEffect, useRef} from 'react';
import {useIterableContext} from '~/context/IterableContext';
import {track, updateCart} from '@iterable/web-sdk';

/**
 * Update cart in Iterable
 * @param {Object} cart - Cart data from Shopify
 */
const trackCartUpdate = async (cart) => {
  if (!isInitialized) {
    console.log('Iterable SDK not initialized, skipping cart update');
    return;
  }

  if (!isUserIdentified) {
    console.log('User not identified in Iterable SDK, skipping cart update');
    return;
  }

  if (!cart) return;

  try {
    const formattedItems = cart.lines.nodes.map((item) => ({
      id: item.merchandise.id,
      name: item.merchandise.product.title,
      quantity: item.quantity,
      price: parseFloat(item.merchandise.price.amount),
      sku: item.merchandise.sku || '',
      imageUrl: item.merchandise.image?.url,
      url: `/products/${item.merchandise.product.handle}`,
    }));

    await updateCart({items: formattedItems});
    console.log('✅ Successfully updated cart in Iterable');
    return true;
  } catch (error) {
    console.error('❌ Error updating cart in Iterable:', error);
    return false;
  }
};

return { trackProductView, trackCartUpdate };

/**
 * Automatically tracks cart changes to Iterable
 * Only fires events when cart contents actually change
 * @param {Object} cart - The cart object from Shopify
 */
export function useCartTracking(cart) {
  const {trackCartUpdate} = useIterableEvents();
  const previousCartRef = useRef(null);

  useEffect(() => {
    // Skip if no cart data
    if (!cart) return;

    // Create a stable identifier for the current cart state
    const currentCartSignature = JSON.stringify({
      id: cart.id,
      totalQuantity: cart.totalQuantity,
      lines:
        cart.lines?.nodes?.map((line) => ({
          id: line.merchandise.id,
          merchandiseId: line.merchandise?.id,
          quantity: line.quantity,
        })) || [],
    });

    // Only track if cart state has actually changed
    if (previousCartRef.current !== currentCartSignature) {
      // Update only after initial mount (skip first render)
      if (previousCartRef.current !== null) {
        trackCartUpdate(cart);
      }

      previousCartRef.current = currentCartSignature;
    }
  }, [cart, trackCartUpdate]);
}

import {useCartTracking} from '~/hooks/useIterableEvents';

export function CartMain({layout, cart: originalCart}) {
  const cart = useOptimisticCart(originalCart);

  // Automatically track cart changes
  useCartTracking(cart);

  // ... rest of your component
}

// Maps URL parameter names to cookie names
const PARAM_MAPPINGS = {
  iterable_campaign: 'iterable_campaign_id',
  iterable_template: 'iterable_template_id',
};

/**
 * Saves Iterable parameters from URL to cookies (expires in 24 hours)
 * @param {Object} params - URL parameters object (e.g., from URLSearchParams)
 */
export function setAttributionCookies(params) {
  if (typeof document === 'undefined') return;

  Object.entries(PARAM_MAPPINGS).forEach(([urlParam, cookieName]) => {
    if (params[urlParam]) {
      document.cookie = `${cookieName}=${params[urlParam]}; path=/; max-age=86400`;
    }
  });
}

/**
 * Reads attribution from server-side request cookies
 * @param {string} cookieHeader - Cookie header from request
 * @returns {Object} Object with iterable_campaign_id and iterable_template_id
 */
export function getAttributionFromRequest(cookieHeader) {
  if (!cookieHeader) return {};

  const cookies = cookieHeader.split(';').reduce((acc, cookie) => {
    const [name, value] = cookie.trim().split('=');
    if (name && value) acc[name] = decodeURIComponent(value);
    return acc;
  }, {});

  return {
    iterable_campaign_id: cookies.iterable_campaign_id,
    iterable_template_id: cookies.iterable_template_id,
  };
}

/**
 * Merges Iterable attribution with existing cart attributes
 * Replaces any existing Iterable attributes, preserves all others
 * @param {Array} existingAttributes - Current cart attributes
 * @param {Object} attribution - Attribution object with campaign/template IDs
 * @returns {Array} Merged attributes array
 */
export function mergeAttributionWithCart(
  existingAttributes = [],
  attribution = {},
) {
  // Keep all non-Iterable attributes
  const preserved = existingAttributes.filter(
    (attr) => !attr.key.startsWith('__iterable_'),
  );

  // Build new Iterable attributes
  const newAttrs = [];
  if (attribution.iterable_campaign_id) {
    newAttrs.push({
      key: '__iterable_campaign_id',
      value: attribution.iterable_campaign_id,
    });
  }
  if (attribution.iterable_template_id) {
    newAttrs.push({
      key: '__iterable_template_id',
      value: attribution.iterable_template_id,
    });
  }

  return [...preserved, ...newAttrs];
}

import {
  getAttributionFromRequest,
  mergeAttributionWithCart,
} from '~/lib/attribution';

export async function action({request, context}) {
  // ... existing cart action logic ...

  if (result?.cart) {
    const attribution = getAttributionFromRequest(
      request.headers.get('Cookie'),
    );

    if (attribution.iterable_campaign_id || attribution.iterable_template_id) {
      const mergedAttributes = mergeAttributionWithCart(
        result.cart.attributes || [],
        attribution,
      );
      result = await cart.updateAttributes(mergedAttributes);
    }
  }

  // ... rest of action ...
}