> 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/sdk/android/undefined-2.md).

# 전면 광고

<div><figure><img src="/files/MbZv6n88WJpggqEJ2h2B" alt="" width="320"><figcaption></figcaption></figure> <figure><img src="/files/yIdDUbAHdCRDHHSytymX" alt="" width="563"><figcaption></figcaption></figure></div>

## 1. 전면 광고 인스턴스 생성

아래 코드를 추가하여 전면 광고 인스턴스를 생성합니다.

{% tabs %}
{% tab title="JAVA" %}

```java
private AdPopcornSSPInterstitialAd interstitialAd; 

@Override 
rotected void onCreate(Bundle savedInstanceState) { 
    interstitialAd = new AdPopcornSSPInterstitialAd(context);
}
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
private var interstitialAd: AdPopcornSSPInterstitialAd? = null
override fun onCreate(savedInstanceState: Bundle?) { 
		interstitialAd = AdPopcornSSPInterstitialAd(this@MainActivity)
}
```

{% endtab %}
{% endtabs %}

## 2. 전면 Placement ID 설정

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

{% tabs %}
{% tab title="JAVA" %}

```java
interstitialAd.setPlacementId("전면_PlacementId");
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
interstitialAd?.setPlacementId("전면광고PlacementId")
```

{% endtab %}
{% endtabs %}

## 3. 전면 광고 요청

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

{% tabs %}
{% tab title="JAVA" %}

```java
interstitialAd.loadAd();
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
interstitialAd?.loadAd()
```

{% endtab %}
{% endtabs %}

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

## 4. 전면 광고 노출

전면 광고 노출 시점에 <mark style="color:red;">`showAd()`</mark> API 를 추가하여 광고를 노출합니다.

{% tabs %}
{% tab title="JAVA" %}

```java
interstitialAd.showAd();
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
interstitialAd?.showAd()
```

{% endtab %}
{% endtabs %}

## 5. 전면 광고가 노출될 activity 지정

아래 코드를 추가하여 전면 광고의 Load API 를 호출한 activity 가 아닌 다른 곳에서 show 를 하고자 할 경우, 현재의 activity 에서 호출합니다.

{% tabs %}
{% tab title="JAVA" %}

```java
interstitialAd.setCurrentActivity(this);
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
interstitialAd?.setCurrentActivity(this@MainActivity);
```

{% endtab %}
{% endtabs %}

## 6. 전면 광고 로드 여부 체크

전면 광고 로드 시 광고 유/무를 파악할 때 호출 합니다.

* <mark style="color:red;">`true`</mark>: 광고 로드 성공&#x20;
* <mark style="color:blue;">`false`</mark>: 광고 로드 실패

{% tabs %}
{% tab title="JAVA" %}

```java
interstitialAd.isLoaded();
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
interstirialAd?.showAd()
```

{% endtab %}
{% endtabs %}

## 7. 이벤트 리스너

### 1) 전면 광고 Load 이벤트 리스너

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

| 이벤트 리스너                     | 설명                                                          |
| --------------------------- | ----------------------------------------------------------- |
| OnInterstitialLoaded        | 전면 광고 로딩 성공                                                 |
| OnInterstitialReceiveFailed | 전면 광고 로딩 실패. [에러코드 값](/ssp-sdk/sdk/android/undefined-10.md) |

{% tabs %}
{% tab title="JAVA" %}

```java
interstitialAd.setInterstitialLoadEventCallbackListener(new IInterstitialLoadEventCallbackListener() { 	
	@Override 
	public void OnInterstitialLoaded() { 
		Toast.makeText(MainActivity.this, "LoadEventCallback OnInterstitialLoaded", Toast.LENGTH_SHORT).show(); 
	} 
	
	@Override 
	public void OnInterstitialReceiveFailed(SSPErrorCode errorCode) { 
		Toast.makeText(MainActivity.this, "LoadEventCallback OnInterstitialReceiveFailed", Toast.LENGTH_SHORT).show(); 
	}
});
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
interstitialAd?.setInterstitialLoadEventCallbackListener(object: IInterstitialLoadEventCallbackListener {
    override fun OnInterstitialLoaded() {
    }

    override fun OnInterstitialReceiveFailed(errorCode: SSPErrorCode) {
    }
})
```

