Banners place

Starting with 0.28.0 SDK version, banner display functionality has been added.

Initialization

Before showing Banners, make sure you initialized SDK (if it has not been initialized previously with other functionality). To see how to initialize SDK, check out How to get started section.

Important

Do not add horizontal padding to BannerCarousel component, this may cause visual bugs (e.g. banner cropping)

Banners can be added to your app using a simple code:

import React from 'react';
import {BannerCarousel, type BannerViewRef} from '@inappstory/react-native-sdk';

export function MyScreen() {
    const bannerRef = useRef<BannerViewRef>(null);

    const placeId = "default"

    return (
        <BannerCarousel
            placeId={placeId}
            ref={bannerRef}
            cornerRadius={16}
            onPlaceLoaded={(size, widgetHeight) => {
                console.log('Loaded', size, 'banners, height:', widgetHeight);
            }}
            onScroll={(index) => {
                console.log('Active banner index:', index);
            }}
        />
    );
}

Preloading

To warm up a banner place before the carousel is mounted, call preloadBannerPlace. It resolves to true once the place is loaded. You can optionally pass tags to filter content:

await storyManager.preloadBannerPlace('default');
await storyManager.preloadBannerPlace('default', ['tag1', 'tag2']);

Props

Prop	Type	Default value	Description
`placeId`	`string`	`'default'`	Banner place identifier
`shouldLoop`	`boolean`	`true`	Enable infinite scrolling (auto-repeat carousel)
`height`	`number`	`150`	The height of the component
`sideInset`	`number`	`16`	Indentation on both sides (applied if `leadingInset` / `trailingInset` are not specified)
`leadingInset`	`number`	`16`	Left indent
`trailingInset`	`number`	`16`	Right indent
`interItemSpacing`	`number`	`8`	Padding between banners
`cornerRadius`	`number`	`16`	Banner corner radius
`style`	`StyleProp<ViewStyle>`	—	Additional container styles
`onScroll`	`(index: number) => void`	—	Called when the active banner changes. `index` is the new active index
`onPlaceLoaded`	`(size: number, widgetHeight: number) => void`	—	Called after banners are loaded. `size` is the number of banners, `widgetHeight` is the height of the SDK widget

Ref-methods (BannerViewRef)

To call methods, pass a ref to the component:

const bannerRef = useRef<BannerViewRef>(null);
<BannerCarousel
    ref={bannerRef}
    // ...
/>

Method	Description
`refresh()`	Forcefully reloads banners from the server
`pause()`	Stops the carousel from auto-scrolling
`resume()`	Resumes autoscrolling of the carousel
`showNext()`	Switches the carousel to the next banner
`showPrevious()`	Switches the carousel to the previous banner
`showBannerWith(index: number)`	Switches the carousel to the banner with the specified index

An example of using ref methods

// Go to the next banner
bannerRef.current?.showNext();

// Go to banner with index 2
bannerRef.current?.showBannerWith(2);

// Reload banners (e.g., during pull-to-refresh)
bannerRef.current?.refresh();

// Pause when leaving the screen, resume when returning
useFocusEffect(
    useCallback(() => {
        bannerRef.current?.resume();
        return () => bannerRef.current?.pause();
    }, [])
);

Events

In addition to the onScroll / onPlaceLoaded props, the banner carousel reports global events. These are available anywhere in the app, not just within the component.

Call to action

A button (CTA) click inside a banner is delivered through storyLinkClickHandler with src set to CTASource.STORY_LIST. See more in Call To Action section.

storyManager.storyLinkClickHandler = (payload) => {
    // payload.src: CTASource.STORY_LIST for a banner click
    // payload.data.url: target link
    console.log('Banner CTA:', payload.data.url);
};

Banners event

onBannerWidgetEvent fires when an interactive widget inside the banner dispatches a user event (e.g. a click on a custom element). The payload is in event.body:

storyManager.onBannerWidgetEvent((event) => {
    const {bannerData, name, data} = event.body;
    console.log('Widget event from banner:', bannerData.id, name, data);
});

Structure of `event`

Field	Type	Description
`name`	`string`	The event name specified in the platform editor
`data`	`any`	Custom event data from the editor
`bannerData.id`	`string`	ID of the banner that generated the event
`bannerData.bannerPlace`	`string`	`placeId` of the carousel in which the banner is located
`bannerData.payload`	`string \| null`	Additional banner payload (optional)

Initialization​

Preloading​

Props​

Ref-methods (BannerViewRef)​

An example of using ref methods​

Events​

Call to action​

Banners event​

Structure of event​