# 사용자 레벨 수익 API 알아보기

> 탭조이 오퍼월의 사용자 레벨 수익 API를 사용하여 사용자별 수익을 트래킹하고 실행 가능한 분석 정보에 따라 앱의 수익화 전략을 조정할 수 있습니다.

탭조이를 사용하면 퍼블리셔가 기존의 오퍼 데이터 콜백 외에도 사용자 레벨 광고 수익 API를 통해 오퍼월 사용자 레벨 광고 수익 데이터에 액세스할 수 있습니다. 이 API는 사용자 레벨 광고 수익 리포트를 AWS(Amazon Web Services) S3에 저장된 CSV 파일을 통해 MMP(모바일 측정 파트너)나 퍼블리셔 파트너에게 직접 제공합니다.

요청을 생성하려면 사용자에게 관련 Tapjoy 앱 ID(탭조이 LTV 대시보드용 앱과 동일한 ID)와 데이터를 원하는 날짜가 있어야 합니다.

API를 사용하려면 MMP나 파트너가 리포트 API나 마케팅 API 키를 사용하여 액세스 토큰을 수신하도록 [탭조이 OAuth 엔드포인트](/grow/offerwall/monetization/api/api-authentication.md)에 요청해야 합니다. 액세스 토큰을 사용하면 사용자가 탭조이 리포트 API에 AWS S3의 리포트를 가리키는 사전 서명된 URL을 수신하도록 요청합니다. 사전 서명된 URL을 사용하면 검색 후 5분 동안 리포트에 액세스할 수 있습니다. 마지막으로 AWS S3에서 리포트 URL을 요청하면 사용자 레벨 광고 수익 데이터가 포함된 CSV 리포트가 반환됩니다.

## 리포트 API##report-api

엔드포인트: `https://api.tapjoy.com/api/client/publisher/apps/<app_id>/user_revenue_report`

리포트 API나 마케팅 API 키를 사용하여 [OAuth](/grow/offerwall/monetization/api/api-authentication.md)를 통해 액세스할 수 있습니다.

필수 파라미터:

* 퍼블리셔 앱 ID
* UTC 기준 날짜

허용되는 날짜 포맷은 mm/dd, mm/dd/yyyy, mm/dd/yy, dd-mm yyyy-mm-dd입니다.

5분 동안 유효한 사전 서명된 인증 토큰을 사용하여 정적 리포트에 URL 배열을 반환합니다.

### 요청 예시##example-request

다음 예제는 사용자 매출 보고서 요청에 필요한 헤더를 보여줍니다.

```curlrc
GET api/client/publisher/apps/<publisher_app_id>/user_revenue_report?date=<date> 
Host: api.tapjoy.com 
Authorization: Bearer <access_token_string> 
Accept: application/json
```

### 응답 예시##example-response

### Success##success

성공적으로 요청하면 S3의 보고서 파일을 가리키는 사전 서명된 URL 배열 반환됩니다.

```curlrc
{
	"urls": [
	"https://tapjoy.amazon.s3.com/data/report.csv.gz&key=secure"
  	  ]
}
```

### 실패##failure

퍼블리셔 앱 ID를 찾을 수 없는 경우 요청에 설명 오류 메시지 포함된 404 상태가 반환됩니다.

```curlrc

status 404 
{ 
	"reason": "ID가 있 <publisher_app_id> 는 퍼블리셔 앱이 없습니다." 
}
```

## S3 API##s3-api

데이터 SLA - 01:00(UTC 기준)의 x+1일에 준비될 x일의 데이터

리텐션 SLA - 14일(x일 + 15일) 동안 리포트 제공

사용자 레벨 수익 리포트의 CSV 파일 반환

### 요청 예시##example-request

다음 예시는 사전 서명된 S3 URL에서 보고서 파일을 요청하는 방법을 보여 줍니다.

```curlrc
GET /data/report.csv.gz&key=secure
Host: tapjoy.amazon.s3.com 
Accept: application/json
```

### 응답 예시##example-response

### Success##success

다음 예시는 성공적인 S3 요청에 대한 응답과 승인되지 않은 조건 또는 조건을 찾지 못한 경우의 오류 응답을 보여줍니다.

1. **Success**

   ```curlrc

   status 200 
   { 
     CSV File
   }
   ```

