# 보상형 광고 플러스 연동

{% hint style="info" %}
보상형 광고 플러스는 AdPopcornSSPUnityPlugin\_v1.1.0.unitypackage 버전부터 API를 지원합니다.
{% endhint %}

## 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 %}

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

```csharp
AdPopcornSSPPluginIOS.SetUserId("TEST_UNITY_IOS");
```

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

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

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

아래 API의 기본 버전은 1.5입니다.

<pre class="language-csharp"><code class="lang-csharp"><strong>AdPopcornSSPPluginIOS.OpenRewardAdPlusPage("your_app_key");
</strong></code></pre>

<figure><img src="https://50533756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fqmkw7pJLtjFGD5fwChbN%2Fuploads%2FLr5pRA5kFzMkzCRRSVwm%2Fimage.png?alt=media&#x26;token=359f828a-b380-426c-9619-f39ee5612a1c" alt="" width="360"><figcaption><p>v1.5 보상형 광고 플러스 설정 페이지 예시</p></figcaption></figure>

## 3. 보상형 광고 플러스 델리게이트 지원

보상형 광고 플러스에서 발생되는 아래 이벤트들에 대해선 이벤트 리스너로 이벤트를 전달해 줍니다.

* sspRewardAdPlusPageClosed : 보상형 광고 세팅 페이지 닫기
* sspRewardAdPlusEventResult : 1차 광고 참여 완료 후 포인트 박스 지급 성공 or 실패에 대한 이벤트

```csharp
public class AdPopcornSSPSampleScene : MonoBehaviour, 
{
    void Start (){
        // 델리게이트 등록	
        AdPopcornSSPPluginIOS.AdPopcornSSPSetCallbackHandler("AdPopcornSSPSampleScene");	    
        
        AdPopcornSSPPluginIOS.sspRewardAdPlusPageClosed += HandlleSSPRewardAdPlusPageClosed;
        AdPopcornSSPPluginIOS.sspRewardAdPlusEventResult += HandlleSSPRewardAdPlusEventResult;
        
        AdPopcornSSPPluginIOS.OpenRewardAdPlusPage("your_app_key");
    }
	
    public void HandlleSSPRewardAdPlusPageClosed()
    {
        // 보상형 광고 세팅 페이지 닫기
    }
    
    public void HandlleSSPRewardAdPlusEventResult(int resultCode, string resultMessage)
    {
        // 1차 광고 참여 완료 후 포인트 박스 지급 성공 or 실패에 대한 이벤트
    }
}
```

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

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

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

```csharp
AdPopcornSSPPluginIOS.GetRewardAdPlusUserMediaStatus("your_app_key");
```

4.2 유저의 지면별 정보 조회

```csharp
AdPopcornSSPPluginIOS.GetRewardAdPlusUserPlacementStatus("your_app_key", "your_placement_id");
```

```csharp
public class AdPopcornSSPSampleScene : MonoBehaviour
{
    void Start ()
    {	
        AdPopcornSSPPluginIOS.AdPopcornSSPSetCallbackHandler("AdPopcornSSPSampleScene");	    
	
        AdPopcornSSPPluginIOS.sspRewardAdPlusUserMediaStatusWithResult += HandlleSSPRewardAdPlusUserMediaStatus;
        AdPopcornSSPPluginIOS.sspRewardAdPlusUserPlacementStatusWithResult += HandlleSSPRewardAdPlusUserPlacementStatus;
        
        AdPopcornSSPPluginIOS.OpenRewardAdPlusPage("62198111");
        AdPopcornSSPPluginIOS.GetRewardAdPlusUserPlacementStatus("62198111", "2e92f6bd1");
    }
	
    public void HandlleSSPRewardAdPlusUserMediaStatus(bool result, int totalBoxCount, string placementStatusListJson)
    {
	
        Debug.Log("AdPopcornSSPSample HandleSSPRewardAdPlusUserMediaStatus : " + result + ", totalBoxCount : " + totalBoxCount);
        // placementStatusListJson을 UnityEngine.JsonUtility로 파싱
        try
        {
            Debug.LogError("placementStatusListJson : " + placementStatusListJson);
            string wrappedJson = "{\"items\":" + placementStatusListJson + "}";
            
            PlacementStatusListWrapper wrapper = JsonUtility.FromJson<PlacementStatusListWrapper>(wrappedJson);
                
            if (wrapper != null && wrapper.items != null)
            {
                foreach (PlacementStatus placement in wrapper.items)
                {
                    Debug.Log($"  Placement ID: {placement.placementId}, Limit: {placement.limit}, Current: {placement.current}");
                }
            }
            else
            {
                Debug.LogError("Failed to parse placement list or it is empty.");
            }
        }
        catch (System.Exception e)
        {
            Debug.LogError("Error parsing placement list JSON with JsonUtility: " + e.Message);
        }
    }
    
    public void HandlleSSPRewardAdPlusUserPlacementStatus(bool result, string placementId, int limit, int current)
    {
        Debug.Log("AdPopcornSSPSample HandleSSPRewardAdPlusUserPlacementStatus : " + result + ", placementId : " + placementId + ", limit : " + limit);
    }
}
```

* sspRewardAdPlusUserMediaStatusWithResult  : 매체에 활성화된 전체 리워드 애드 플러스 지면에 대한 정보.
  * result : 조회 성공 여부
  * totalBoxCount : 전체 받은 포인트 박스
  * placementStatusListJson
    * placementId : 조회 한 지면 키
    * limit : 일별 유저 한도
    * current : 일별 유저 참여 횟수
  * Native -> Unity 메시지 전달 방식에 따라 Json 데이터를 직접 파싱하여 정보를 받아야 합니다. Unity내 기본 Json 라이브러리 사용시에는 위 샘플과 같이 처리하면 됩니다.
* sspRewardAdPlusUserPlacementStatusWithResult  : 특정 지면에 대한 정보를 제공
  * result : 조회 성공 여부
  * placementId : 조회 한 지면 키
  * limit : 일별 유저 한도
  * current: 일별 유저 참여 횟수