Shipped Suite React Client SDK

Shipped Suite offers premium package assurance for shipments that are lost, damaged or stolen. Instantly track and resolve shipment issues hassle-free with the app.

Bigcommerce

Installation

npm install shipped-suite-react-client-sdk
npm install shipped-suite-bigcommerce-headless-client-sdk

Usage

1. Import ShippedWidget and ShippedController react components into your project:

import { ShippedWidget, ShippedController } from 'shipped-suite-react-client-sdk/bigcommerce';

2. Add <ShippedWidget /> component inside a <ShippedController /> component:

<ShippedController
  shippedConfig={{
    storeHash: 'your_store_hash',
  }}
  onInit={handleInit}
  onChange={handleChange}
  onProcessStart={handleProcessStart}
  onProcessEnd={handleProcessEnd}
  cartItems={cartItems}
  isCartEligible={isCartEligible}
>
  <ShippedWidget />
</ShippedController>

• storeHash can be derived from your Bigcommerce store dashboard URL. For example, if your URL is https ://store-xxxxxxxxx.mybigcommerce.com/ then your_store_hash value is xxxxxxxxx.

Shopify

Installation

npm install shipped-suite-react-client-sdk
npm install shipped-suite-shopify-headless-client-sdk

Usage

1. Import ShippedWidget and ShippedController react components into your project:

import { ShippedWidget, ShippedController } from 'shipped-suite-react-client-sdk/shopify';

2. Add <ShippedWidget /> component inside a <ShippedController /> component:

<ShippedController
  shippedConfig={{
    domain: 'your-shopify-domain.myshopify.com',
    accessToken: 'your-shopify-access-token',
    cartIdDetails: {
      storageType: 'localStorage',
      key: 'storage-key',
      path: 'cardId',
    },
  }}
  onInit={handleInit}
  onChange={handleChange}
  onProcessStart={handleProcessStart}
  onProcessEnd={handleProcessEnd}
  cartItems={cartItems}
  isCartEligible={isCartEligible}
>
  <ShippedWidget />
</ShippedController>

• domain - your Shopify storefront URL (ends with .myshopify.com)
• accessToken - Shopify access token (used for Shopify GraphQL queries)
• cartIdDetails:
  • Shipped widget is applicable in the context of an existing cart on user's end. That cart ID is usually stored in localStorage or sessionStorage
  • storageType - localStorage or sessionStorage
  • key - the key name in localStorage or sessionStorage where cartId can be found
  • path - the key name above can have a JSON format. path indicates the JSON path that leads to cartId. If no path is specified, cartId will be the value of the key above

All platforms

3. If you need to add more than one <ShippedWidget /> element (for example, one for mobile cart and one for desktop cart), you need to ensure that all <ShippedWidget /> elements are wrapped within a single <ShippedController /> element instance.

4. Configure component props:

• shippedConfig is the object that allows widget configuration.

• onInit & onChange - optional. Since adding & removing Shipped product from cart is handled automatically by the widget, onChange could be useful for any other UI related adjustments. When a user opts in or opts out of Shipped widget, or when the offer changes, onChange callback is triggered. You can provide a handler for this callback:

  const handleChange = (details) => {
    console.log(details);
  
    // Example 'details':
    // {
    //   "isSelected": true,
    //   "totalFee": "2.23",
    //   "shippedProducts": []
    // }
  };

• onProcessStart & onProcessEnd - optional. The first one fires immediately before the Shipped widget starts any processes such as fetching cart information, retrieving Shipped offers, or mutating the cart. The second fires immediately afterward. These are useful to add logic that prevents the user from making any changes to the cart while in between these two events.

• When cartItems value changes

  • the widget will automatically update its price
  • Shipped products in cart will also be automatically updated

  cartItems can be any object from your code that you would want the widget to react to. It could also be just a total price variable.

  IMPORTANT! cartItems must exclude Shipped product(s). The widget needs to react only to non-Shipped items. For example, if a new regular product is added to cart, we want the widget to react and update the Shipped price on the widget and also add the Shipped product to cart. But when the Shipped product itself is added to cart, we no longer want to update the Shipped price.

• isCartEligible is a boolean that indicates whether or not the cart is eligible for Shipped widget. By default it's true, but if this is changed to false, the widget will no longer show and Shipped items will be removed from cart.