Rep AI Web Client Integration Guide for Headless Shopify (e.g., Hydrogen)

Standard Shopify websites work seamlessly with the Rep widget, and no additional configuration is required to launch the widget. If you use a headless website, additional configuration might be required.

This guide outlines how to integrate headless Shopify setups with the Rep AI Web Client. It covers initialization, triggering events, mapping data, listening to platform events, and Hydrogen-specific setup instructions.

Note: Knowledge of coding is required.

1. Initialize the Rep AI Web Client

Step 1: Inject the Script

Add the following script tag to your root HTML or layout file:

<script src="https://d1o5e9vlirdalo.cloudfront.net/initRepConfig.min.js"></script>

Step 2: Initialize the Client

window.initRepConfig({
  partnerKey: '{{account_key}}',             // Provided by Rep AI
  analyticsProcessingAllowed: true,          // Based on user cookie consent
  localization: 'US',                         // ISO 3166-1 alpha-2 country code
  currencySymbol: 'USD'                       // Optional; default is USD
});

Step 3: Trigger Page Events on Load

window.rep.triggerEvent('PAGE_VIEWED', eventData);
window.rep.triggerEvent(EVENT_TYPE, eventData); // Example: 'HOMEPAGE_VIEWED'

Refer to Section 2 for supported event types.

2. Triggering Events

Use window.rep.triggerEvent(eventType, eventData) to manually track user behavior.

Common Event Types

3. Mapping Shopify Liquid Fields to Rep AI Events

Use Shopify Liquid objects to populate the eventData object. Examples below:

PAGE_VIEWED / HOMEPAGE_VIEWED / OTHER_PAGE_VIEWED

window.rep.triggerEvent("PAGE_VIEWED", {
  pageTitle: "{{ page_title }}",
  cartRevenue: {{ cart.items_subtotal_price | money_without_currency }}
});

CART_VIEWED

window.rep.triggerEvent("CART_VIEWED", {
  pageTitle: "Cart",
  cartRevenue: {{ cart.total_price | money_without_currency }},
  cartItems: [
    {% for item in cart.items %}{
      productId: {{ item.product.id }},
      productTitle: "{{ item.product.title }}",
      productVariantId: {{ item.variant.id }},
      productVariantTitle: "{{ item.variant.title }}",
      productPrice: {{ item.variant.price | money_without_currency }},
      productQuantity: {{ item.quantity }}
    }{% unless forloop.last %},{% endunless %}{% endfor %}
  ]
});

PRODUCT_VIEWED

window.rep.triggerEvent("PRODUCT_VIEWED", {
  productId: {{ product.id }},
  productSku: "{{ variant.sku }}",
  productTitle: "{{ product.title }}",
  productVariantTitle: "{{ variant.title }}",
  productPrice: {{ variant.price | money_without_currency }},
  productImage: "{{ variant.image.src }}",
  productVendor: "{{ product.vendor }}",
  productType: "{{ product.type }}"
});

PRODUCT_LIST_VIEWED

window.rep.triggerEvent("PRODUCT_LIST_VIEWED", {
  collectionId: {{ collection.id }},
  collectionType: "{{ collection.title }}"
});

PRODUCT_ADDED / PRODUCT_REMOVED

window.rep.triggerEvent("PRODUCT_ADDED", {
  productId: {{ product.id }},
  productTitle: "{{ product.title }}",
  productVariantTitle: "{{ variant.title }}",
  productPrice: {{ variant.price | money_without_currency }},
  productImage: "{{ variant.image.src }}",
  productQuantity: {{ quantity }},
  cartRevenue: {{ cart.total_price | money_without_currency }}
});

CART_UPDATED

window.rep.triggerEvent("CART_UPDATED", {
  cartRevenue: {{ cart.total_price | money_without_currency }},
  cartItems: [
    {% for item in cart.items %}{
      productId: {{ item.product.id }},
      productTitle: "{{ item.product.title }}",
      productVariantId: {{ item.variant.id }},
      productVariantTitle: "{{ item.variant.title }}",
      productPrice: {{ item.variant.price | money_without_currency }},
      productQuantity: {{ item.quantity }}
    }{% unless forloop.last %},{% endunless %}{% endfor %}
  ]
});

ORDER_COMPLETED

window.rep.triggerEvent("ORDER_COMPLETED", {
  totalPrice: {{ checkout.total_price | money_without_currency }},
  orderId: "{{ checkout.order_id }}",
  discountCode: "{{ checkout.discount_code }}",
  currency: "{{ checkout.currency }}",
  discountsAmount: {{ checkout.discounts_amount | money_without_currency }},
  taxPrice: {{ checkout.tax_price | money_without_currency }},
  shippingPrice: {{ checkout.shipping_price | money_without_currency }}
});

IDENTIFY

window.rep.triggerEvent("IDENTIFY", {
  customerId: "{{ customer.id }}"
});

📘 Refer to Shopify Liquid Documentation for a complete list of available fields.

4. Hydrogen Integration

Step 1: Wrap App with Analytics Provider

<Analytics.Provider cart={data.cart} shop={data.shop} consent={data.consent}>
  <PageLayout {...data}>{children}</PageLayout>
  <RepAiIntegration />
</Analytics.Provider>

Step 2: Track Views Per Route

<Analytics.ProductView data={{
  products: [{
    id: product.id,
    title: product.title,
    price: variant.price.amount,
    vendor: product.vendor,
    variantId: variant.id,
    variantTitle: variant.title,
    quantity: 1,
    image: variant.image.url
  }]
}} />

Use ProductView, CollectionView, or CustomView depending on route type.

5. Web Client Event Listeners

Subscribe to Web Client events:

window['rep'].on(EVENT_TYPE, callback);

Available Events

Example: Accepting Cookie Consent

window['rep'].setUserPrivacyPolicyProved(true);

6. Chat Control APIs

rep.open();   // Open the chat
rep.close();  // Minimize the chat
rep.hide();   // Hide the widget
rep.show();   // Show the widget

🔗 References

• Shopify Liquid Objects
• Shopify Hydrogen Docs
• Rep AI Documentation