{% endtab %}
{% endtabs %}

### 2) 전면 광고 Show 이벤트 리스너

전면 광고 열고 닫을 경우에 대한 이벤트 리스너를 설정합니다. 제공되는 리스너와 구현 예시는 다음과 같습니다.

<table><thead><tr><th width="230">이벤트 리스너</th><th>설명</th></tr></thead><tbody><tr><td>OnInterstitialOpened</td><td>전면 광고 열기</td></tr><tr><td>OnInterstitialOpenFailed</td><td>전면 광고 열기 실패</td></tr><tr><td>OnInterstitialClosed</td><td>전면 광고 닫기. 닫기 이벤트가 발생한 방법에 따라 closeEvent를 전달해 줍니다. 단 , 미디에이션 광고의 경우에는 SSP에서 확인할 수 없이 <code>Unknown</code>으로 전달되어 집니다.</td></tr><tr><td>OnInterstitialClicked</td><td>전면 광고 클릭 시</td></tr></tbody></table>

{% tabs %}
{% tab title="JAVA" %}

```java
interstitialAd.setInterstitialShowEventCallbackListener(new IInterstitialShowEventCallbackListener() { 

	@Override 
	public void OnInterstitialOpened() { 
	} 

	@Override 
	public void OnInterstitialOpenFailed(SSPErrorCode errorCode) { 
	} 

	@Override 
	public void OnInterstitialClosed(int CloseEvent) { 
			// UNKNOWN = 0; 
			// CLICK_CLOSE_BTN = 1; 
			// PRESSED_BACK_KEY = 2; 
			// SWIPE_RIGHT_TO_LEFT = 3; 
			// SWIPE_LEFT_TO_RIGHT = 4; 
			// AUTO_CLOSE = 5; 
	}

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

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
interstitialAd?.setInterstitialShowEventCallbackListener(object: IInterstitialShowEventCallbackListener{

    override fun OnInterstitialOpened() {
    }

    override fun OnInterstitialOpenFailed(errorCode: SSPErrorCode) {
    }

    override fun OnInterstitialClosed(CloseEvent: Int) {
    // UNKNOWN = 0;
    // CLICK_CLOSE_BTN = 1;
    // PRESSED_BACK_KEY = 2;
    // SWIPE_RIGHT_TO_LEFT = 3;
    // SWIPE_LEFT_TO_RIGHT = 4;
    // AUTO_CLOSE = 5;
    }

    override fun OnInterstitialClicked() {
    }
})
```

{% endtab %}
{% endtabs %}

## 8. 전면 광고 커스텀 옵션&#x20;

전면 광고 노출시 아래와 같은 커스텀 옵션을 제공합니다.&#x20;

(InterstitialAd.CustomExtraData 에 정의되어 있는 값 사용)

필요한 옵션 설정 후 "<mark style="color:red;">`endingInterstitialAd.setCustomExtras(extras);`</mark>" API 를 호출합니다.

