Documentation

Integration Guide

Ingrid provides a bootstrap.js file (stage production), which when loaded exposes methods on the window._ingridPDPWidgetApi object. These methods can be used to display the Product Page Widget and allow back and forth communication between widget's iframe and your website.

Using addListener, you can register callbacks that will be fired when Product Page Widget emits events.

After you subscribe to events with your callbacks, you can use render method to render an iframe with the widget in a specified container. To see the example integration, jump to Integration example section.

Integration steps:

  1. Embed bootstrap script from our CDN stage production.

  2. Subscribe to events by calling window._ingridPDPWidgetApi.addListener with chosen event name and provide a callback function.

  3. Call window._ingridPDPWidgetApi.render to initialize and display the Product Page Widget. This method takes two argumets, respectively:

    • the id attribute of a container, in which the widget will be located
    • a config object, required to create delivery offering
Important notice

When creating a script tag, it is required to add attribute type="module"

Authorization

It is required to specify the token in the auth_token config field used by render method. The token has a pattern of ingrid-http-auth-token:<your_id>. You can obtain your token by reaching out to Ingrid Customer Success Team.

Config object

Config object consists of required and optional values that could be used for creation of a delivery offering. If the config is invalid, an error event will be sent via addListener callback.

Note

TypeScript type definitions for the config object can be found on the bottom of that page

Collecting data

Product Page Widget has the possibility to gather analytics data (such as created delivery offerings and their impact on a user's decision on adding item to cart), which then Ingrid will aggregate for you. If you'd like to analytics on, two following steps are required:

  1. Enable analytics in Ingrid's system

  2. Add window._ingridPDPWidgetApi.onItemAdded method call when item has been added to the cart.

API overview

window._ingridPDPWidgetApi object exposes methods listed below:

Integration example

const configObject = {
  country: "SE",
  locales: ["en-US"],
  currency: "SEK",
  auth_token: "ingrid-http-auth-token:<your_id>",
  cart: {
    cart_id: "e2c7b0e8-a860-4624-9f04-9a85a5a30649",
    attributes: [],
    total_value: 10000,
    items: [
      {
        attributes: ["gray"],
        name: "Mouse",
        price: 500,
        sku: "mouse_43209423",
      },
      {
        attributes: [],
        name: "Notebook",
        price: 9500,
        sku: "notebook_3824932",
      },
    ],
  },
  viewed_item: {
    attributes: ["gray"],
    name: "Mouse",
    price: 500,
    sku: "mouse_43209423",
  },
};

const loadScript = (
  src: string,
  options: {
    onLoad: GlobalEventHandlers["onload"] | null;
  }
) => {
  const script = document.createElement("script");
  script.src = src;
  /**
   * important: note the type attribute below
   */
  script.type = "module";
  script.onload = options.onLoad;
  document.body.appendChild(script);
};

const Widget = () => {
  const ref = React.useRef<HTMLDivElement>(null);

  React.useEffect(() => {
    if (ref.current) {
      const container = ref.current;

      loadScript("https://cdn.ingrid.com/product-page-widget/bootstrap.js", {
        onLoad: () => {
          ref.current.innerHTML = "";
          window._ingridPDPWidgetApi.addListener("ready", () => {
            console.log("Widget is ready");
          });
          window._ingridPDPWidgetApi.addListener("error", (value: string) => {
            /**
             * You can implement your fallback logic if the error occurs -
             * it could happen when the provided config object is invalid
             */
            console.log("Error event: " + value);
          });
          window._ingridPDPWidgetApi.render(container.id, configObject);
        },
      });
    }
  }, []);

  return <div ref={ref} id="product-page-widget" />;
};

If you would like to gather more meaningful analytics data, add onItemAdded call:

// Register item addition to cart

const AddToCartButton = ({ item }) => {
  const handleClick = (e) => {
    // ...
    window._ingridPDPWidgetApi.onItemAdded(item.sku);
  };

  return <Button onClick={handleClick}>Add item to cart</Button>;
};

TypeScript

Typings for the configuration object are as follows:

type Config = {
  auth_token: string;
  cart: Cart;
  country: string;
  currency: string;
  external_id?: string;
  locales: string[];
  viewed_item: Item;
};

type Cart = {
  attributes?: string[];
  cart_id: string;
  items?: Item[];
  /** @format int32 */
  total_value: number;
};

type Item = {
  /**
   * Attributes of item. They are specific to that particular item and can be set to adjust delivery offering.
   * They can be set in the filter rules for certain shipping categories or carrier products in site configuration
   * so that the delivery offering presented in product page widget is more precise.
   */
  attributes?: string[];
  dimensions?: Dimensions;
  /**
   * Discount for the item.
   * @format int32
   */
  discount?: number;
  /** Product name or title. */
  name: string;
  /** Flag indicating if the item is currently out of stock. */
  out_of_stock?: boolean;
  /**
   * Price of the item.
   * @format int32
   */
  price: number;
  /**
   * Number of entities of the given item.
   * @format int32
   */
  quantity?: number;
  shipping_date?: ShippingDate;
  /** Unique product identifier. */
  sku: string;
  /**
   * Weight of the item in grams.
   * Example `1000` is 1 kg and `10` is 0,01 kg.
   * @format int32
   */
  weight?: number;
};

type Dimensions = {
  /**
   * Height of the item in millimeters.
   * @format int32
   */
  height?: number;
  /**
   * Length of the item in millimeters.
   * @format int32
   */
  length?: number;
  /**
   * Width of the item in millimeters.
   * @format int32
   */
  width?: number;
};

type ShippingDate = {
  /** End of the interval. Date is returned in RFC3339 format. Example `2018-09-08T22:47:31+01:00`. */
  end?: string;
  /** Start of the interval. Date is returned in RFC3339 format. Example `2018-09-08T22:47:3+01:00`.*/
  start?: string;
};

Last updated: Thu, Nov 21, 06:15 AM