Hydrogen ve headless mağaza vitrinleri

Hydrogen veya başka bir headless Shopify mağaza vitrinini ROASaurus modülüyle takip edin.

Headless bir mağaza vitrininin Shopify teması yoktur; bu yüzden ROASaurus tema yerleştirmesi çalışmaz. Bunun yerine tarayıcıda ROASaurus'tan küçük bir ES module yüklersiniz. npm paketi gerekmez. Ödeme sayfası Shopify'da kalır; orada ROASaurus uygulama pikseli (uygulamayla birlikte yüklenir) ödemeleri ve satın alımları eskisi gibi takip eder, siparişler de yine Shopify'ın sipariş webhook'ları üzerinden gelir.

1. Modülü yükleyin

Mağaza anahtarınız, ROASaurus'ta mağazanın Setup › Shopify sayfasındadır. Modülü yalnızca tarayıcıda yükleyin (sunucu tarafında render sırasında değil):

const {createRoasaurus} = await import('https://app.roasaurus.com/headless@1.js');
const roasaurus = createRoasaurus({
  storeKey: 'YOUR_STORE_KEY',
  market: 'eu',      // optional: the Shopify Market handle of this storefront
  country: 'NL',     // optional: the shopper's country
});

/headless@1.js her 1.x sürümüyle birlikte güncellenir. Belirli bir sürüme sabitlemek için /headless@1.0.0.js, her zaman en yenisini almak için /headless.js kullanın. Content Security Policy'nizde betikler ve bağlantılar için https://app.roasaurus.com adresine izin verin (Hydrogen: createContentSecurityPolicy içinde scriptSrc ve connectSrc).

2. Hydrogen analitiğini bağlayın

Hydrogen 2026-04 ve öncesi: bu bileşeni <Analytics.Provider> içinde render edin.

import {useAnalytics} from '@shopify/hydrogen';
import {useEffect} from 'react';

export function RoasaurusAnalytics() {
  const {subscribe, register} = useAnalytics();
  const {ready} = register('ROASaurus');
  useEffect(() => {
    import(/* @vite-ignore */ 'https://app.roasaurus.com/headless@1.js').then(({createRoasaurus}) => {
      const roasaurus = createRoasaurus({storeKey: 'YOUR_STORE_KEY'});
      roasaurus.subscribeHydrogen(subscribe);
      ready();
    });
  }, []);
  return null;
}

Hydrogen 2026-10 ve sonrası: ROASaurus'u analitik veri yoluna bir hedef olarak ekleyin; her sayfa yüklemesinde yalnızca bir kez.

const roasaurus = createRoasaurus({storeKey: 'YOUR_STORE_KEY'});
roasaurus.addToBus(window.Shopify.analytics);

Modül page_viewed olayını PageView, product_viewed olayını ViewContent, product_added_to_cart olayını AddToCart (eklenen miktarla) ve cart_viewed olayını sepet görüntüleme olarak gönderir. ROASaurus bunları, tarayıcı pikselleriyle aynı olay kimlikleriyle reklam platformlarınıza iletir.

3. Sepet özniteliklerini yazın

Sepetteki ziyaretçi kimliği, Shopify siparişini reklam tıklamasına bağlar. Hydrogen'da bir ürün eklendiğinde sepetin özniteliklerini roasaurus.cartAttributes() ile güncelleyin (örneğin CartForm.ACTIONS.AttributesUpdateInput içeren bir CartForm ya da sepet action'ınızda cart.updateAttributes()). Sepette zaten bulunan öznitelikleri koruyun.

Diğer headless mağaza vitrinleri, bunları herkese açık bir token ile Storefront API üzerinden modüle yazdırabilir:

const roasaurus = createRoasaurus({
  storeKey: 'YOUR_STORE_KEY',
  shopDomain: 'your-store.myshopify.com',
  storefrontAccessToken: 'PUBLIC_STOREFRONT_TOKEN',
});
await roasaurus.beforeCheckout(cart);   // before you send the shopper to cart.checkoutUrl

Modül sepetin özniteliklerini okur, _tl değerini, tıklama kimliklerini ve pazarı ekler, ardından bunları cartAttributesUpdate ile kaydeder. Rızayla görülen bir sepet ziyaretçiye de bağlanır; böylece öznitelikler eksik olsa bile sipariş eşleşir.

Rıza

Modül, Hydrogen'ın consent ayarlarıyla yüklediği Shopify Customer Privacy API'sini (window.Shopify.customerPrivacy) izler. Alışverişçinin pazarlama tercihi belli olana kadar olaylar bekletilir. Reddettiğinde ziyaretçi kimliği, tıklama kimliği ya da sepet özniteliği tutulmaz; olaylar tanımlayıcılar olmadan gönderilir ve reklam platformlarına iletilmez. Kendi bannerınızı kullanıyorsanız roasaurus.setConsent(true) veya setConsent(false) çağırın.

Diğer çağrılar

roasaurus.track('Lead', {value: 50, currency: 'EUR'}) herhangi bir olayı gönderir.
roasaurus.identify({email}) bir kaydolma işlemini ziyarete bağlar (rıza varsa).
roasaurus.handle('product_viewed', payload) diğer framework'lerden Hydrogen tarzı payload'ları kabul eder.

Hâlâ takıldınız mı? Bize e-posta gönderin.