What is Shoppable Content

Storyly Placement SDK provides powerful shoppable features that enable seamless e-commerce integration within widgets.

📘

Features

• Manage shopping cart operations with real-time feedback
• Track product analytics through comprehensive event callbacks
• Hydrate products from your latest data source, ensuring up-to-date pricing, availability, and product information
• Product wishlist for user's favorite products

📘

Architecture

Callback-Based Control

Cart and wishlist operations are handled through StorylyPlacement callbacks, giving your application complete control over state management, API integration, and user experience.

Approve-Reject Mechanism

The SDK uses a callback-based mechanism where you must explicitly approve or reject each cart/wishlist update by calling approveCartChange / rejectCartChange (or approveWishlistChange / rejectWishlistChange) on the placement ref with the event's responseId, ensuring your backend always has the final say.

🚧

Prerequisites

• Storyly Placement SDK integrated and initialized in your React Native application as described in Initial Setup.
• Shoppable Content user guide must be followed and integrations on Storyly Dashboard must be completed.
• Wishlist feature must be turned on under Brand settings before creating shoppable content on the Storyly Dashboard.

Update Shopping Cart

This section explains how to update cart which allows users to add products to their shopping cart directly from Storyly widgets. Storyly SDK notifies your app when cart operations occur, giving you full control over the cart logic.

Setup Callback

The onUpdateCart callback is triggered when a user attempts to add items in the cart through the widget. Your app is responsible for handling the actual cart operation and informing Storyly SDK of the result.

🚧

Warning

You must call either approveCartChange or rejectCartChange with the event's responseId to inform Storyly SDK of the operation result. This allows Storyly SDK to update the UI accordingly (e.g., show success animation or error message).

const placementRef = useRef<StorylyPlacementMethods>(null);

<StorylyPlacement
  ref={placementRef}
  provider={provider}
  onUpdateCart={(event: PlacementCartUpdateEvent) => {
    // Call your cart API to check product availability
    const productId = event.item?.product.productId;

    // Notify SDK in case of success
    placementRef.current?.approveCartChange(event.responseId);

    // Notify SDK in case of fail
    // placementRef.current?.rejectCartChange(
    //   event.responseId,
    //   'Failed to add product to your cart',
    // );
  }}
/>

Track Product Analytics

This section explains how to track user behavior and integrate with your analytics platforms in the context of product. The product event represents various product-related events that can occur within the widget.

Product Analytic Events

This section shows the list of product analytic events and their description.

Setup Callback

The onProductEvent callback is triggered when a user takes any product related action. The event name is available via event.event.

<StorylyPlacement
  provider={provider}
  onProductEvent={(event) => {
    // Track product events
    console.log('Product event:', event.event);
  }}
/>

Hydrate Products

This section explains how to hydrate products with latest information from your own data. This ensures that prices, availability, and other product details are always up-to-date.

📘

Why use hydration?

• Show latest product data instead of daily updated product feed data
• Ensure real-time pricing accuracy
• Display current stock availability
• Show personalized product information
• Maintain consistency between your app and Storyly widgets

Setup Callback

The onHydration callback in StorylyPlacementProviderListener is triggered when Storyly widgets contain products that may need to be updated. Hydrate the provider with the latest data via hydrateProducts.

const placementListener: StorylyPlacementProviderListener = {
  onHydration: (event) => {
    // Extract product IDs
    const productIds = event.products
      .map((p) => p.productId)
      .filter((id): id is string => id != null);

    // Fetch latest product data
    const latestProducts: STRProductItem[] = ...;

    // Hydrate the data provider with updated products
    provider.hydrateProducts(latestProducts);
  },
};

const provider = useStorylyPlacementProvider(placementConfig, placementListener);

Product Wishlist

This section explains how to add products to wishlist directly from Storyly widgets. You can pre-populate the wishlist state and handle wishlist updates through dedicated callbacks.

Setup Callback

The onUpdateWishlist callback is triggered when a user adds or removes a product from their wishlist through the widget. Your app handles the actual wishlist operation and informs Storyly SDK of the result.

🚧

Warning

You must call either approveWishlistChange or rejectWishlistChange with the event's responseId to update the wishlist UI state in the widget.

<StorylyPlacement
  ref={placementRef}
  provider={provider}
  onUpdateWishlist={(event) => {
    try {
      switch (event.event) {
        case 'WishlistAdded':
          // Add to wishlist
          break;
        case 'WishlistRemoved':
          // Remove from wishlist
          break;
        default:
          // Check other events
          break;
      }

      // Notify SDK in case of success
      placementRef.current?.approveWishlistChange(event.responseId);
    } catch (e) {
      // Notify SDK in case of fail
      placementRef.current?.rejectWishlistChange(
        event.responseId,
        'Wishlist operation failed',
      );
    }
  }}
/>

Hydrate Wishlisted Products

This section explains how to hydrate products that are already in the user's wishlist. This ensures the wishlist state is correctly displayed in the widget UI.

// Check user's wishlist
const wishlistProducts: STRProductInformation[] = ...;

// Hydrate the wishlist
provider.hydrateWishlist(wishlistProducts);

Supplemental Product Feed Handling

Storyly allows you to integrate you multi-market product feeds depending on language or country. You can use this feature to show different products to users in different countries or with different languages.

You need to set the locale parameter on StorylyPlacementConfig to the end-user's locale in the IETF BCP 47 format.

const placementConfig: StorylyPlacementConfig = {
  token: '<your_placement_token>',
  locale: '<locale_for_end-user>',
};