> For the complete documentation index, see [llms.txt](https://one-admax-organization.gitbook.io/one-admax-sdk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://one-admax-organization.gitbook.io/one-admax-sdk/05.-flutter-plugin-guide/5-3..md).

# 5-3. 배너 광고 구현하기

## 사전 작업

{% content-ref url="/pages/HIpQCyVR8FOQSoTDab0B" %}
[05. Flutter-Plugin Guide](/one-admax-sdk/05.-flutter-plugin-guide.md)
{% endcontent-ref %}

## 배너 인스턴스 생성 <a href="#undefined-1" id="undefined-1"></a>

`OAMBannerWidget`을 이용하여 배너를 노출할 수 있습니다.\
[배너광고의 `PlacementId`는 ONE AdMax 콘솔에서 생성이 가능합니다.](/one-admax-sdk/02..md)

```java
class OAMBannerWidget extends StatefulWidget {
  final String placementId;
  final BannerSize bannerSize;
  late final AdMaxBanner _bannerPlugin;
  final BannerCallBackListener callback;
  final AnimType animType;
  final int? refreshTime;
  final int? networkTimeout;

  OamBannerWidget({
    super.key,
    required this.placementId,
    required this.callback,
    required this.bannerSize,
    this.animType = AnimType.NONE,
    this.refreshTime,
    this.networkTimeout,
  }) {
    _bannerPlugin = OAMBanner(callback);
  }
```

{% hint style="success" %}
`OamBannerWidget` 매개변수

* PlacementId: 사용하고자 하는 광고의 크기. (required)
* Callback: 배너 뷰를 배치해야 하는 위치. (required)
* BannerSize: 배너사이즈 (required)
* animType: 배너의 애니메이션 타입. (optional)
* refreshTime : 갱신주기. (optional)
* networkTimeout : 타임아웃 시간. (optional)
  {% endhint %}

## 배너 이벤트 리스너 <a href="#id-01.sdk-8" id="id-01.sdk-8"></a>

배너를 불러올 때 발생하는 이벤트에 대한 리스너를 설정합니다.&#x20;

```java
OamBannerWidget(
  callback: BannerCallBackListener(
    onLoaded: onLoaded,
    onLoadFailed: onLoadFailed,
    onClicked: onClicked
  ),
...
) 
```

## **배너 사이즈** <a href="#id-01.sdk-1" id="id-01.sdk-1"></a>

세가지 옵션이 있으며, ONE AdMax 콘솔에서 배너 광고 생성 시 지정한 값이 동일하게 세팅 되어 합니다.

```java
class BannerSize {
  final int width, height;
  final String? name;

  const BannerSize({required this.width, required this.height, this.name});

  static const BannerSize BANNER_320x50 =
      BannerSize(width: 320, height: 50, name: 'BANNER_320x50');
  static const BannerSize BANNER_320x100 =
      BannerSize(width: 320, height: 100, name: 'BANNER_320x100');
  static const BannerSize BANNER_300x250 =
      BannerSize(width: 300, height: 250, name: 'BANNER_300x250');

  Size get toSize => Size(width.toDouble(), height.toDouble());
}
```

| 크기      | 상수                         |
| ------- | -------------------------- |
| 320x50  | BannerSize.BANNER\_320x50  |
| 300x250 | BannerSize.BANNER\_300x250 |
| 320x100 | BannerSize.BANNER\_320x100 |

```java
OAMBannerWidget(
  bannerSize : BannerSize.BANNER_320x50
  ...
)
```

## **배너 선택 사항** <a href="#id-01.sdk-2" id="id-01.sdk-2"></a>

### **배너 갱신 주기**(선택사항) <a href="#id-01.sdk-2-1" id="id-01.sdk-2-1"></a>

설정가능 범위는 15\~300초이며, -1로 설정 시 갱신되지 않습니다.

```java
OAMBannerWidget(
  refreshTime: 60,
  ...
) // default 60 sec
```

### **배너 네트워크 스케줄 타임아웃**(선택사항) <a href="#id-01.sdk-3" id="id-01.sdk-3"></a>

배너 광고 로딩 시 각 네트워크(미디에이션 업체)별로 타임아웃 시간을 주어 해당 시간 안에 광고를 받지 못할 경우, 다음 네트워크로 넘어가게 됩니다.

```java
OAMBannerWidget(
  networkTimeout: 30,
  ...
) // default 60 sec
```

### 애니메이션 효과 설정 (선택사항) <a href="#undefined-2" id="undefined-2"></a>

배너가 노출될 때의 애니메이션을 설정합니다. (기본값: `AnimType.NONE`) 총 7가지의 애니메이션을 설정할 수 있습니다.

```java
OAMBannerWidget(
  animType: AnimType.TOP_SLIDE
  ...
) // Defaults to AnimType.NONE
```

아래 표는 애니메이션 타입의 종류가 나와 있습니다.

| 상수                      | 설명               |
| ----------------------- | ---------------- |
| `AnimType.NONE`         | 애니메이션 없음 (기본값)   |
| `AnimType.FADE_IN`      | 페이드 인 애니메이션      |
| `AnimType.SLIDE_LEFT`   | 왼쪽으로 슬라이드 애니메이션  |
| `AnimType.SLIDE_RIGHT`  | 오른쪽으로 슬라이드 애니메이션 |
| `AnimType.TOP_SLIDE`    | 위쪽으로 슬라이드 애니메이션  |
| `AnimType.BOTTOM_SLIDE` | 아래쪽으로 슬라이드 애니메이션 |
| `AnimType.CIRCLE`       | 배너 회전 애니메이션      |

### 배너 배경색 채우기 (선택사항) <a href="#undefined-3" id="undefined-3"></a>

배너 뷰의 빈 공간에 배경색을 채울 수 있습니다. (기본값: true)

```java
OAMBannerWidget(
  isEnabledAutoBgColor: true
  ...
) // Defaults to true
```

### 배너 미디에이션 <a href="#id-01.sdk-9" id="id-01.sdk-9"></a>

배너 광고는 일부 미디에이션에 대한 사용을 지원합니다. 배너의 load() 호출 이전에 setting 되어야 합니다.

```java
class CaulyExtras extends BannerMediationExtras {
  bool? isEnableLock;
  bool? isEnableDynamicReloadInterval;
  int? reloadInterval;
  int? threadPriority;
}

class MezzoExtras extends BannerMediationExtras {
  int? ageLevel;
  bool? isEnableBackgroundCheck;
  String? storeUrl;

  MezzoExtras({this.ageLevel, this.isEnableBackgroundCheck, this.storeUrl});
}


```

#### Cauly

| 변수                            | 설명                                                                                                      |
| ----------------------------- | ------------------------------------------------------------------------------------------------------- |
| isEnableLock                  | 잠금 화면에서 노출 가능 여부. default false.                                                                        |
| isEnableDynamicReloadInterval | 카울리 다이나믹 배너 갱신 사용 여부. default true.                                                                     |
| reloadInterval                | 카울리 배너 갱신 주기. range: 10\~120. default 20s. CAULY\_ENABLE\_DYNAMIC\_RELOAD\_INTERVAL를 false로 설정 후에 사용가능. |
| threadPriority                | 카울리 스레드 우선순위 지정. range: 1\~10. default 5.                                                               |

#### Mezzo

| 변수                      | 설                                                                          |
| ----------------------- | -------------------------------------------------------------------------- |
| ageLevel                | 유저 나이 정보, default -1. 알 수 없음 = -1, 어린이(13세 미만) = 0, 청소년 및 성인(만 13세 이상) = 1 |
| isEnableBackgroundCheck | 백그라운드 갱신 사용 여부.                                                            |
| storeUrl                | 앱 스토어 URL                                                                  |

## 배너 샘플 코드 <a href="#undefined-4" id="undefined-4"></a>

```java
@override
Widget build(BuildContext context) {
  final state = ref.watch(bannerDetailProvider);

  return Scaffold(
      appBar: AppBar(
        title: const Text('Banner'),
        automaticallyImplyLeading: false,
      ),
      body: OAMBannerWidget(
          placementId: banner.placementId,
          callback: BannerCallBackListener(
              onLoaded: onLoaded,
              onLoadFailed: onLoadFailed,
              onClicked: onClicked),
          bannerSize: banner.bannerSize,
          bannerMediationExtras: banner.bannerMediationExtras);
  );
}

void onClicked() {
  debugPrint("onClicked");
}

void onLoadFailed(OAMError admaxError) {
  debugPrint("OnBannerAdReceiveFailed");
}

void onLoaded() {
  debugPrint("onLoaded");
}
```