> For the complete documentation index, see [llms.txt](https://adpopcornssp.gitbook.io/offerwall/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/offerwall/advertiser/campaign/web-cpa.md).

# Web CPA 캠페인 연동

웹 기반 CPA 캠페인의 완료 처리를 연동하는 방법을 안내해요. 

S2S 방식과 Script 방식 중 환경에 맞는 방식을 선택해 주세요.

***

### 연동 방식 선택 <a href="#method" id="method"></a>

<table><thead><tr><th width="145">항목</th><th>S2S 방식</th><th>Script 방식</th></tr></thead><tbody><tr><td>완료 처리 주체</td><td>광고주 서버에서 API 호출</td><td>클라이언트에서 JavaScript 호출</td></tr><tr><td>서버 개발 필요</td><td>필요</td><td>불필요</td></tr><tr><td>권장 상황</td><td>서버에서 완료 여부를 판단해야 하는 경우</td><td>프론트엔드만으로 처리 가능한 경우</td></tr></tbody></table>

***

### 이벤트 참여 프로세스 <a href="#event-participation-process" id="event-participation-process"></a>

두 방식 모두 동일한 흐름을 따라요.

```
[1] 유저가 애드팝콘 오퍼월에서 광고 클릭
    ↓
[2] 광고주 이벤트 페이지로 랜딩 (tid, campaignkey 파라미터 전달)
    ↓
[3] 유저가 이벤트 페이지에서 완료 액션 달성
    ↓
[4] 완료 처리 (S2S: 서버에서 API 호출 / Script: JavaScript에서 함수 호출)
    ↓
[5] 리워드 지급 (애드팝콘에서 처리)
```

***

### 필수 파라미터 <a href="#required-parameters" id="required-parameters"></a>

유저가 광고를 클릭하면 광고주 랜딩 URL에 아래 파라미터가 자동으로 전달돼요.

```
http://광고주이벤트페이지주소?tid={자동생성된TID값}&campaignkey={캠페인키}
```

<table><thead><tr><th width="160">파라미터</th><th>설명</th></tr></thead><tbody><tr><td>tid</td><td>클릭 ID. 오퍼월에서 광고 클릭 시 자동 생성되며, 클릭할 때마다 값이 변경돼요.</td></tr><tr><td>campaignkey</td><td>캠페인 키. 캠페인별로 고정되는 값이에요.</td></tr></tbody></table>

> 페이지 전환이 되어도 tid, campaignkey 파라미터는 완료 페이지까지 계속 유지되어야 해요.

***

### 완료 처리 연동 <a href="#completion-integration" id="completion-integration"></a>

{% tabs %}
{% tab title="S2S 방식" %}
광고주 서버에서 애드팝콘 완료 API를 직접 호출하여 캠페인 완료를 처리해요. 서버에서 완료 여부를 판단해야 하는 경우에 적합해요.

#### Sign 생성 방법

```
Sign = MD5(tid + campaignkey)
```

| 항목          | 값                                |
| ----------- | -------------------------------- |
| tid         | abcde                            |
| campaignkey | 12345                            |
| sign        | df6f58808ebfd3e609c234cf2283a989 |

> [MD5 Hash 값 확인하기](https://www.md5hashgenerator.com/)

#### 완료 API 호출

유저가 완료 액션을 달성하면 광고주 서버에서 아래 API를 호출해 주세요.

```
GET https://apapi.adpopcorn.com/ap/v1/postback/thirdparty/AchievePostBack?tid={tid}&sign={sign}
```

#### 호출 예시

```
https://apapi.adpopcorn.com/ap/v1/postback/thirdparty/AchievePostBack?tid=abcde&sign=df6f58808ebfd3e609c234cf2283a989
```

#### 응답

<table><thead><tr><th width="135">필드</th><th width="135">자료형</th><th>설명</th></tr></thead><tbody><tr><td>IsTest</td><td>Int</td><td>접속 환경 (true: 스테이징, false: 라이브)</td></tr><tr><td>Result</td><td>Boolean</td><td>호출 성공 여부 (true: 성공, false: 실패)</td></tr><tr><td>ResultCode</td><td>Int</td><td>결과 코드</td></tr><tr><td>ResultMsg</td><td>String</td><td>결과 메시지</td></tr></tbody></table>

#### 응답 코드

<table><thead><tr><th width="130">ResultCode</th><th>ResultMsg</th><th>설명</th></tr></thead><tbody><tr><td>1</td><td>요청이 성공하였습니다</td><td>캠페인 완료 체크 성공</td></tr><tr><td>100 / 200</td><td>Exception</td><td>알 수 없는 오류. 완료 요청 시간 및 TID 정보와 함께 문의해 주세요.</td></tr><tr><td>999</td><td>Terminated or invalid campaign</td><td>종료된 캠페인에 대해 완료 요청한 경우</td></tr><tr><td>1400</td><td>Invalid media</td><td>미디어 정보가 정확하지 않은 경우</td></tr><tr><td>2000</td><td>Already completed</td><td>이미 참여 완료한 TID</td></tr><tr><td>2100</td><td>Participation info not exist</td><td>참여 시도 이력이 없는 유저 정보로 완료 요청한 경우</td></tr><tr><td>3000</td><td>Sign check fail</td><td>sign 정보의 유효성 체크에 실패한 경우</td></tr><tr><td>4200</td><td>Invalid tid</td><td>TID가 유효하지 않은 경우</td></tr><tr><td>4720</td><td>Campaign type error</td><td>CPA 타입이 아닌 캠페인에 대해 해당 API로 완료 요청한 경우</td></tr><tr><td>5300</td><td>tid or sign parameter is null</td><td>TID 또는 Sign 파라미터를 전달하지 않은 경우</td></tr></tbody></table>

***

#### 멀티리워드 캠페인인 경우

멀티리워드 CPA 캠페인은 완료 API 엔드포인트와 파라미터가 다르니 아래 내용을 참고해 주세요.

**완료 API**

```
GET https://apapi.adpopcorn.com/ap/v1/postback/thirdparty/AchieveMultiPostBack?tid={tid}&sign={sign}&event_name={event_name}
```

| 파라미터        | 설명                                  |
| ----------- | ----------------------------------- |
| tid         | 클릭 ID (일반 CPA와 동일)                  |
| sign        | MD5(tid + campaignkey) (일반 CPA와 동일) |
| event\_name | 완료된 이벤트명 (캠페인 설정 시 협의된 값)           |

**호출 예시**

```
https://apapi.adpopcorn.com/ap/v1/postback/thirdparty/AchieveMultiPostBack?tid=abcde&sign=df6f58808ebfd3e609c234cf2283a989&event_name=purchase
```

> 응답 및 응답 코드는 일반 CPA S2S와 동일해요. 단, 필수 파라미터에 event\_name이 추가돼요.
> {% endtab %}

{% tab title="Script 방식" %}
JavaScript 스크립트를 사용하여 클라이언트에서 캠페인 완료를 처리해요. 서버 개발 없이 프론트엔드만으로 처리 가능한 경우에 적합해요.

#### 랜딩 페이지에서 액션이 완료되는 경우

광고 클릭 후 랜딩되는 페이지에서 모든 액션이 완료되는 경우예요. \
(예: 싱글 이벤트 페이지, 게임 사전예약 등)

**1. 스크립트 선언**

```html
<script src="//webapi.adpopcorn.com/offerwall/postback/adpopcorn-cpa.min.js"></script>
```

**2. 완료 함수 호출**

페이지 전환이 없는 경우:

```javascript
AdPopcorn.cpaCompleted();
```

페이지 전환이 이루어지는 경우:

```javascript
AdPopcorn.cpaCompleted(function() {
    // 리다이렉트 액션 진행
});
```

***

#### 랜딩 페이지에서 페이지가 전환되어 액션이 완료되는 경우

광고 클릭 후 랜딩되는 페이지가 아닌 다른 페이지에서 액션이 완료되는 경우예요. \
(예: 사이트 회원가입, 단계별 회원가입 등)

> 페이지 전환이 되어도 tid, campaignkey 파라미터는 완료 페이지까지 계속 유지되어야 해요.

**1. 스크립트 선언**

```html
<script src="//webapi.adpopcorn.com/offerwall/postback/adpopcorn-cpa.min.js"></script>
```

**2. 완료 함수 호출**

페이지 전환이 없는 경우:

```javascript
AdPopcorn.cpaCompleted();
```

페이지 전환이 이루어지는 경우:

```javascript
AdPopcorn.cpaCompleted(function() {
    // 리다이렉트 액션 진행
});
```

{% endtab %}
{% endtabs %}

***

### 문의 <a href="#support" id="support"></a>

* 연동 문의: <reward@adpopcorn.com>