Story Block (React Native)

For android:

StoryBlock is a heavy object containing multiple instances of the player, Heavy-lifting UI elements, and intensive background tasks, Beware that the recommended number of the StoryBlock being used in a single screen is 1. However, in a wide range of new Android devices, 2 instances might work alright. Any number of StoryBlock above this limitation is not recommended by the Firework team and is not supported.

There are four source types of the story block:

• Discover

• Channel

• Playlist

• Dynamic Content

• Hashtag Playlist

• Sku

• Single Content

Integration

import {
  StoryBlock,
} from 'react-native-firework-sdk';

// discover
<StoryBlock
  style={{ height: 400 }} 
  source="discover" 
/>

// channel
<StoryBlock 
  style={{ height: 400 }} 
  source="channel" 
  channel="your encoded channel id"
/>

// playlist
<StoryBlock 
  style={{ height: 400 }} 
  source="playlist" 
  playlist="your encoded playlist id"
  channel="your encoded channel id"
/>

// dynamic content
<StoryBlock 
  style={{ height: 400 }} 
  source="dynamicContent" 
  channel="your encoded channel id"
  dynamicContentParameters={{
    '<cohort key>': ['<cohort value1>', '<cohort value2>'],
  }}
/>

// hashtag playlist
<StoryBlock 
  style={{ height: 400 }} 
  source="hashtagPlaylist"
  channel="your encoded channel id"
  hashtagFilterExpression="<hashtag filter expression>"
/>

<StoryBlock 
  style={{ height: 400 }} 
  source="sku"
  channel="your encoded channel id"
  productIds={['prodct_id_1', 'product_id_2']}
/>

<StoryBlock 
  style={{ height: 400 }} 
  source="singleContent"
  channel="your encoded vide or live stream id"
  productIds={['prodct_id_1', 'product_id_2']}
/>

Please refer to the Encoded IDs help article to learn about how to find your encoded channel ID, playlist ID.

Story block loading result callback

StoryBlock component provides onStoryBlockLoadFinished prop for setting video feed loading result callback.

<StoryBlock
  style={{ height: 400 }}
  source="discover"
  onStoryBlockLoadFinished={(error) => {
  /**
    * if error is undefined, it means that story block loaded successfully. 
    * Otherwise, it means that story block failed to load.
    */
  console.log('onStoryBlockLoadFinished error', error);
  }}
/>

Story block configuration

Please refer to Player configurations (React Native).

Enable PiP(Picture in Picture)

Please refer to Enable PiP(Picture in Picture).

Manually manage story block appearance

Why manual appearance management is needed

By default the SDK tries to detect viewport changes automatically through the underlying native view's lifecycle. In a React Native app this auto-detection is limited and is not reliable in the following common cases:

• JS-based screen navigation. Only @react-navigation/native-stack (which is backed by a real UINavigationController / FragmentManager) reliably triggers the native view controller / fragment appearance callbacks the SDK depends on. JS-based navigators such as @react-navigation/stack, bottom-tabs, and drawer keep the same root native view controller / activity and only swap the React tree, so the native SDK does not receive an "appeared" / "disappeared" signal when the user navigates between screens.

• Scrolling inside a list. When a story block is embedded in a ScrollView, FlatList, SectionList, or any other custom scroll container, the native view stays attached to the same window and parent view as the user scrolls it on/off screen. The native SDK has no portable way to observe that the host RN list has scrolled the story block out of (or back into) the visible area, so it cannot pause/resume on its own.

In these cases set storyBlockConfiguration.handleAppearanceManually to true and drive the viewport state from the host app.

Driving viewport state from the host app

When storyBlockConfiguration.handleAppearanceManually is set to true, the SDK will not perform any automatic viewport detection. The host app is responsible for notifying the story block of viewport changes by calling onViewportEntered and onViewportLeft on the StoryBlock ref:

• When the story block leaves the viewport, call onViewportLeft and the story block will pause playback.

• When the story block re-enters the viewport, call onViewportEntered and the story block will resume the state it was in before leaving.

import { useRef } from 'react';
import { StoryBlock, type IStoryBlockMethods } from 'react-native-firework-sdk';

const storyBlockRef = useRef<IStoryBlockMethods>(null);

<StoryBlock
  ref={storyBlockRef}
  style={{ height: 400 }}
  source="discover"
  storyBlockConfiguration={{
    handleAppearanceManually: true,
  }}
/>

Below are two common scenarios for driving these callbacks.

Example 1: The story block fills the whole screen

If the story block occupies the entire screen, you can use React Navigation's useFocusEffect to detect when the screen becomes focused or unfocused, and forward those events to the story block:

import { useCallback, useRef } from 'react';
import { useFocusEffect } from '@react-navigation/native';
import { StoryBlock, type IStoryBlockMethods } from 'react-native-firework-sdk';

const StoryBlockScreen = () => {
  const storyBlockRef = useRef<IStoryBlockMethods>(null);

  useFocusEffect(
    useCallback(() => {
      storyBlockRef.current?.onViewportEntered();

      return () => {
        storyBlockRef.current?.onViewportLeft();
      };
    }, [])
  );

  return (
    <StoryBlock
      ref={storyBlockRef}
      style={{ flex: 1 }}
      source="discover"
      storyBlockConfiguration={{
        handleAppearanceManually: true,
      }}
    />
  );
};

Example 2: The story block is embedded in a FlatList

If the story block is rendered as one of many items inside a FlatList, you need to consider two factors together:

1. Whether the story block's row is currently visible inside the list (tracked via onViewableItemsChanged).

2. Whether the screen that hosts the list is currently focused (tracked via useFocusEffect). The list item may still be "viewable" within the list while the user has navigated to another screen, in which case the story block should still be paused.

Track each condition and derive the combined viewport state. A useEffect keyed on the derived value will fire onViewportEntered / onViewportLeft only when the combined state changes:

import { useCallback, useEffect, useRef, useState } from 'react';
import { FlatList, type ViewToken } from 'react-native';
import { useIsFocused } from '@react-navigation/native';
import { StoryBlock, type IStoryBlockMethods } from 'react-native-firework-sdk';

const STORY_BLOCK_ITEM_KEY = 'story-block';

const viewabilityConfig = { itemVisiblePercentThreshold: 50 };

const FeedScreen = () => {
  const storyBlockRef = useRef<IStoryBlockMethods>(null);
  const isScreenFocused = useIsFocused();
  const [isItemVisible, setIsItemVisible] = useState(false);

  const onViewableItemsChanged = useCallback(
    ({ viewableItems }: { viewableItems: ViewToken[] }) => {
      setIsItemVisible(
        viewableItems.some((item) => item.key === STORY_BLOCK_ITEM_KEY)
      );
    },
    []
  );

  const isInViewport = isScreenFocused && isItemVisible;

  useEffect(() => {
    if (isInViewport) {
      storyBlockRef.current?.onViewportEntered();
    } else {
      storyBlockRef.current?.onViewportLeft();
    }
  }, [isInViewport]);

  return (
    <FlatList
      data={data}
      viewabilityConfig={viewabilityConfig}
      onViewableItemsChanged={onViewableItemsChanged}
      renderItem={({ item }) => {
        if (item.key === STORY_BLOCK_ITEM_KEY) {
          return (
            <StoryBlock
              ref={storyBlockRef}
              style={{ height: 400 }}
              source="discover"
              storyBlockConfiguration={{
                handleAppearanceManually: true,
              }}
            />
          );
        }
        return renderOtherItem(item);
      }}
    />
  );
};

Reference

StoryBlock

IStoryBlockProps