# SDK API

## 1. 광고 목록 조회

SDK가 제공하는 DATA API 를 사용하여 광고 목록을 JSON 문자열로 받을 수 있습니다.

### requestOfferwallData()

호출 파라메터

* placementName :  플 레이스먼트에 설정된 광고 목록을 가져옵니다. "main" 은 사용할 수 없습니다.
* isEmbeded : false 인 경우에는 설정된 광고목록 전체를 가져옵니다. true 인 경우에는 플레이스먼트에 설정된 최대 광고 갯수만큼만 가져옵니다.

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

```java
// UI Thread 에서 호출 불가
// return : JSON 문자
S2Offerwall.requestOfferwallData(Context context, 
                                String placementName, 
                                boolean isEmbeded);

// 호출 예시
new Thread(() -> {
    String data = S2Offerwall.requestOfferwallData(activity,"YOUR_PLACEMENT",false);
    Log.d("TAG","return : " + data);
}).start();
```

{% endtab %}

{% tab title="Swift" %}

```swift
// completion closure 로 JSON 문자열 전달
S2Offerwall.requestOfferwallData(placementName:String, 
                                     isEmbeded:Bool, 
                                    completion: @escaping (String) -> Void)
                                    
// 호출 예시
S2Offerwall.requestOfferwallData(placementName: "YOUR_PLACEMENT", 
                                     isEmbeded: false) { jsonStr in
    NSLog("return : \(jsonStr)")
}
```

{% endtab %}

{% tab title="Flutter" %}

```dart
// Future<String> 으로 JSON 문자열 반환
S2OfferwallFlutter.requestOfferwallData(String placementName, bool isEmbeded)


// 호출 예시
S2OfferwallFlutter.requestOfferwallData("YOUR_PLACEMENT", false)
.then( (data) {
    print("return : $data");
});
```

{% endtab %}
{% endtabs %}

&#x20;아래의 JSON 샘플 데이터와 [에러 및 유형 코드](https://snapplay.gitbook.io/docs/data-api/error-code-and-types)를 참고하세요.

## 2. 상세 페이지 띄우기

특정 광고를 클릭했을 경우 이를 처리하기위하여 아래의 API 를 제공합니다.

### openAdItem()

&#x20;호출 파라메터

* advId : 광고의 고유 ID 값입니다. JSON 데이터의 "adv\_id" 입니다.
* needDetail : 광고 상세 페이지로 이동할지를 지정합니다. JSON 데이터의 "detail\_yn" 입니다.
  * "detail\_yn" = "Y" 이면 true 로 전달합니다. 광고 상세페이지로 이동합니다.
  * "detail\_yn" = "N" 이면 false 로 전달합니다. 광고 참여 요청 후 광고 페이지(마켓 등)로 바로 이동합니다.
* placementFrom : JSON 데이터를 가져올 때 사용한 placementName 입니다.

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

```java
S2Offerwall.openAdItem(Activity activity, 
                       long advId, 
                       boolean needDetail, 
                       String placementFrom);
```

{% endtab %}

{% tab title="Swift" %}

```swift
S2Offerwall.openAdItem(_ viewController: UIViewController, 
                                  advId:Int, 
                             needDetail:Bool, 
                          placementFrom:String)
```

{% endtab %}

{% tab title="Flutter" %}

```dart
S2OfferwallFlutter.openAdItem(int advId, 
                                bool needDetail, 
                                String placementFrom);
```

{% endtab %}
{% endtabs %}

openAdItem() 은 아래와 같은 순서로 처리됩니다.

1. needDetail 이 true 이면 광고 상세페이지를 띄웁니다.
2. needDetail 이 false 이면
   1. setUserName() 이 설정되었는 지 확인하고 설정되었다면 바로 광고 참여 요청을 수행합니다. 광고 참여가 정상적으로 처리되었으면 광고 페이지로 이동합니다. (브라우저로 이동함)
   2. 광고 참여 요청시 에러가 발생하면 에러 내용을 Alert 창으로 띄웁니다.
   3. setUserName() 이 설정되지 않았다면 EventListener.onLoginRequested() 가 호출됩니다.

## 3. Sample Data

```json
{
    "ret_cd": 0,
    "ret_list": [
        {
            "user_pnt": 5,
            "adid_yn": "N",
            "type_nm": "퀴즈풀기",
            "detail_yn": "N",
            "actn_type": 3410,
            "adv_type": 331,
            "icon_img_url": "https://d31pfn6usm02y3.cloudfront.net/snapquiz/quiz_img/pub/49/wi6zosn2wah.png",
            "num_actions": 1,
            "org_user_pnt": 5,
            "adv_types": [
                331,
                10011,
                3410
            ],
            "adv_id": 18547,
            "pnt_unit": "%",
            "adv_desc": "이미지 퀴즈의 정답을 모두 맟추면 성공!",
            "adv_title": "이미지 퀴즈풀기"
        },
        {
            "user_pnt": 180,
            "adid_yn": "Y",
            "type_nm": "구독",
            "detail_yn": "Y",
            "actn_type": 2202,
            "adv_type": 201,
            "icon_img_url": "https://cdn4.tnkfactory.com/icon/ic_264875.png",
            "num_actions": 1,
            "org_user_pnt": 180,
            "adv_types": [
                10007,
                201,
                2202
            ],
            "adv_id": 218047,
            "pnt_unit": "%",
            "adv_desc": "채널 구독하고 삼성전자의 다양한 소식을 만나 보세요",
            "feed_img_url": "https://cdn4.tnkfactory.com/scn/fi_264887_2.jpg",
            "adv_title": "삼성전자 뉴스룸 유튜브 구독"
        }
    ]
}
```

<table><thead><tr><th width="136.5703125">컬럼명</th><th width="285.6796875">설명</th><th>비고</th></tr></thead><tbody><tr><td>adv_id</td><td>광고 고유 ID</td><td></td></tr><tr><td>adv_title</td><td>광고 타이틀</td><td></td></tr><tr><td>adv_desc</td><td>광고 설명문</td><td></td></tr><tr><td>pnt_unit</td><td>사용자 지급 포인트 명칭</td><td></td></tr><tr><td>user_pnt</td><td>사용자 적립 포인트</td><td>num_actions > 1 이면 최대 가능 포인트</td></tr><tr><td>org_user_pnt</td><td>2배 이벤트 등 진행 시에는 원래 포인트</td><td></td></tr><tr><td>icon_img_url</td><td>아이콘 이미지 </td><td></td></tr><tr><td>feed_img_url</td><td>피드 이미지</td><td></td></tr><tr><td>adv_type</td><td>광고 타입</td><td>표 참고</td></tr><tr><td>adv_types</td><td>광고 타입과 태그들</td><td></td></tr><tr><td>actn_type</td><td>액션 타입</td><td>표 참고</td></tr><tr><td>type_nm</td><td>액션 타입 명칭</td><td>목록 표시용</td></tr><tr><td>num_actions</td><td>리워드 액션 갯수</td><td></td></tr><tr><td>detail_yn</td><td>상세 화면 필요 여부</td><td></td></tr><tr><td>adid_yn</td><td>adid 필수 광고 여부</td><td></td></tr></tbody></table>