---
title: Banner Ads
description: This guide explains how to integrate banner ads into a ReactNative app.
---

Banner Ad units display rectangular ads that occupy a portion of an app's layout.
They can refresh automatically after a set period of time.
This means users view a new ad at regular intervals, even if they stay on the same screen in your app.
They're also the simplest ad format to implement.

Banner Ad management in **React Native** is handled through the `BannerAdView` component from **react-native-cas**,
which represents an ad view used directly in JSX.

```tsx
import { BannerAdView, BannerAdSize } from 'react-native-cas';
```

CAS provides an option to enable `autoReload` to simplify your app logic. The `autoReload` is enabled by default, loading failures will trigger automatic retry attempts.
You should decide whether to enable `autoReload`, or manually manage each ad loading cycle in your code.

Also, banner ads support automatic `refreshInterval` regardless of the `autoReload` setting.

Below is a diagram showing the ad lifecycle and how `autoReload` and `refreshInterval` affect it.

<Image zoom src="/assets/Lifecycle-Banner-Ad.png" alt="Diagram" height="500" />


## Choose the Ad size
To add a banner ad, you need to specify the ad size. To do this, choose one of the `AdSize` from the list below:

1. **Adaptive banner** ads have a fixed aspect ratio for the maximum width. 
The adaptive size calculates the optimal height for that width with an aspect ratio similar to 320x50. 
By default, the full screen width will be used. You can limit width by specifying a `maxWidth` in the parameters.
```ts
const adSize = BannerAdSize.ADAPTIVE;
```

2. **Inline banner** ads have a desired width and a maximum height, useful when you want to limit the banner's height. 
Inline banners are larger and taller compared to adaptive banners. They have variable height, including Medium Rectangle size, 
and can be as tall as the device screen. Specify the `maxWidth` and `maxHeight` dimensions to limit the ad size.
```ts
const adSize = BannerAdSize.INLINE;
```

3. **Smart** selects the optimal dimensions depending on the device type. For mobile devices, it returns 320x50, while for tablets, it returns 728x90. In the UI, these banners occupy the same amount of space regardless of device type.
```ts
const adSize = BannerAdSize.SMART;
```

4. **Medium Rectangle** has a fixed size of 300x250.
```ts
const adSize = BannerAdSize.MREC;
```

5. **Leaderboard** has a fixed size of 728x90 and is allowed on tablets only.
```ts
const adSize = BannerAdSize.LEADERBOARD;
```

6. **Standard Banner** has a fixed size of 320x50 and is the minimum ad size
```ts
const adSize = BannerAdSize.BANNER;
```

## Show Ad View
`BannerAdView` is a React component and can be used like any other view.

```tsx
<BannerAdView 
  size={adSize}
  maxWidth={undefined}
  maxHeight={undefined}
  autoReload={true} 
/>
```

The ad content will be loaded automatically as soon as the view is mounted. 
Keep in mind that loading the ad takes some time, so avoid frequently unmounting and remounting the view.

While the ad is loading, the widget will have a size of (1x1). When the ad loads, the widget will automatically adopt the selected size.

The size of the container in which you place your ad must be at least as large as the AdSize. Any padding effectively decreases the size of your container.

## Ad content callbacks
`BannerAdView` supports lifecycle callbacks via props:

```tsx
const onAdLoadedCallback = useCallback((data: AdViewInfo) => {
  // Called when an ad is successfully loaded. 
  console.log('Banner Ad loaded', data);
}, []);

const onAdFailedCallback = useCallback((err: AdError) => {
  // Called when an ad load failed. 
  console.log('Banner Ad load failed', err);
}, []);

const onAdClickedCallback = useCallback(() => {
  // Called when a click is recorded for an ad.
  console.log('Banner Ad clicked');
}, []);

const onAdImpressionCallback = useCallback((info: AdContentInfo) => {
  // Called when an impression occurs on the ad.  
  console.log('Banner Ad impression', info);
}, []);

return <BannerAdView
  size={adSize}
  onAdViewLoaded={onAdLoadedCallback}
  onAdViewFailed={onAdFailedCallback}
  onAdViewImpression={onAdClickedCallback}
  onAdViewClicked={onAdImpressionCallback}
/>
```

