hydrogen-web-sdk

This package is developed for Shopify Hydrogen integrations to handle Insider Web SDK integration.

npm install insider-npm

Usage

import {Insider, useInsider} from "insider-npm";

// Wrap your app
<Insider.Provider partnerName="YOUR_PARTNER_NAME" partnerId="YOUR_PARTNER_ID" nonce="">
  {children}
</Insider.Provider>

// Hook usage inside components (recommended)
const Page = () => {
  const {
    initialize,
    pushHomePageView,
    pushCategoryPageView,
    pushOtherPageView,
    pushProductPageView,
    pushCartPageView,
    pushProduct,
    pushCurrency,
    pushCart,
    pushAddToCart,
    pushRemoveFromCart,
    pushToQueue,
    pushInitToQueue,
    pushPageViewEvent,
  } = useInsider();

  // Example calls
  initialize();
  pushHomePageView({currency: "USD"});
  pushCategoryPageView(["Dresses", "Night Dresses", "Long Sleeve"]);
  pushOtherPageView({name: "Custom Landing", currency: "USD"});
  pushProductPageView({product, currency: "USD"});
  pushCartPageView({cart, currency: "USD"});
  pushProduct(product);
  pushCurrency("USD");
  pushCart(cart);
  pushAddToCart({...product, quantity: 1});
  pushRemoveFromCart({...product, quantity: 1});
  pushInitToQueue();
  pushPageViewEvent({
    type: "category",
    user: {email: "[email protected]"},
    currency: "USD",
    category: ["Dresses", "Night Dresses", "Long Sleeve"],
  });

  return null;
};

// Static usage inside components (also valid)
const PageStatic = () => {
  Insider.initialize();
  Insider.pushHomePageView({currency: "USD"});
  return null;
};

Note: Insider.initialize() and other static methods require Insider.Provider to have rendered at least once. Call them after your app has mounted under the provider.

API

Components

• Insider.Provider: Initializes Insider SDK and provides context.

Hooks

• useInsider(): Returns the Insider actions listed below.

Functions

• getInsiderCspSources(partnerName: string): Returns CSP sources for Insider scripts.

Insider actions (from useInsider())

• pushToQueue(item)
• initialize()
• pushHomePageView(params?: {currency?: string; cart?: Cart; user?: UserAttributes})
• pushCategoryPageView(category: string | string[])
• pushCategoryPageView(params: {category: string | string[]; currency?: string; cart?: Cart; user?: UserAttributes})
• pushOtherPageView(params?: {name?: string; custom?: Record<string, object>; currency?: string; cart?: Cart; user?: UserAttributes})
• pushProductPageView(params: {product: Product; currency?: string; cart?: Cart; user?: UserAttributes})
• pushCartPageView(params: {cart: Cart; currency?: string; user?: UserAttributes})
• pushProduct(product)
• pushCurrency(currency)
• pushCart(cart)
• pushAddToCart(item)
• pushRemoveFromCart(item)
• pushInitToQueue()
• pushPageViewEvent(params)

Insider static methods

• Insider.pushToQueue(item)
• Insider.initialize()
• Insider.pushHomePageView(params?: {currency?: string; cart?: Cart; user?: UserAttributes})
• Insider.pushPageViewEvent(params)
• Insider.pushCategoryPageView(category: string | string[])
• Insider.pushCategoryPageView(params: {category: string | string[]; currency?: string; cart?: Cart; user?: UserAttributes})
• Insider.pushOtherPageView(params?: {name?: string; custom?: Record<string, object>; currency?: string; cart?: Cart; user?: UserAttributes})
• Insider.pushProductPageView(params: {product: Product; currency?: string; cart?: Cart; user?: UserAttributes})
• Insider.pushCartPageView(params: {cart: Cart; currency?: string; user?: UserAttributes})
• Insider.pushProduct(product)
• Insider.pushCart(cart)
• Insider.pushAddToCart(item)
• Insider.pushRemoveFromCart(item)
• Insider.pushInitToQueue()

pushPageViewEvent params

• type: "home" | "category" | "product" | "cart" | "other"
• user: user attributes object
• currency: currency code (optional)
• cart: cart data (optional)
• product: product data (required for type: "product")
• category: string or string[] (required for type: "category")
• name: page name (optional for type: "other")
• custom: custom attributes object (string/number/boolean values) (optional for type: "other")

pushPageViewEvent pushes user data first (if provided), then page data, then init.

Note: Cart items should include quantity.

Add to cart / Remove from cart

When sending add-to-cart or remove-from-cart events, Insider expects a product object with quantity. These events do not require an init call and should be triggered after the Insider tag is loaded.

Insider.pushAddToCart({
  id: "123",
  name: "Test",
  taxonomy: ["test"],
  unit_price: 100,
  unit_sale_price: 80,
  url: "https://test.com",
  product_image_url: "https://test.com/image.jpg",
  quantity: 1
});

Insider.pushRemoveFromCart({
  id: "123",
  name: "Test",
  taxonomy: ["test"],
  unit_price: 100,
  unit_sale_price: 80,
  url: "https://test.com",
  product_image_url: "https://test.com/image.jpg",
  quantity: 1
});

Page data - Category

When sending category (listing) page data, Insider expects breadcrumb as an array and init right after.

Insider.pushToQueue({
  type: "category",
  value: {breadcrumb: ["Dresses", "Night Dresses", "Long Sleeve"]},
});
Insider.pushToQueue({type: "init"});

CSP

This package injects scripts from Insider domains. You must allow these origins in your app's CSP:

• https://<partnerName>.api.useinsider.com
• https://shopify-pixel.useinsider.com

You can use the helper to get the required sources:

import {getInsiderCspSources} from "insider-npm";

const {scriptSrc, connectSrc} = getInsiderCspSources("shopifywebsdktest");

For more details on the Insider Web SDK Integration, see:

https://academy.insiderone.com/docs/insider-web-sdk-integration-guide

See CONTRIBUTING.md for release/publish steps.