2. **Failure**

   ```curlrc title="Failure"

   status 401 
   { 
     "error": "유효하지 않음" 
   }

   status 404 
   { 
     "error": "찾을 수 없음" 
   }
   ```

## 필드 개요##fields-overview

다음 표는 리포트의 여러 열이 무엇을 의미하는지 자세히 설명합니다.

| 필드                      | 설명                                                                             |
| ----------------------- | ------------------------------------------------------------------------------ |
| date\_id 및 report\_date | API 요청의 사용자별 리포트 날짜입니다. 해당 날짜를 기준으로 하는 리포트 지표                                  |
| partner\_id             | 탭조이 내부 식별자                                                                     |
| app\_name, appkey       | 앱의 이름과 탭조이 식별자                                                                 |
| IDFA/IDFV/GAID          | 플랫폼에 따라 이 열에 식별자 값이나 UNKNOWN 값 포함                                              |
| device\_os\_version     | 연관된 모바일 디바이스의 운영체제 버전                                                          |
| att\_status             | 디바이스의 iOS 앱 트래킹 투명성 상태(알려진 경우)                                                 |
| publisher\_user\_id     | 디바이스와 연관된 퍼블리셔 식별자(해당하는 경우)                                                    |
| ad\_unit                | 항상 **오퍼월**이며 MMP에서 처리하는 데 사용                                                   |
| placement               | 탭조이 플레이스먼트 이름                                                                  |
| content\_card           | 탭조이 콘텐츠 카드 이름                                                                  |
| geoip\_country          | IP 조회에서 사용 가능한 경우 디바이스와 연관된 국가                                                 |
| currency\_sale          | 값이 **1**인 경우 연결된 전환이 발생했을 때 재화 세일이 진행 중이었거나, 세일이 발생한 경우 재화 멀티플라이어 값이 될 것임을 나타냄 |
| conversion\_rate        | 거래에 사용되는 재화 교환율                                                                |
| impressions             | 해당 날짜에 이 디바이스 ID와 연관된 누적 노출 수. 사용자가 전환한 당일, 전환된 오퍼를 본 횟수를 나타냄                  |
| publisher\_amount       | 해당 날짜에 이 디바이스 ID와 연관된 누적 수익                                                    |

## FAQ##faq

**Does this report include video revenue?:**아니요, 이 리포트에는 오퍼월 광고 수익만 포함됩니다. 사용자 레벨 광고 수익 데이터를 원하는 경우 파트너는 해당 API나 리포트에 액세스하려면 관련 미디에이션 담당자에게 문의해야 합니다.**How far back does this report look?:**퍼블리셔 파트너는 14일 동안 리포트에 액세스할 수 있으며, 매일 오전 1시(UTC 기준)에 전날의 리포트를 사용할 수 있습니다.**Why do some user level entries have zero values in the impression column but non-zero values for revenue?:**멀티 리워드 CPE 광고 제품의 경우 노출이 표시되는 때와 이벤트 전환이 멀티 리워드 퍼널에서 나중에 발생하는 때 사이에 지연 시간이 종종 발생합니다.**What currency is my publisher revenue amount shown in?:**미국 달러(USD)로 표시됩니다.**Which MMPs are currently supporting the API?:**[Appsflyer](../../user-acquisition/mmp-integrations/appsflyer)**Why are there multiple results in the publisher\_user\_id or geoip\_countries column?:**사용자가 다른 `publisher_user_ids` 또는 `geoip_countries`를 사용하여 동일한 퍼블리셔 앱에서 오퍼를 보고 전환할 수 있습니다. 이 ID는 SDK 초기화 시 퍼블리셔가 설정하므로 다음과 같은 일이 발생할 수 있습니다.1) 사용자가 `publisher_user_id A`와 연결됩니다.
2) A 오퍼를 확인합니다. 보기 기록에 `publisher_user_id A`가 있습니다.
3) 사용자가 `publisher_user_id B`와 연결됩니다.
4) 다시 A 오퍼를 확인합니다. 보기 기록에 `publisher_user_id B`가 있습니다.
5) 전환합니다. 변환 기록에 `publisher_user_id B`가 있습니다.`geoip_countries`에도 동일한 일이 발생할 수 있습니다. 수익 인플레이션을 피하려면 이 값을 하나의 행으로 통합해야 합니다.