<Info>
Read more about `AdContentInfo` structure in [Impression Level Data](ReactNative/Impression-Level-Data).
</Info>

## Ad refresh interval
The automatic refresh interval determines how often a new ad request is generated. 
Once the interval elapses, a new ad will automatically load and display.

The interval countdown runs only while the ad is visible on screen. 

Set a custom refresh interval longer than 10 seconds, or 0 to disable refresh option. 
Default refresh interval is 30 seconds.

Override the automatic refresh interval in `refreshInterval` property:
```tsx
<BannerAdView
  size={adSize}
  refreshInterval={30} // [!code highlight]
/>
```
Set `refreshInterval={0}` to disable. Default interval **30 seconds**.

## Manual reload Ad
When you want to manually control ad loading, use the `loadAd()` function on the `BannerAdViewRef` to retry loading with the same configuration.

```tsx
const bannerAdRef = useRef<BannerAdViewRef>(null); // [!code highlight]
const retryTimer = useRef<ReturnType<typeof setTimeout> | null>(null);

useEffect(() => {
  return () => {
    if (retryTimer.current) clearTimeout(retryTimer.current);
    retryTimer.current = null;
  };
}, []);

const onAdLoadedCallback = useCallback((data: AdViewInfo) => {
  if (retryTimer.current) {
    clearTimeout(retryTimer.current);
    retryTimer.current = null;
  }
}, []);

const onAdFailedCallback = useCallback((err: AdError) => {
  if (retryTimer.current) clearTimeout(retryTimer.current);
    retryTimer.current = setTimeout(() => {
      retryTimer.current = null;
      bannerAdRef.current?.loadAd(); // [!code highlight]
    }, 10000);
}, []);

return <BannerAdView 
  ref={bannerAdRef} 
  size={adSize} 
  autoReload={false}
  onAdViewLoaded={onAdLoadedCallback}
  onAdViewFailed={onAdFailedCallback}
/>
```

## BannerAdView props
<Property name="size" type="BannerAdSize" required>
  Represents the size of a banner ad.
</Property>

---

<Property name="maxWidth" type="number" optional>
  Maximum width for banner ad. Defaults to screen width.
</Property>

---

<Property name="maxHeight" type="number" optional>
  Maximum height for banner ad. Defaults to screen height.
</Property>
---

<Property name="autoReload" type="boolean" optional>
  If enabled, the ad will automatically retry loading the ad if an error occurs during the loading process. By default enabled.
</Property>

---

<Property name="refreshInterval" type="number" optional>
  Sets the refresh interval in seconds for displaying ads. Set `0` to disable automatic refreshing. 
  This automatic refresh worksregardless of the `autoReload` setting. By default 30 seconds.
</Property>

---

<Property name="placement" type="string" optional>
  An optional placement name for the ad instance that helps categorize and track statistics across different ad placements. Maximum 100 characters allowed for the placement name.
</Property>

---

<Property name="casId" type="string" optional>
  The unique identifier of the CAS content for each platform. Leave undefined to use the initialization identifier.
</Property>

---

<Property name="onAdViewLoaded" type="(info: AdViewInfo) => void" optional>
  Callback to be invoked when the ad content has been successfully loaded.
</Property>

---

<Property name="onAdViewFailed" type="(error: AdError) => void" optional>
  Callback to be invoked when the ad content fails to load.
</Property>

---

<Property name="onAdViewClicked" type="() => void" optional>
  Callback to be invoked when the ad content is clicked by the user.
</Property>

---

<Property name="onAdViewImpression" type="(info: AdContentInfo) => void" optional>
  Callback to be invoked when an ad is estimated to have earned money.
</Property>

## Complete example
- [Adaptive banner ad example](https://github.com/cleveradssolutions/CAS-ReactNative/blob/main/example/src/AdaptiveBannerExample.tsx)
- [Standard banner ad example](https://github.com/cleveradssolutions/CAS-ReactNative/blob/main/example/src/BannerExample.tsx)
- [Multi banners ad example](https://github.com/cleveradssolutions/CAS-ReactNative/blob/main/example/src/ScrolledAdViewExample.tsx)