Skip to main content

Banners

The Banners Plugin for @inappstory/js-sdk provides a simple way to display banner placements on your website.

Table of Contents​

  1. Overview
  2. Requirements
  3. Integration
  4. Initialization
  5. Usage
  6. Customization
  7. Events
  8. Tips & Best Practices
  9. Errors & Debugging
  10. FAQ

Overview​

The Banners plugin allows you to:

  • Embed banners.
  • Manage display via API or InAppStory Console.
  • Integrate custom sliders (e.g., Swiper.js).
  • React to loading, error, and user interaction events.

Requirements​

PlatformCompatibility
JavaScript SDK@inappstory/js-sdk@>=3.7.0
SSR Support❌ No support
TypeScript Support✅ Full
BrowsersModern ES6+ browsers

Integration​

Via NPM​

npm install @inappstory/js-sdk
import { InAppStoryManager } from "@inappstory/js-sdk";
import IasBannersPlugin from "@inappstory/js-sdk/plugins/banners";

InAppStoryManager.use(IasBannersPlugin);
const inAppStoryManager = new InAppStoryManager(config);
/* You can now use inAppStoryManager.banners to access the banners API */

Via CDN​

The plugin is built into the SDK bundle

<script>
const inAppStoryManager = new IAS.InAppStoryManager(config);
/* You can now use inAppStoryManager.banners to access the banners API */
</script>

Initialization​

The first step in SDK setup is to create and place the <div id="your-mount-selector"> container in the body of your markup.
The <div> tag in this section identifies the location on the page where the js-sdk API will place the banners widget.

const bannerPlace = inAppStoryManager.banners.mountBannerCarousel(
  "#your-mount-selector", {
      placeId: "{your-place-id-from-ias-console}",
      appearance: {
        autoplay: true,
        gap: 16,
        banner: {
          borderRadius: 8
        }
      }
  }
);

❗ placeId must match the ID set in the InAppStory Console.

Example​

<!DOCTYPE html>
<head>
  <meta charset="utf-8" />
  <script
      defer
      src="https://cdn.domain-placeholder/sdk/js-sdk-version-placeholder/dist/js/IAS.js"
    ></script>
</head>
  <body>
    <div id="ias-banner-place-widget"></div>
    <script>
      document.addEventListener("DOMContentLoaded", () => {
        const inAppStoryManager = new IAS.InAppStoryManager({
          apiKey: "{project-integration-key}",
        });

         const bannerPlace = inAppStoryManager.banners.mountBannerCarousel(
                        "#ias-banner-place-widget", {
                            placeId: bannerPlaceId,
                            appearance: {}
                        }
                    );
      })
    </script>
  </body>
</html>

Usage​

Update Appearance​

You can update the appearance settings

bannerPlace.updateAppearance({
  gap: 24,
  navigation: { enabled: false },
  banner: {
    borderRadius: 16
  },
});

Resume/Pause Autoplay​

You can control the default slider implementation

bannerPlace.resume();
bannerPlace.pause();

Reload Banners​

You can reload the list of banners

await bannerPlace.reload();

Run transition to next slide.

bannerPlace.showNext();

Run transition to previous slide.

bannerPlace.showPrevious();

Run transition to the slide by index

bannerPlace.showByIndex(index: number, speed?: number);

Destroy​

After finishing using it, you should properly destroy the banner place to avoid memory leaks and other possible problems

bannerPlace.destroy();

Access Banner List​

You can access the list of banners for full customization

const banners = bannerPlace.banners;
banners.forEach(b => console.log(b.name));

Customization​

Appearance settings​

The following appearance settings are available for the banner place:

