Начать бесплатноПопробовать

← Справочный центр

Hydrogen и headless-витрины

Отслеживайте витрину на Hydrogen или другую headless-витрину Shopify с помощью модуля ROASaurus.

У headless-витрины нет темы Shopify, поэтому встраивание ROASaurus в тему не работает. Вместо этого вы загружаете в браузере небольшой ES module от ROASaurus. Пакет npm не нужен. Чекаут остаётся на Shopify, где пиксель приложения ROASaurus (устанавливается вместе с приложением) отслеживает чекауты и покупки, как и раньше, а заказы по-прежнему поступают через вебхуки заказов Shopify.

1. Загрузите модуль

Ключ магазина находится в ROASaurus на странице Setup › Shopify этого магазина. Загружайте модуль только в браузере (не во время серверного рендеринга):

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 обновляется с каждым релизом 1.x. Закрепите точную версию через /headless@1.0.0.js или всегда берите последнюю через /headless.js. Разрешите https://app.roasaurus.com в Content Security Policy для скриптов и соединений (Hydrogen: scriptSrc и connectSrc в createContentSecurityPolicy).

2. Подключите аналитику Hydrogen

Hydrogen 2026-04 и более ранние версии: отрендерите этот компонент внутри <Analytics.Provider>.

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 и более поздние версии: добавьте ROASaurus как получателя в шину аналитики, один раз за загрузку страницы.

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

Модуль отправляет page_viewed как PageView, product_viewed как ViewContent, product_added_to_cart как AddToCart (с добавленным количеством) и cart_viewed как просмотр корзины. ROASaurus передаёт их в ваши рекламные платформы с теми же event id, что и у их браузерных пикселей.

3. Запишите атрибуты корзины

Visitor id в корзине связывает заказ Shopify с кликом по рекламе. В Hydrogen обновляйте атрибуты корзины через roasaurus.cartAttributes() при добавлении товара (например, CartForm с CartForm.ACTIONS.AttributesUpdateInput или cart.updateAttributes() в action корзины). Сохраняйте атрибуты, которые уже есть у корзины.

В других headless-витринах их может записывать сам модуль через Storefront API с публичным токеном:

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

Он считывает атрибуты корзины, добавляет _tl, click id и рынок и сохраняет их через cartAttributesUpdate. Корзина, замеченная при наличии согласия, также связывается с посетителем, поэтому заказ сопоставляется, даже если атрибутов нет.

Согласие

Модуль следует Customer Privacy API Shopify (window.Shopify.customerPrivacy), который Hydrogen загружает со своими настройками consent. Пока маркетинговый выбор покупателя неизвестен, события ждут. Если покупатель отказывается, visitor id, click id и атрибуты корзины не сохраняются, а события отправляются без идентификаторов и не передаются в рекламные платформы. Если у вас свой баннер, вызывайте roasaurus.setConsent(true) или setConsent(false).

Другие вызовы

Всё ещё не получается? Напишите нам.