Wishlist integration

Introduction

The wishlist feature allows viewers to save products for later. This feature is available in the player and can be integrated with your e-commerce platform.

How it works

The player triggers events when a user adds or removes a product from the wishlist. You can listen to these events and update your backend accordingly. The player can also request the wishlist status for a list of products to display the correct state to the user.

Enabling the wishlist feature

To enable the wishlist feature, you need to switch it on in the theme editor in your dashboard. For the feature to work correctly, you also need to implement the integration methods described in this document.

Player Events

The following events are related to the wishlist feature:

• player.EVENT.ADD_TO_WISHLIST: Triggered when a user clicks the "add to wishlist" button.
• player.EVENT.REMOVE_FROM_WISHLIST: Triggered when a user clicks the "remove from wishlist" button.
• player.EVENT.PROVIDE_WISHLIST_STATUS: The player requests the wishlist status for a list of products. This event is triggered during the startup sequence of the player, after it has fetched the list of products from the backend.
• player.EVENT.OPEN_WISHLIST: Triggered when a user clicks the "view wishlist" button.
• player.EVENT.OPEN_WISHLIST_LOGIN: Triggered when a user clicks the "login" button after attempting to add an item to the wishlist.

Player Methods

player.updateWishlistStatus(wishlistStatus)

This method is used to inform the player about the wishlist status of products. The player will use this information to update the UI, for example, by showing the correct icon on the wishlist button. This method should be called in response to the player.EVENT.PROVIDE_WISHLIST_STATUS event. It can also be called at any other time to update the wishlist status in the player.

The wishlistStatus object has the following shape:

interface WishlistStatus {
  statuses: {
    [sku: string]: boolean;
  };
}

• statuses: An object where each key is a product sku and the value is a boolean indicating whether the product is in the wishlist (true) or not (false).

Example:

player.updateWishlistStatus({
  statuses: {
    'sku-123': true,
    'sku-456': false,
  },
});

Example implementation

The ADD_TO_WISHLIST and REMOVE_FROM_WISHLIST events provide a sku in the event payload, which can be used to identify the specific product variant. The PROVIDE_WISHLIST_STATUS event provides a list of products, each with a sku.

The ADD_TO_WISHLIST callback accepts a reason property. If the reason is set to 'login-required', the player will show a login button to the user. When the user clicks the login button, the OPEN_WISHLIST_LOGIN event is triggered. If the reason is set to 'more-info-required', the player will show a button that opens the product details view. This can be used when a shopper needs to select a size or color before adding a product to the wishlist.

// Mock wishlist implementation using localStorage
const getWishlist = () => JSON.parse(localStorage.getItem('wishlist') || '{}');
const addToWishlist = (sku) => {
  const wishlist = getWishlist();
  wishlist[sku] = true;
  localStorage.setItem('wishlist', JSON.stringify(wishlist));
};
const removeFromWishlist = (sku) => {
  const wishlist = getWishlist();
  delete wishlist[sku];
  localStorage.setItem('wishlist', JSON.stringify(wishlist));
};
const isInWishlist = (sku) => {
  const wishlist = getWishlist();
  return wishlist[sku] === true;
};
// A mock function to check if the user is logged in
const isUserLoggedIn = () => false;
// A mock function to check if a product requires more info
const needsMoreInfo = (sku) => sku.includes('some-specific-sku');

player.on(player.EVENT.ADD_TO_WISHLIST, (event, callback) => {
  console.log('ADD TO WISHLIST', event);
  const { sku } = event;

  // Example of handling a login-required scenario
  if (!isUserLoggedIn()) {
    callback({
      success: false,
      sku,
      reason: 'login-required',
    });
    return;
  }

  // Example of handling a more-info-required scenario
  if (needsMoreInfo(sku)) {
    callback({
      success: false,
      sku,
      reason: 'more-info-required',
    });
    return;
  }

  // At this point, you should call your own backend API or use localStorage to save the product to the wishlist.
  addToWishlist(sku);

  // The callback should be called with `success: true` if the operation was successful.
  callback({
    success: true,
    sku,
    reason: null,
  });
});

player.on(player.EVENT.REMOVE_FROM_WISHLIST, (event, callback) => {
  console.log('REMOVE FROM WISHLIST', event);
  const { sku } = event;

  // At this point, you should call your own backend API or use localStorage to remove the product from the wishlist.
  removeFromWishlist(sku);

  // The callback should be called with `success: true` if the operation was successful.
  callback({
    success: true,
    sku,
    reason: null,
  });
});

player.on(player.EVENT.PROVIDE_WISHLIST_STATUS, (event) => {
  console.log('PROVIDE_WISHLIST_STATUS', event);
  const statuses = {};
  if (event.products) {
    event.products.forEach(({ sku }) => {
      // At this point, you should check your own backend API or localStorage to see if the product is in the wishlist.
      // The status should be `true` if the product is in the wishlist, and `false` otherwise.
      statuses[sku] = isInWishlist(sku);
    });
  }
  player.updateWishlistStatus({
    statuses,
  });
});

player.on(player.EVENT.OPEN_WISHLIST, (event) => {
  console.log('OPEN WISHLIST', event);
  // At this point, you can open your own wishlist page.
});

player.on(player.EVENT.OPEN_WISHLIST_LOGIN, (event) => {
  console.log('OPEN WISHLIST LOGIN', event);
  // At this point, you can open your own login page.
});

Theming

The wishlist feature's appearance can be customized from the theme editor in your dashboard. The settings are grouped into the following sections:

Player Settings

• Enable wishlist: Player settings → Product CTAs → Enable Wishlist
  • Enables the wishlist functionality in the player.
• Show wishlist button on list items: Player settings → Product CTAs → Show wishlist button on list items
  • Shows the wishlist button on products in the product list view.
• Show Buy button: Player settings → Product CTAs → Show Buy button
  • Shows the "Add to cart" button.
• Allow selecting out-of-stock items: Player settings → Product CTAs → Allow selecting out-of-stock items
  • Allows viewers to select variations and sizes that are out of stock.

Assets

• Add to wishlist icon: Assets → Icons → Add to wishlist
• Remove from wishlist icon: Assets → Icons → Remove from wishlist

Button Styles

• "Add to wishlist" button:
  • Style: Button → Add to wishlist enabled
  • Hover Style: Button → Add to wishlist hover