Banner

Banner ads occupy a small portion of the user interface, usually at the bottom or the top of the screen.

To start using banners, just call useBanner() hook. Use show() when you need the banner to be displayed.

Start creating a Banner

import {
  BannerPosition,
  BannerSize,
  useBanner,
  useRewarded,
  useRewardedEvents,
} from "react-native-xmediator";

export default function App() {
  const { create, hide, show, isShowing } = useBanner();

  // use effect to create when component mounts
  useEffect(() => {
    create({
      placementId: "<placement-id>",
      size: BannerSize.Phone,
      position: BannerPosition.Bottom,
    });
  }, []);

  return <>{/* your app code... */}</>;
}

tip

If you are using expo tabs, you can use useFocusEffect to fire on focus.

Banner sizes

Constant	Size (WxH)	Description
Phone	320x50	Size for banners used in phone devices
Tablet	728x90	Size for banners used in tablet devices
MREC	300x250	Size for IAB Medium Rectangle banners

Size is in DP for Android and Points for iOS.

Showing a banner

import {
  BannerPosition,
  BannerSize,
  useBanner,
  useRewarded,
  useRewardedEvents,
} from "react-native-xmediator";

export default function App() {
  const { create, hide, show, isShowing } = useBanner();

  // use effect to create when component mounts
  useEffect(() => {
    create({
      placementId: "<placement-id>",
      size: BannerSize.Phone,
      position: BannerPosition.Bottom,
    });
    show("<placement-id>");
  }, []);

  return <>{/* your app code... */}</>;
}

note

In this case we are showing the banner after creating it. You can also show on another event, just call show().

Hiding a banner

Use this function to indicate that the banner should not be visible. This will not interfere with the loading process, so if the banner is still being loaded it will continue to do so.

import {
  BannerPosition,
  BannerSize,
  useBanner,
  useRewarded,
  useRewardedEvents,
} from "react-native-xmediator";

export default function App() {
  const { create, hide, show, isShowing } = useBanner();

  // use effect to create when component mounts
  // if you are using expo tabs, you can use useFocusEffect to fire on focus.
  useEffect(() => {
    create({
      placementId: "<placement-id>",
      size: BannerSize.Phone,
      position: BannerPosition.Bottom,
    });
    show();
    return () => {
      // hide when component unmounts
      hide("<placement-id>");
    };
  }, []);

  return <>{/* your app code... */}</>;
}

note

You can also hide on another event, just call hide().

Built-in features

Banner autorefresh

After being displayed for some time, our banner fires a Load() call automatically to refresh its contents. You can configure this time through our Admin tool for each one of your banners.

Banner retry

Our banner has a built in auto retry for failed loads attempts. This means that when a banner fails to load, it will retry again until it loads successfully. Time between each retry attemp will increase using an exponential backoff. You should not add any retry logic on your end, as it may interefere with our retry behaviour.

Additional settings

Register ad callbacks

Every ad callback indicates the placement id of the banner that triggered the event.

Additional settings

Register ad callbacks

Every ad callback indicates the placement id of the banner that triggered the event.

useBannerEvents(
  {
    onLoaded: (placementId, loadResult) => {
      console.log("banner loaded", placementId, loadResult);
    },
    onClicked: (placementId) => {
      console.log("banner clicked", placementId);
    },
    onImpression: (placementId, impressionData) => {
      console.log("banner impression", placementId, impressionData);
    },
  },
  []
);

(Optional) Updating ad space

Before showing an ad, you can set an ad space name for the banner instance. This is useful for tracking purposes because it enables you to get performance insights for different ad spaces of your application.

const { setAdSpace } = useBanner();

setAdSpace("<placement-id>", "banner-ad-space");

(Optional) Manually refreshing a banner ad

Banner ads usually refresh their contents automatically, after a certain amount of time has passed. However, if you prefer to, you can manually refresh a banner's content by calling the load method:

const { load } = useBanner();

load("<placement-id>");

Setting a banner's position

const { setPosition } = useBanner();

setPosition("<placement-id>", BannerPosition.Top);

Banner sizes

Constant	Size (WxH)	Description
Phone	320x50	Size for banners used in phone devices
Tablet	728x90	Size for banners used in tablet devices
MREC	300x250	Size for IAB Medium Rectangle banners

Size is in DP for Android and Points for iOS.

Banner position

Constant	Description
Top	Places the banner at the top of the screen
Bottom	Places the banner at the bottom of the screen
Custom	Custom x,y position relative to top-left corner

Full Code example

In addition to the example below, you can see a fully implementation.

BannerTest.tsx

BannerTest.tsx

import { Button, Text, View } from "react-native";
import {
  useBanner,
  BannerSize,
  BannerPosition,
  useBannerEvents,
} from "react-native-xmediator";
import { useEffect } from "react";

const demoPlacementId = "<placement-id>";
export function BannerExample() {
  const {
    create: createBanner,
    hide: hideBanner,
    show: showBanner,
    isShowing,
    setPosition,
  } = useBanner();
  useEffect(() => {
    createBanner({
      placementId: demoPlacementId,
      size: BannerSize.Phone,
      position: BannerPosition.Bottom,
    });
    if (!isShowing) {
      showBanner(demoPlacementId);
    }
    return () => {
      hideBanner(demoPlacementId);
    };
  }, []);

  useBannerEvents(
    {
      onLoaded: (placementId, loadResult) => {
        console.log("[Demo App] banner loaded", placementId, loadResult);
      },
      onClicked: (placementId) => {
        console.log("[Demo App] banner clicked", placementId);
      },
      onImpression: (placementId, impressionData) => {
        console.log(
          "[Demo App] banner impression",
          placementId,
          impressionData
        );
      },
    },
    []
  );

  return (
    <View style={{ marginBottom: BannerSize.Phone.height }}>
      <Text>Banner Example</Text>
      <Button title="Show Banner" onPress={() => showBanner(demoPlacementId)} />
      <Button title="Hide Banner" onPress={() => hideBanner(demoPlacementId)} />
      <Button
        title="Set Banner on Bottom"
        onPress={() => setPosition(demoPlacementId, BannerPosition.Bottom)}
      />
      <Button
        title="Set Banner on Top"
        onPress={() => setPosition(demoPlacementId, BannerPosition.Top)}
      />
      <Text>Is Banner Showing: {isShowing ? "Yes" : "No"}</Text>
    </View>
  );
}