# 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");
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://one-admax-organization.gitbook.io/one-admax-sdk/05.-flutter-plugin-guide/5-3..md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.