ParameterTypeDescriptionDefault Value
loopbooleanEnables continuous loop mode (rearranges slides).true
gapnumberSpacing between slides (in pixels).16
autoplaybooleanEnables automatic slide playback.false
navigationobjectNavigation settings.—
↳ enabledbooleanEnables default navigation (prev/next buttons).true
paginationobjectPagination settings.—
↳ enabledbooleanEnables default pagination (slide indicators/dots).true
bannerobjectBanner settings.—
↳ borderRadiusnumberBanner corner rounding (in pixels).16
directionstringList direction. Possible values: row, column. Since 3.8.0.row
allowTouchMovebooleanToggles touch on the list. Since 3.8.0true

Note:
Nested properties (navigation.enabled, pagination.enabled, banner.borderRadius) are marked with ↳.

Custom Navigation Controls​

You can create your own buttons and control the banner slider:

const nextBtn = document.getElementById('next-btn');
const prevBtn = document.getElementById('prev-btn');

nextBtn.addEventListener('click', () => {
  bannerPlace.showNext();
});

prevBtn.addEventListener('click', () => {
  bannerPlace.showPrevious();
});

Custom Pagination Indicators​

Render your own pagination dots or numbers, and synchronize them with the banner state:

const paginationContainer = document.getElementById('pagination');

function renderPagination() {
  paginationContainer.innerHTML = '';
  for (let i = 0; i < bannerPlace.paginationBullets; i++) {
    const dot = document.createElement('button');
    dot.textContent = (i + 1).toString();
    dot.classList.toggle('active', i === bannerPlace.activeIndex);

    dot.addEventListener('click', () => {
      bannerPlace.showByIndex(i);
    });

    paginationContainer.appendChild(dot);
  }
}

renderPagination();

// Update pagination UI on banner change
bannerPlace.on('loadEnd', renderPagination);
bannerPlace.on('activeIndexChange', renderPagination);

Events​

loadStart​

Description: Triggered when loading starts.

No payload.

loadEnd​

Description: Triggered when loading ends.

No payload.

loadError​

Description: Triggered when loading fails.

No payload.

activeIndexChange​

Description: Triggered when the active banner changes.

Payload:

FieldTypeDescription
—numberIndex of the currently active banner.

autoplayTimeLeft​

Description: Triggered before transition to the next slide after the duration has elapsed.

No payload.

autoplayTimerTick​

Description: Triggered while autoplay timer tick.

Payload:

FieldTypeDescription
bannerIndexnumberBanner index in banner place.
currentTimenumberCurrent progress.
totalTimenumberTotal duration.
percentsnumberCurrent progress in percents.

showBanner​

Description: Triggered when the banner is in the viewport and started.

Payload:

FieldTypeDescription
idstringBanner identifier.
bannerPlacestringBanner place identifier.
payloadstring?Optional additional banner payload data.

showBannerFailed​

Description: Triggered when the banner is in the viewport and error occurs on start.

Payload:

FieldTypeDescription
idstringBanner identifier.
bannerPlacestringBanner place identifier.
errorErrorError that occurred.
payloadstring?Optional additional banner payload data.

bannerWidget​

Description: Triggered when interacting with banner widgets.

Payload:

FieldTypeDescription
idstringBanner identifier.
bannerPlacestringBanner place identifier.
widgetEventNamestringName of the widget event (e.g., "click").
widgetDataRecord<string, any>Arbitrary data related to the widget event.
payloadstring?Optional additional banner payload data.
bannerPlace.on("loadEnd", () => console.log("Loaded"));

Tips and Best Practices​

  • Always call destroy() to properly free resources.
  • Connect third-party sliders via setSliderController() for full UI/UX control.
  • Use unique placeId values for A/B testing and analytics.

Errors and Debugging​

ProblemCauseSolution
Banners not showingInvalid placeId or mount selectorCheck mount selector and InAppStory console and ensure correct placeId
loadError triggeredNetwork issue or no bannersValidate InAppStory console content and connection
banners.length === 0No banners configuredFill banner place in the InAppStory console

FAQ​

Banners are not loading, what should I do?​

Check the browser console. Ensure the placeId is correct and that the banner place contains active content.

Can I use multiple banner places on the same page?​

Yes. You can create multiple BannerPlace instances with different selectors values.