useGtm

Use useGtm when your theme must report customer actions, such as viewing a product or adding it to the cart, to the merchant's Google Tag Manager container.

ExampleCopy Anchor Link

import { useEffect } from 'react';
import { useGtm } from '@salla.sa/twilight-theme-engine/hooks/useGtm';
import type { Product } from '@salla.sa/twilight-theme-engine/types';

export function AddToCart({ product }: { product: Product }) {
  const gtm = useGtm();

  useEffect(() => {
    gtm.detail(product);
  }, [product.id]); // eslint-disable-line react-hooks/exhaustive-deps

  return (
    <button
      onClick={async () => {
        await window.salla?.cart.addItem(product.id, 1);
        gtm.add(product, 1);
      }}
    >
      Add to cart
    </button>
  );
}

APICopy Anchor Link

function useGtm(): UseGtmResult;

Ecommerce events carry an ecommerce object with currencyCode, a unique event_id, and the products (id, name, price, brand, category, quantity). Product price is sale_price.

GotchasCopy Anchor Link

• Everything is a no-op when the store has no Tag Manager id, so you can call the methods without checking enabled.
• The engine loads the Tag Manager script itself. This hook only pushes events to window.dataLayer.
• Call the methods from effects and event handlers, not during render. They use window, so they only work in the browser.
• The currency of detail, impressions, click and add is the product's own currency. For remove, checkout and purchase it is the signed-in customer's preferred currency, and SAR for guests.
• The hook calls useUser inside, so the result is a new object on every render. Do not use gtm as a useEffect dependency; keep it in a ref, as in the page views recipe.
• The engine does not call these methods for you. Your components decide where each event is sent.

NextCopy Anchor Link

• Track page views: send viewPage on every client-side navigation.
• Store data: keys.gtm.
• Cart data: the Cart and CartItem you pass to checkout and purchase.