Shopping

Callbacks

Firework SDK triggers shopping callbacks whenever appropriate to ask for product details updates, custom cart page and cart icon style, etc. It's up to the host app developer to inject custom callbacks and return feedback in the callback body. Firework SDK does not keep any state, but asks for updates via callbacks.

onUpdateProductDetails

Triggered when the video will be shown. The host app can return a Product list to update the latest product information.

FireworkSDK.getInstance().shopping.onUpdateProductDetails = async (event) => {
  let products: Product[] = []
  for (let productId of event.productIds) {
    let product: Product = { productId: productId };
    product.name = 'latest-product-name';
    product.description = 'latest-product-description';
    products.push(product);
  }

  return products;
};

onWillDisplayProduct(Only supported on iOS)

Triggered when the product will be shown. The host app can return a ProductInfoViewConfiguration object to configure configure "Add to cart" button.

FireworkSDK.getInstance().shopping.onWillDisplayProduct = async (_) => {
  /**
   * You could return the style of "Add to cart" button.
   * But the style only applies to iOS side.
   * If you return empty object, We will use default style of "Add to cart" button on the iOS side.
   * And you could use style.xml to customize the styles of "Add to cart" button on the Android side.
   * For more detail, please refer to https://docs.firework.tv/react-native-sdk/integration-guide/reference/models/productinfoviewconfiguration
  */
  return {
    addToCartButton: {
     backgroundColor: '#c0c0c0',
     textColor: '#ffffff',
     fontSize: 16,
    },
  };
};

onShoppingCTA

Triggered when the user clicks the shopping CTA button. And we support customizing the shopping CTA button text to "Add to cart" or "Shop now" on the iOS side. The usage codes are:

FireworkSDK.getInstance().shopping.productInfoViewConfiguration = {
  ctaButton: {
    text: 'addToCart', // 'addToCart' or 'shopNow'. Only supported on iOS.
  },
};

And host app can return a ShoppingCTAResult object to tell FireworkSDK the result. The event type is ShoppingCTAEvent.

FireworkSDK.getInstance().shopping.onShoppingCTA = async (event: ShoppingCTAEvent) => {
  if (Platform.OS === 'android') {
    await FireworkSDK.getInstance().navigator.popNativeContainer();
  } else {
    // start floating player
    const result = await FireworkSDK.getInstance().navigator.startFloatingPlayer();
    if (!result) {
      /* when the result is false, the current fullscreen player may not
       * enable the floating player. In that case, we could call the 
       * following method to close the fullscreen player.
       */
      await FireworkSDK.getInstance().navigator.popNativeContainer();
    }
  }
  
  // The host app handles the process of adding to cart
  
  // Navigate to the RN cart page of the host app.
  navigation.navigate('Cart');
  
  return {
    res: 'success',
  };
}

onAddToCart(Deprecated)

Please use onShoppingCTA instead.

Triggered when the user clicks the "Add to cart" button. The host app can return an AddToCartResult object to tell FireworkSDK the result of adding to the cart.

FireworkSDK.getInstance().shopping.onAddToCart = async (_) => {
  // The host app handles the process of adding to cart
 
  // return the result of adding to cart
  return {
    res: 'success',
    tips: 'Add to cart successfully',
  };
};

FireworkSDK.getInstance().shopping.onAddToCart = async () => {
  
  if (Platform.OS === 'ios') {
    // we only support starting floating player on the iOS side
    const result = await FireworkSDK.getInstance().navigator.startFloatingPlayer();
    if (!result) {
      /* when the result is false, the current fullscreen player may not
       * enable the floating player. In that case, we could call the
       * following method to close the fullscreen player.
       */
      await FireworkSDK.getInstance().navigator.popNativeContainer();
    }
  } else {
      await FireworkSDK.getInstance().navigator.popNativeContainer();
  }
  
  // The host app handles the process of adding to cart
  
  // Navigate to the RN cart page of the host app.
  navigation.navigate('Cart');
  
  /* returning null indicates SDK doesn't need to
   * show the result message of adding to cart to users.
   */
  return null;
};

onClickCartIcon

Triggered when users click the cart icon. if the host app returns NewNativeContainerProps in this callback, we will push a native container with the props when users click the cart icon. And we will render your app component with the props in the new native container.

Integration Steps

1. Set your app component name through FireworkSDK.getInstance().appComponentName . The app component name is the first parameter you pass to AppRegistry.registerComponent. And you could set your app component name after calling AppRegistry.registerComponent. The sample file is index.tsx.

2. Return NewNativeContainerProps in onClickCartIcon callback. The sample file is HostAppShoppingService.tsx.

3. Handle NewNativeContainerProps in your app component. The sample file is App.tsx. The version that the sample codes use for react-navigation is 6.x. You need to handle the dynamic initialRouteName and initialParams based on the version you use.

onCustomClickCartIcon

If you don't want to handle hybrid navigation when users click the cart icon, you could set onCustomClickCartIcon instead of onClickCartIcon. As follows, you could start the floating player(only supported on iOS) or close the player and push the RN cart page in the RN navigation stack when users click the cart icon.

FireworkSDK.getInstance().shopping.onCustomClickCartIcon = async () => {
  
  if (Platform.OS === 'ios') {
    // we only support starting floating player on the iOS side
    const result = await FireworkSDK.getInstance().navigator.startFloatingPlayer();
    if (!result) {
      /* when the result is false, the current fullscreen player may not
       * enable the floating player. In that case, we could call the
       * following method to close the fullscreen player.
       */
      await FireworkSDK.getInstance().navigator.popNativeContainer();
    }
  } else {
      await FireworkSDK.getInstance().navigator.popNativeContainer();
  }
  
  // Navigate to the RN cart page of the host app.
  navigation.navigate('Cart');
};

onClickCartIcon vs onCustomClickCartIcon

You could set onClickCartIcon or onCustomClickCartIcon callback to handle the cart icon click event. As above, onCustomClickCartIcon is easier to integrate than onClickCartIcon. But the two callbacks interact differently.

For onClickCartIcon, we show a new native container to embed the React Native cart page. As the player is a native page, we need to handle hybrid navigation when implementing the onClickCartIcon callback.

For onCustomClickCartIcon, you could call FireworkSDK.getInstance().navigator.popNativeContainer to close the player and navigate to the React Native cart page using React Native navigation library, such as react-navigation.

If you accept closing the player when users click the cart icon, we recommend using onCustomClickCartIcon instead of onClickCartIcon.

Props

cartIconVisible

Defaults to true. You can hide the cart icon by setting this property to false.

Method

setCartItemCount

// The host app call this method to sycn cart item count to Firework SDK.
FireworkSDK.getInstance().shopping.setCartItemCount(cartItemCount);

Reference

VideoShopping