> 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/cocoscreator/undefined-6.md).

# 보상형 광고 플러스 연동

## 1. 유저 식별값(USN) 입력

보상형 광고 플러스 기능을 활성화 및 활용하기 위해서는 반드시 유저의 식별값이 지정되어야 합니다.

유저 식별값은 리워드 지급 조건이 달성되었을 때 **완료 유저를 식별하기 위해 사용되는 고유한 값**입니다.

{% hint style="danger" %}
**주의 사항**

1. 1명의 유저는 반드시 1개의 고유한 유저 식별값(USN)을 가져야 하며, 앱 실행 시점이나 세션마다 변경되는 가변적인 값은 사용할 수 없습니다.
2. 개인정보(이메일, 이름, 전화번호, 식별 가능한 유저 아이디 등)이 포함되어서는 안됩니다.
3. USN으로 사용하기에 적합하지 않은 값의 예시는 다음과 같습니다. 
   1. 디바이스 ID(Android ID, Advertising ID, IDFA 등) 
   2. 앱 재설치, 기기 변경, 초기화 등에 따라 변경될 수 있는 값
4. 한글, 특수 문자, 공백 등이 포함된 경우에는 반드시 URL 인코딩 처리를 하여 사용하여야 합니다.
5. USN은 비디오 광고 로딩 이전에 반드시 설정되어 있어야 합니다.
6. <mark style="color:red;">**개발 서버에서 사용한 특정 USN값을 라이브 서버에서 유저가 할당받지 않도록 예외 처리를 하거나, 개발 서버에서 사용하는 USN은 별도 구분값을 설정해주셔야 합니다.**</mark>
   {% endhint %}

위 주의사항에 유의하여 유저 식별값을 입력합니다.

```dart
AdPopcornSSP.setUserId('Your_User_ID');
```

&#x20;&#x20;

## 2. 보상형 광고 플러스 세팅 페이지 연동

유저의 CS 문의 및 현재 리워드 참여 횟수 확인을 위해서는 세팅 페이지 연동이 반드시 필요합니다.

유저의 보상형 광고 플러스 정보는 아래 API를 통해 확인 가능합니다.&#x20;

```dart
AdPopcornSSP.openRewardAdPlusPage('YOUR_APP_KEY');
```

<figure><img src="/files/PrEFYMAGAbVGd3kApWns" alt="" width="360"><figcaption></figcaption></figure>

## 3. 보상형 광고 플러스 이벤트 처리

보상형 광고 플러스에서 발생되는 아래 이벤트를 전달 받고 싶은 경우 아래 API를 호출합니다.

```dart
AdPopcornSSP.setRewardAdPlusEventListener();
```

* **지원되는 이벤트**

| Event                         | 설명                         |
| ----------------------------- | -------------------------- |
| **OnClosedRewardAdPlusPage**  | 보상형 광고 플러스 세팅 페이지 닫기 이벤트   |
| **OnRewardAdPlusEventResult** | 보상형 광고 플러스 1차 광고 리워드 처리 결과 |

## 4. 보상형 광고 플러스 사용자 정보 조회

현재 유저의 사용 정보를 직접 조회하고자 할 땐, 아래의 API를 활용 가능합니다.

4.1 유저의 매체 전체 지면에 대한 정보 조회

<pre class="language-dart"><code class="lang-dart"><strong>AdPopcornSSP.getRewardAdPlusUserMediaStatus('app_key');
</strong></code></pre>

* **지원되는 이벤트**

| Event                               | 설명                  |
| ----------------------------------- | ------------------- |
| **OnRewardAdPlusUserMediaStatus**   | 현재 사용자의 전체 사용 정보 조회 |
| ㄴtotalBoxCount                      | 전체 받은 포인트 박스        |
| ㄴplacementStatusList                |                     |
| ㄴplacementStatusList.placementId    | 지면키                 |
| ㄴplacementStatusList.dailyUserLimit | 일별 유저 한도            |
| ㄴplacementStatusList.dailyUserCount | 일별 유저 참여 횟수         |

4.2 유저의 지면별 정보 조회

```dart
AdPopcornSSP.getRewardAdPlusUserPlacementStatus('app_key', 'placementId');
```

* 지원되는 이벤트

| Event                                 | 설명                      |
| ------------------------------------- | ----------------------- |
| **OnRewardAdPlusUserPlacementStatus** | 현재 사용자의 특정  지면 사용 정보 조회 |
| ㄴplacementId                          | 지면키                     |
| ㄴdailyUserLimit                       | 일별 유저 한도                |
| ㄴdailyUserCount                       | 일별 유저 참여 횟수             |

## 5. 샘플 코드

```js
const AdPopcornSSP = require('AdPopcornSSPPlugin');

cc.Class({
    extends: cc.Component,
    
    onLoad() {
        const ANDROID_APP_KEY = 'your_android_app_key';
        const IOS_APP_KEY = 'your_android_ios_key';
        
        const currentAppKey = cc.sys.os === cc.sys.OS_IOS ? IOS_APP_KEY : ANDROID_APP_KEY;
        if (cc.sys.os === cc.sys.OS_ANDROID || cc.sys.os === cc.sys.OS_IOS) {
            AdPopcornSSP.init(currentAppKey, (event, params) => this._onAdEvent(event, params));
            AdPopcornSSP.setLogEnable(true);
            AdPopcornSSP.setUserId('test_id');
        }
    },
     _openRewardAdPlus() {
        // 보상형 광고 플러스 세팅 페이지 연동
        AdPopcornSSP.openRewardAdPlusPage('app_key');
    },
    
    _getRewardAdPlusStatus() {
        // 현재사용자에 대한 미디어 전체 상태 조회 (iOS는 appKey 필수)
        AdPopcornSSP.getRewardAdPlusUserMediaStatus('app_key');
        // 현재사용자에 대한 특정 지면 상태 조회 (iOS는 appKey 필수)
        AdPopcornSSP.getRewardAdPlusUserPlacementStatus('app_key', 'placement_id');
    },
    _onAdEvent(event, params) {
        if (event === "AdPopcornSSPSDKDidInitialize") {
            this._loadAds();
        }
        else if(event === "OnClosedRewardAdPlusPage"){
            
        }
        else if(event === "OnRewardAdPlusEventResult"){
            
        }
        else if(event === "OnRewardAdPlusUserMediaStatus"){
            
        } 
        else if(event === "OnRewardAdPlusUserPlacementStatus"){
            
        }        
    },
});
```