Skip to content

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.

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

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

Our banner has an 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.

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);
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.

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