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);
            }}
        />
    );
}

Props

Prop	Type	Default value	Discription
`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`	`24`	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, you need to pass ref to the component.

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

Method	Discription
`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
await bannerRef.current?.showNext();

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

// Reload banners (e.g., during pull-to-refresh)
await 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 emits global events that can be tracked via storyManager.on(...). Both events are available for subscription anywhere in the app, not just within the component.

Call to action

handleCTA - fires when the user clicks a button (CTA) inside the banner. See more in Call To Action section

storyManager.on('handleCTA', (event) => {
    // event.url    — target link
    // event.action — CTA source ('deeplink' for a banner click)
    console.log('Banner CTA:', event.url, event.action);
});

Banners event

bannerWidgetEvent- fires when an interactive widget inside the banner dispatches a user event (e.g. a click on a custom element).

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

Structure of `event`

Поле	Тип	Описание
`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​

Props​

Ref-methods (BannerViewRef)​

An example of using ref methods​

Events​

Call to action​

Banners event​

Structure of event​