<table data-full-width="false"><thead><tr><th>option</th><th width="250">설명</th><th width="95">Type</th><th>Default</th></tr></thead><tbody><tr><td>APSSP_AD_BACKGROUND_COLOR </td><td>전면 광고 배경색 및 투명도 변경</td><td>int</td><td>Black , 투명도 : 0 (#ff000000)</td></tr><tr><td>APSSP_AD_ENABLE_SWIPE_CLOSE </td><td>Swipe 를 이용하여 전면광고 닫기 기능 추가</td><td>Boolean</td><td>false</td></tr><tr><td>APSSP_AD_HIDE_CLOSE_BTN </td><td>전면 광고 우측 상단 닫기 버튼 노출 여부 설정</td><td>Boolean</td><td>false</td></tr><tr><td>APSSP_AD_SWIPE_MIN_DISTANCE_DP</td><td>Swipe 동작을 위한 최소 swipe 거리</td><td>int</td><td>120(dp)</td></tr><tr><td>APSSP_AD_CLOSE_BTN_MARGIN_FROM_EDGE </td><td>광고 이미지 마진 기준. 마진을 주고 싶은 경우 false.</td><td>Boolean</td><td>true</td></tr><tr><td>APSSP_AD_CLOSE_BTN_LEFT_MARGIN</td><td>APSSP 전면 광고 닫기 버튼 좌측 마진</td><td>int</td><td>-28(dp)</td></tr><tr><td>APSSP_AD_CLOSE_BTN_RIGHT_MARGIN</td><td>APSSP 전면 광고 닫기 버튼 우측 마진</td><td>int</td><td>20(dp)</td></tr><tr><td>APSSP_AD_CLOSE_BTN_TOP_MARGIN</td><td>APSSP 전면 광고 닫기 버튼 상단 마진</td><td>int</td><td>20(dp)</td></tr><tr><td>APSSP_AD_CLOSE_BTN_BOTTOM_MARGIN</td><td>APSSP 전면 광고 닫기 버튼 하단 마진</td><td>int</td><td>0</td></tr><tr><td>APSSP_AD_DISABLE_BACK_BTN</td><td>전면 백키 사용 여부</td><td>Boolean</td><td>false</td></tr><tr><td>IS_ENDING_AD</td><td>전면 광고에 종료 메시지 노출 여부</td><td>Boolean</td><td>false</td></tr><tr><td>ENDING_TEXT</td><td>종료 광고 메시지 변경</td><td>string</td><td>"뒤로가기를 한 번 더 누르시면 종료됩니다."</td></tr><tr><td>ENDING_TEXT_SIZE</td><td>종료 광고 메시지 크기 변경</td><td>int</td><td>11(sp)</td></tr><tr><td>ENDING_TEXT_COLOR</td><td>종료 광고 메시지 색상 변경</td><td>int</td><td>0x9c9c9c</td></tr><tr><td>ENDING_TEXT_GRAVITY</td><td>종료 광고 메시지 정렬 위치 변경</td><td>int</td><td>우측 정렬</td></tr></tbody></table>

{% tabs %}
{% tab title="JAVA" %}

```java
endingInterstitialAd = new InterstitialAd(this);

endingInterstitialAd.setPlacementId(TEST_INTERSTITIAL_PLACEMENT_ID);

HashMap extras = new HashMap<>();

// Option1. 배경색 변경
extras.put(AdPopcornSSPInterstitialAd.CustomExtraData.APSSP_AD_BACKGROUND_COLOR , Color.parseColor("#ff0000"));

// Option2. 배경색 + 투명도 변경
extras.put(AdPopcornSSPInterstitialAd.CustomExtraData.APSSP_AD_BACKGROUND_COLOR , Color.parseColor("#11000000"));
extras.put(AdPopcornSSPInterstitialAd.CustomExtraData.APSSP_AD_ENABLE_SWIPE_CLOSE , true);
extras.put(AdPopcornSSPInterstitialAd.CustomExtraData.APSSP_AD_HIDE_CLOSE_BTN , true);
extras.put(AdPopcornSSPInterstitialAd.CustomExtraData.APSSP_AD_SWIPE_MIN_DISTANCE_DP , 120);

// Option3. 전면광고를 Ending 배너로 사용하실 경우 아래 옵션을 추가합니다.
extras.put(AdPopcornSSPInterstitialAd.CustomExtraData.IS_ENDING_AD, true);
extras.put(AdPopcornSSPInterstitialAd.CustomExtraData.ENDING_TEXT, "백키를 누르시면 종료 시켜드립니다! 감사합니다\n");
extras.put(AdPopcornSSPInterstitialAd.CustomExtraData.ENDING_TEXT_SIZE, 14);
extras.put(AdPopcornSSPInterstitialAd.CustomExtraData.ENDING_TEXT_COLOR, Color.parseColor("#ffffff"));
extras.put(AdPopcornSSPInterstitialAd.CustomExtraData.ENDING_TEXT_GRAVITY, Gravity.RIGHT);

endingInterstitialAd.setCustomExtras(extras);

// Option4. Close 버튼 디바이스 우측 상단 기준 커스텀
HashMap customExtras = new HashMap<>();

customExtras.put(AdPopcornSSPInterstitialAd.CustomExtraData.APSSP_AD_CLOSE_BTN_LEFT_MARGIN, -28); // 영향 받지 않음
customExtras.put(AdPopcornSSPInterstitialAd.CustomExtraData.APSSP_AD_CLOSE_BTN_RIGHT_MARGIN, 50);
customExtras.put(AdPopcornSSPInterstitialAd.CustomExtraData.APSSP_AD_CLOSE_BTN_TOP_MARGIN, 50);
customExtras.put(AdPopcornSSPInterstitialAd.CustomExtraData.APSSP_AD_CLOSE_BTN_BOTTOM_MARGIN, 0); // 영향 받지 않음
interstitialAd.setCustomExtras(customExtra);

// Option5. 중앙 광고물의 Close 버튼 우측 상단 기준 커스텀
// - 광고물 기준으로 커스텀 진행 시 디바이스 가로 , 세로 길이와 광고물의 가로 , 세로 길이에 따라 영향 받는 옵션 값이 달라짐.

// - 광고물이 전체 화면에 노출 되는 경우
//APSSP_AD_CLOSE_BTN_RIGHT_MARGIN, IGAW_AD_CLOSE_BTN_TOP_MARGIN 영향 받음.

// - 디바이스 화면이 광고물 보다 더 큰 경우
//APSSP_AD_CLOSE_BTN_LEFT_MARGIN, IGAW_AD_CLOSE_BTN_BOTTOM_MARGIN 영향 받음.

HashMap customExtras = new HashMap<>();
customExtras.put(AdPopcornSSPInterstitialAd.CustomExtraData.APSSP_AD_CLOSE_BTN_MARGIN_FROM_EDGE, false);
customExtras.put(AdPopcornSSPInterstitialAd.CustomExtraData.APSSP_AD_CLOSE_BTN_LEFT_MARGIN, -28);
customExtras.put(AdPopcornSSPInterstitialAd.CustomExtraData.APSSP_AD_CLOSE_BTN_RIGHT_MARGIN, 50);
customExtras.put(AdPopcornSSPInterstitialAd.CustomExtraData.APSSP_AD_CLOSE_BTN_TOP_MARGIN, 50);
customExtras.put(AdPopcornSSPInterstitialAd.CustomExtraData.APSSP_AD_CLOSE_BTN_BOTTOM_MARGIN, 0);
interstitialAd.setCustomExtras(customExtra);
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
endingInterstitialAd = AdPopcornSSPInterstitialAd(this@MainActivity)

var extras:HashMap<String, Any> = HashMap()

// Option1. 배경색 변경
extras[AdPopcornSSPInterstitialAd.CustomExtraData.APSSP_AD_BACKGROUND_COLOR] = Color.parseColor("#ff0000")

// Option2. 배경색 + 투명도 변경
extras[AdPopcornSSPInterstitialAd.CustomExtraData.APSSP_AD_BACKGROUND_COLOR] = Color.parseColor("#11000000")

extras[AdPopcornSSPInterstitialAd.CustomExtraData.APSSP_AD_CANCELABLE_TIME_MILLIS] = 3000
extras[AdPopcornSSPInterstitialAd.CustomExtraData.APSSP_AD_ENABLE_SWIPE_CLOSE] = true
extras[AdPopcornSSPInterstitialAd.CustomExtraData.APSSP_AD_HIDE_CLOSE_BTN] = true
extras[AdPopcornSSPInterstitialAd.CustomExtraData.APSSP_AD_SWIPE_MIN_DISTANCE_DP] = 120

// Option3. 전면광고를 Ending 배너로 사용하실 경우 아래 옵션을 추가합니다.
extras[AdPopcornSSPInterstitialAd.CustomExtraData.IS_ENDING_AD] = true
extras[AdPopcornSSPInterstitialAd.CustomExtraData.ENDING_TEXT] = "백키를 누르시면 종료 시켜드립니다! 감사합니다\n"
extras[AdPopcornSSPInterstitialAd.CustomExtraData.ENDING_TEXT_SIZE] = 14
extras[AdPopcornSSPInterstitialAd.CustomExtraData.ENDING_TEXT_COLOR] = Color.parseColor("#ffffff")
extras[AdPopcornSSPInterstitialAd.CustomExtraData.ENDING_TEXT_GRAVITY] = Gravity.RIGHT

endingInterstitialAd?.setCustomExtras(extras)

// Option4. Close 버튼 디바이스 우측 상단 기준 커스텀
var customExtras:HashMap<String, Any> = HashMap()

customExtras[AdPopcornSSPInterstitialAd.CustomExtraData.APSSP_AD_CLOSE_BTN_LEFT_MARGI] = -28 // 영향 받지 않음
customExtras[AdPopcornSSPInterstitialAd.CustomExtraData.APSSP_AD_CLOSE_BTN_RIGHT_MARGIN] = 50
customExtras[AdPopcornSSPInterstitialAd.CustomExtraData.APSSP_AD_CLOSE_BTN_TOP_MARGIN] = 50
customExtras[AdPopcornSSPInterstitialAd.CustomExtraData.APSSP_AD_CLOSE_BTN_BOTTOM_MARGIN] = 0 // 영향 받지 않음
interstitialAd?.setCustomExtras(customExtras)

// Option5. 중앙 광고물의 Close 버튼 우측 상단 기준 커스텀
// - 광고물 기준으로 커스텀 진행 시 디바이스 가로 , 세로 길이와 광고물의 가로 , 세로 길이에 따라 영향 받는 옵션 값이 달라짐.

// - 광고물이 전체 화면에 노출 되는 경우
// APSSP_AD_CLOSE_BTN_RIGHT_MARGIN, APSSP_AD_CLOSE_BTN_TOP_MARGIN 영향 받음.

// - 디바이스 화면이 광고물 보다 더 큰 경우
// APSSP_AD_CLOSE_BTN_LEFT_MARGIN, APSSP_AD_CLOSE_BTN_BOTTOM_MARGIN 영향 받음.

var customExtras:HashMap<String, Any> = HashMap()
customExtras[AdPopcornSSPInterstitialAd.CustomExtraData.APSSP_AD_CLOSE_BTN_MARGIN_FROM_EDGE] = false
customExtras[AdPopcornSSPInterstitialAd.CustomExtraData.APSSP_AD_CLOSE_BTN_LEFT_MARGIN] = -28
customExtras[AdPopcornSSPInterstitialAd.CustomExtraData.APSSP_AD_CLOSE_BTN_RIGHT_MARGIN] = 50
customExtras[AdPopcornSSPInterstitialAd.CustomExtraData.APSSP_AD_CLOSE_BTN_TOP_MARGIN] = 50
customExtras[AdPopcornSSPInterstitialAd.CustomExtraData.APSSP_AD_CLOSE_BTN_BOTTOM_MARGIN] = 0
interstitialAd?.setCustomExtras(customExtras)
```

{% endtab %}
{% endtabs %}