> For the complete documentation index, see [llms.txt](https://adpopcornssp.gitbook.io/ssp-sdk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://adpopcornssp.gitbook.io/ssp-sdk/undefined-2/extra-guide/undefined-1/ads/undefined.md).

# 배너 광고

## 1. 배너 뷰 인스턴스 생성

### 1) xml 방식

배너 광고가 노출될 뷰를 사용 중이신 Layout.xml 파일에 추가합니다.

```xml
<LinearLayout 
	android:layout_width="match_parent" 
	android:layout_height="wrap_content" 
	android:background="#ffffff" 
	android:orientation="vertical">	
		<!-- Banner View -->			
		<com.oneadmax.global.ssp.part.banner.AdPopcornSSPBannerAd
			android:layout_width="match_parent"	
			android:layout_height="wrap_content" 
			android:layout_gravity="center_horizontal"	
			android:id="@+id/banner"/>
</LinearLayout>
```

xml 에서 형성된 인스턴스를 추가 합니다.

```java
private AdPopcornSSPBannerAd bannerAd; 

@Override 
protected void onCreate(Bundle savedInstanceState) { 
      bannerAd = (AdPopcornSSPBannerAd)findViewById(R.id.banner);
}
```

### 2) 코드 방식

아래의 코드를 추가하여 인스턴스를 생성합니다.

```java
private AdPopcornSSPBannerAd bannerAd; 

@Override 
protected void onCreate(Bundle savedInstanceState) { 
      bannerAd = new OnestoreBannerAd(context);
}
```

## 2. 배너 Placement Id 설정

아래 코드를 추가하여 배너광고의 PLACEMENT ID 를 설정합니다. 배너광고 PLACEMENT ID 는 애[드팝콘 SSP 페이지](https://www.console.adpopcorn.com/)에서 생성이 가능합니다.

```java
bannerAd.setPlacementId("배너광고_PLACEMENT_ID");
```

## 3. 배너 광고 요청 사이즈 설정 (Default: 320x50)

배너 사이즈는 3 가지 옵션으로 AdSize enum class 로 전달하며 사이즈는 AdSize.BANNER\_320x50 / AdSize.BANNER\_300x250 / AdSize.BANNER\_320x100으로 설정 가능합니다.

<mark style="color:orange;">**주의> AdSize.BANNER\_ADAPTIVE\_SIZE의 경우 네이버 애드 매니저 이미지형 배너 전용 사이즈 입니다. 해당 사이즈 사용하고자 하는 경우에는 사업팀에 문의해 주시기 바랍니다.**</mark>

```java
bannerAd.setAdSize(AdSize.BANNER_320x50);
```

## 4. 배너 광고 요청 갱신 주기 설정 (Default: 60초)

AdPopcornSSP 에서 제공하는 배너 광고에 대한 갱신주기를 설정합니다. 설정가능 범위는 15\~300초 사이이며 -1 로 설정 시 자동으로 갱신되지 않습니다.

```java
bannerAd.setRefreshTime(50);
```

## 5. 네트워크 스케쥴 타임아웃 설정 (Default: 5초)

AdPopcornSSP 에서 제공하는 배너 광고에 대한 네트워크 스케쥴 타임아웃을 설정합니다.

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

```java
bannerAd.setNetworkScheduleTimeout(10);
```

## 6. 배너 광고 애니메이션

AdPopcornSSP 에서 제공하는 배너 광고는 총 7가지의 애니메이션을 추가할 수 있습니다.

* BannerAnimType.NONE: 배너 애니메이션 없음 (기본)
* BannerAnimType.FADE\_IN : 페이드 인 애니메이션
* BannerAnimType.SLIDE\_LEFT : 왼쪽으로 슬라이드 애니메이션
* BannerAnimType.SLIDE\_RIGHT: 오른쪽으로 슬라이드 애니메이션
* BannerAnimType.TOP\_SLIDE : 윗쪽으로 슬라이드 애니메이션
* BannerAnimType\_BOTTOM\_SLIDE : 아래쪽으로 슬라이드 애니메이션
* BannerAnimType\_CIRCLE : 배너 회전 애니메이션

```java
bannerAd.setBannerAnimType(BannerAnimType.SLIDE_LEFT);
```

## 7. 배너 배경색 채우기

AdPopcornSSP 에서 제공하는 배너 광고는 배너 광고가 나오는 뷰의 빈 공간에 배경색을 채울 수 있습니다. (기본 설정은 배경채우기로 설정되어 있습니다.)

```java
bannerAd.setAutoBgColor(false);     // Defaults 'true'
```

## 8. 배너 뷰 광고 요청

배너 광고 노출을 원하는 시점에 <mark style="color:red;">`loadAd()`</mark> API 를 호출하여 서버에 광고를 요청합니다.

```java
bannerAd.loadAd();
```

<mark style="color:orange;">loadAd 호출에 대한 결과로 광고 수신에 실패한 경우에는 loadAd 재호출을 하시면 안됩니다. 과도한 광고 요청 api 호출은 block 사유가 됩니다.</mark>

## 9. 배너 뷰 광고 중단

배너 광고 노출을 더 이상 하고 싶지 않은 시점에 호출합니다. 일반적으로 배너가 노출된 activity 나 fragment 가 destroy 할 때 호출합니다

{% hint style="danger" %}
단 onPause 상태 진입시 stopAd 를 호출할 경우 클릭 리포트 수치가 누락되는 경우가 발생하므로 해당 배너 뷰가 포함된 activity 나 fragment 가 destroy 상태 진입시에 호출 하여 주시길 부탁 드립니다.
{% endhint %}

```java
bannerAd.stopAd();
```

## 10. 배너 광고 로드 여부 체크

배너 광고 로드 시 광고 유/무를 파악할때 호출 합니다. (리턴 true = 광고 로드 성공 , flase = 광고 로드 실패)

```java
bannerAd.isDisplayed();
```

## 11. 이벤트 리스너

배너 광고를 불러올 때 발생하는 이벤트에 대한 리스너를 설정합니다. 제공되는 리스너와 구현 예시는 다음과 같습니다.

* OnBannerAdReceiveSuccess : 배너 광고 로딩 성공
* OnBannerAdReceiveFailed : 베너 광고 로딩 실패 (전달되는 에러코드는 아티클 하단의 테이블 참고)
* OnBannerAdClicked : 배너 클릭 시

```java
bannerAd.setBannerEventCallbackListener(new IBannerEventCallbackListener(){	

	@Override	
	public void OnBannerAdReceiveSuccess() { 
	}	

	@Override	
	public void OnBannerAdReceiveFailed(SSPErrorCode sspErrorCode) { 
	}

	@Override	
	public void OnBannerAdClicked() { 
	}
});
```

## 12. 배너 미디에이션 옵션

배너 광고의 일부 미디에이션에 대한 아래 설정 값을 지원합니다.

```
CAULY_DYNAMIC_RELOAD_INTERVAL : 카울리 다이나믹 배너 갱신 주기
CAULY_RELOAD_INTERVAL : 카울리 배너 갱신 주기
CAULY_THREAD_PRIORITY : 스레드 우선 순위 지정
CAULY_ENABLE_LOCK : 잠금 화면에서 노출 가능 여부

MEZZO_STORE_URL : 앱 스토어 URL
MEZZO_IS_USED_BACKGROUND_CHECK : 백그라운드 갱신 사용 여부 체크
MEZZO_AGE_LEVEL : 유저 나이 정보
```