# 퍼블리셔용 리포트 API

> 액세스, 접근 탭조이 오퍼월의 리포트 API에 접근하여 상세 데이터를 조회하고, 앱 퍼포먼스를 모니터링 및 평가하며, 수익화 전략을 최적화합니다.

퍼블리셔는 리포트 API를 사용하여 오퍼월을 제공하는 앱의 리포트 데이터를 조회할 수 있습니다.

## 필수 조건##prerequisites

API로 인증해야 합니다. [API 인증](/grow/offerwall/monetization/api/api-authentication.md)을 참고하십시오.

* 리포트 API를 통해 콘텐츠를 관리하는 방법에 대한 정보는 [콘텐츠 관리](/grow/offerwall/monetization/api/content-management.md) 문서를 참고하십시오.
* 보고서 API로 오류 처리 및 제한 사항에 관한 내용을 알아보려면 [보고서 API 베스트 프랙티스](/grow/offerwall/monetization/api/reporting-api-best-practices.md)를 참고하십시오.

## 퍼블리셔 리포트 지표##publisher-reporting-metrics

리포트 API를 사용하면 클릭, 전환, 총 수익 등의 지표를 포함한 오퍼월 콘텐츠의 퍼포먼스 데이터를 요청할 수 있습니다. 사용 가능한 모든 퍼블리셔 리포트 지표는 아래 차트에 나열되어 있습니다.

퍼포먼스 지표를 조회하기 위해 퍼블리셔는 다음 기본 쿼리로 시작할 것을 권장합니다.

```graphql
{
  publisher {
    placements(appId: "00000000-0000-0000-0000-000000000000") {
      id
      name
      insights(
        timeRange: {from: "YYYY-MM-DDT00:00:00Z", until: "YYYY-MM-DDT00:00:00Z"}
      ) {
        timestamps
        reports {
          dailyUniqueViewers
          earnings
        }
      }
    }
  }
}
```

| 퍼블리셔 지표                           | 설명                                                                                                                | Country | 앱 그룹 | 단일 퍼블리셔 앱 | 플레이스먼트 | 모든 퍼블리셔 앱 합계 |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------- | ---- | --------- | ------ | ------------ |
| `averageDuc`                      | 앱, 플레이스먼트 또는 콘텐츠 카드 내 오퍼월 광고에서 전환한 고유 사용자 평균 수(사용자당 24시간마다 1회 집계)를 일수로 나눈 값                                       | 예       | 예    | 예         | 예      | 예            |
| `arpdau`                          | 일일 활성 사용자당 평균 수익(총 수익을 일일 활성 사용자 수로 나눈 값)                                                                         | 예       | 예    | 예         | 아니요    | 예            |
| `arpduv`                          | 일일 고유 오퍼월 시청자당 평균 수익(앱 내 오퍼월을 시청한 고유 사용자 수(사용자당 24시간당 1회 집계)로 나눈 총 수익)                                            | 예       | 예    | 예         | 아니요    | 예            |
| `averageDau`                      | 일일 활성 사용자 평균 수(사용자당 24시간당 1회 집계)를 일수로 나눈 값                                                                        | 예       | 예    | 예         | 아니요    | 예            |
| `averageDuv`                      | 앱 내 오퍼월을 조회한 고유 사용자 평균 수(사용자당 24시간마다 1회 집계)를 일수로 나눈 값                                                             | 예       | 예    | 예         | 아니요    | 예            |
| `clicks`                          | 해당 플레이스먼트에서 발생한 클릭 수                                                                                              | 예       | 아니요  | 아니요       | 예      | 아니요          |
| `conversions`                     | 해당 플레이스먼트에서 발생한 전환 수                                                                                              | 예       | 아니요  | 아니요       | 예      | 아니요          |
| `dailyActiveUsers`                | 일간 이용자 수                                                                                                          | 예       | 예    | 예         | 아니요    | 예            |
| `dailyUniqueConversions`          | 이 플레이스먼트 또는 콘텐츠 카드의 광고를 통해 전환한 사용자 수(사용자당 24시간마다 1회 집계). 현재 오퍼월 콘텐츠 카드에만 적용                                       | 예       | 아니요  | 아니요       | 예      | 아니요          |
| `dailyUniqueOfferwallEngagements` | 앱 내 오퍼월 광고에서 전환한 고유 사용자 수(사용자당 24시간마다 1회 집계)                                                                      | 예       | 예    | 예         | 아니요    | 예            |
| `dailyUniqueOfferwallViewers`     | 앱 내에서 오퍼월을 조회한 고유 사용자 수(사용자당 24시간마다 1회 집계)                                                                        | 예       | 예    | 예         | 아니요    | 예            |
| `dailyUniqueViewers`              | 이 플레이스먼트 또는 콘텐츠 카드에서 광고를 본 고유 사용자 수(사용자당 24시간마다 1회 집계). 현재 오퍼월 콘텐츠 카드에만 적용                                        | 예       | 아니요  | 아니요       | 예      | 아니요          |
| `ducduv`                          | 이 플레이스먼트 또는 콘텐츠 카드의 광고를 통해 전환한 사용자 수(사용자당 24시간마다 1회 집계)를 이 플레이스먼트 또는 콘텐츠 카드의 광고를 본 사용자 수(사용자당 24시간마다 1회 집계)로 나눈 값 | 예       | 예    | 예         | 예      | 예            |
| `duvDau`                          | 앱 내에서 오퍼월을 조회한 고유 사용자 수(사용자당 24시간마다 1회 집계)를 일일 활성 사용자 수로 나눈 값                                                     | 예       | 예    | 예         | 아니요    | 예            |
| `earnings`                        | 총 수익액                                                                                                             | 예       | 아니요  | 아니요       | 예      | 아니요          |
| `eCPM`                            | 총 수익/(총 오퍼월 열람 횟수/1000). USD 단위로 표시됩니다.                                                                           | 예       | 아니요  | 아니요       | 예      | 아니요          |
| `impressions`                     | 해당 플레이스먼트에서 발생한 노출 수                                                                                              | 예       | 아니요  | 아니요       | 예      | 아니요          |
| `newUsers`                        | 신규 사용자 수                                                                                                          | 예       | 예    | 예         | 아니요    | 예            |
| `offerwallViews`                  | 오퍼월 총 개수                                                                                                          | 예       | 예    | 예         | 아니요    | 예            |
| `sessions`                        | 앱 실행 횟수                                                                                                           | 예       | 예    | 예         | 아니요    | 예            |
| `totalRevenue`                    | 총 매출                                                                                                              | 예       | 예    | 예         | 아니요    | 예            |

**대시보드에서 확인할 수 있는 추가 퍼블리셔 지표:**

* 노출/조회
* CVR(전환율)

## 지표 세그먼트##metric-segmentations

쿼리에 세그먼트 필드를 추가하면 API가 앱, 플레이스먼트 및/또는 국가별로 세분화된 퍼포먼스 데이터를 반환할 수 있습니다.

리포트 API는 다음과 같은 세분화를 지원합니다.

* country
* id(앱 그룹 ID)
* id(퍼블리셔 앱 ID)
* placement
* platform
* total across all Publisher Apps

### 세그먼트 예시##segmentation-examples

#### 국가별 세그먼트##segment-by-country

다음 쿼리 특정 플레이스먼트의 일별 고유 뷰어 데이터를 국가별로 세분화하여 반환합니다.

1. **Query**

   ```graphql
   {
     publisher {
       placements(appId: "00000000-0000-0000-0000-000000000000") {
         id
         insights(timePreset: TODAY) {
           timestamps
           reports {
             country
             dailyUniqueViewers
           }
         }
       }
     }
   }
   ```

2. **Result**

   ```graphql
   {
     "data": {
       "publisher": {
         "placements": [
           {
             "id": "00000000-0000-0000-0000-000000000001",
             "insights": {
               "timestamps": [
                 "2024-11-15T00:00:00Z"
               ],
               "reports": [
                 {
                   "country": "AU",
                   "dailyUniqueViewers": [
                     115
                   ]
                 },
                 {
                   "country": "IR",
                   "dailyUniqueViewers": [
                     18
                   ]
                 },
                 {
                   "country": "ZA",
                   "dailyUniqueViewers": [
                     2
                   ]
                 }
               ]
             }
           }
         ]
       }
     }
   }
   ```

#### 앱 그룹별 세그먼트##segment-by-app-group

다음 쿼리 앱 그룹 ID로 세분화된 첫 3개의 앱 일간 액티브 사용자 데이터를 반환합니다.

1. **Query**

   ```graphql
   {
     publisher {
       apps(first: 3) {
         nodes {
           appGroupId
           insights(timePreset: TODAY) {
             reports {
               dailyActiveUsers
             }
           }
         }
       }
     }
   }
   ```

2. **Result**

   ```graphql
   {
     "data": {
       "publisher": {
         "apps": {
           "nodes": [
             {
               "appGroupId": "00000000-0000-0000-0000-000000000000",
               "insights": {
                 "reports": [
                   {
                     "dailyActiveUsers": [
                       12
                     ]
                   }
                 ]
               }
             },
             {
               "appGroupId": "00000000-0000-0000-0000-000000000001",
               "insights": {
                 "reports": [
                   {
                     "dailyActiveUsers": [
                       31
                     ]
                   }
                 ]
               }
             },
             {
               "appGroupId": "00000000-0000-0000-0000-000000000002",
               "insights": {
                 "reports": [
                   {
                     "dailyActiveUsers": [
                       3
                     ]
                   }
                 ]
               }
             }
           ]
         }
       }
     }
   }
   ```

#### 퍼블리셔 앱별 세그먼트##segment-by-publisher-app

다음 쿼리 앱 이름으로 세분화된 첫 번째 퍼블리셔 앱 3개의 일간 액티브 사용자 데이터를 반환합니다.

1. **Query**

   ```graphql
   query {
     publisher {
     apps(first:3) {
         edges {
           node {
             name
             insights(timePreset:TODAY) {
               reports {
                 dailyActiveUsers
               }
             }
           }
         }
       }
     }
   }
   ```

2. **Result**

   ```graphql"
   {
     "data": {
       "publisher": {
         "apps": {
           "edges": [
             {
               "node": {
                 "name": "example_app1",
                 "insights": {
                   "reports": [
                     {
                       "dailyActiveUsers": [
                         78
                       ]
                     }
                   ]
                 }
               }
             },
             {
               "node": {
                 "name": "example_app2",
                 "insights": {
                   "reports": [
                     {
                       "dailyActiveUsers": [
                         12
                       ]
                     }
                   ]
                 }
               }
             },
             {
               "node": {
                 "name": "example_app3",
                 "insights": {
                   "reports": [
                     {
                       "dailyActiveUsers": [
                         15
                       ]
                     }
                   ]
                 }
               }
             }
           ]
         }
       }
     }
   }
   ```

#### 플레이스먼트별 세그먼트##segment-by-placement

다음 쿼리 특정 앱의 모든 플레이스먼트에 대한 노출 데이터를 플레이스먼트별로 세분화하여 반환합니다.

1. **Query**

   ```graphql
   {
     publisher{
       placements(appId: "00000000-0000-0000-0000-000000000000") {
         id
         name
         insights(timePreset: TODAY) {
           reports {
             impressions
           }
           timestamps
         }
       }
     }
   }
   ```

2. **Result**

   ```graphql
   {
     "data": {
       "publisher": {
         "placements": [
           {
             "id": "00000000-0000-0000-0000-000000000000",
             "name": "AppLaunch",
             "insights": {
               "reports": [
                 {
                   "impressions": [
                     0
                   ]
                 }
               ],
               "timestamps": [
                 "2024-11-15T00:00:00Z"
               ]
             }
           },
           {
             "id": "00000000-0000-0000-0000-000000000000",
             "name": "offerwall",
             "insights": {
               "reports": [
                 {
                   "impressions": [
                     2590
                   ]
                 }
               ],
               "timestamps": [
                 "2024-11-15T00:00:00Z"
               ]
             }
           }
         ]
       }
     }
   }
   ```

#### 플랫폼별 세그먼트##segment-by-platform

다음 쿼리 플랫폼별로 세분화된 특정 플레이스먼트의 일별 고유 뷰어 데이터를 반환합니다.

1. **query**

   ```graphql
     publisher {
       placements(appId: "00000000-0000-0000-0000-000000000000") {
         id
         insights(timePreset: TODAY) {
           timestamps
           reports {
             platform
             dailyUniqueViewers
           }
         }
       }
     }
   }
   ```

2. **Result**

   ```graphql
   {
     "data": {
       "publisher": {
         "placements": [
           {
             "id": "00000000-0000-0000-0000-000000000001",
             "insights": {
               "timestamps": [
                 "2024-11-15T00:00:00Z"
               ],
               "reports": [
                 {
                   "platform": "ios",
                   "dailyUniqueViewers": [
                     78
                   ]
                 }
               ]
             }
           }
         ]
       }
     }
   }
   ```

#### 모든 퍼블리셔 앱 합계##sum-across-all-publisher-apps

이 퍼블리셔의 모든 앱 요청된 지표의 합계를 나타냅니다.

다음 쿼리 현재의 모든 퍼블리셔 앱 대한 eCPM, 총 매출, offerwall 뷰의 합계를 반환합니다.

1. **query**

   ```graphql
   {
     publisher {
       publisherAppInsights(timePreset: TODAY) {
         timestamps
         reports {
           ecpm
           totalRevenue
           offerwallViews
         }
       }
     }
   }
   ```

2. **Result**

   ```graphql
   {
     "data": {
       "publisher": {
         "publisherAppInsights": {
           "timestamps": [
             "2025-08-27T00:00:00Z"
           ],
           "reports": [
             {
               "ecpm": [
                 4.108913673386
               ],
               "totalRevenue": [
                 57149851536
               ],
               "offerwallViews": [
                 461224
               ],
             }
           ]
         }
       }
     }
   }
   ```

## 필터링 기능##filtering-capabilities

API는 쿼리에 필터를 추가하여 지정된 소스의 퍼포먼스 지표만 반환합니다. 리포트 API는 다음 필터링 기능을 지원합니다.

* appId(단일 앱)
* apps(*첫 번째* 또는 *마지막* x 앱)
* appGroupId
* content
* country
* platform
* timePreset
* timeRange

### 필터링 예시##filtering-examples

#### 앱으로 필터링##filter-by-app

이렇게 하면 결과가 단일 앱으로 제한됩니다.

```graphql
{
  publisher{
    app(id: "<app ID>") {
      id
      name
      insights(timePreset: TODAY) {
        reports {
          arpdau
        }
        timestamps
      }
    }
  }
}
```

#### 다중 앱 필터링##filter-for-multiple-apps

이렇게 하면 결과를 *처음* 또는\_ 마지막\_ x개 앱으로 제한합니다

```graphql
{
  publisher {
    apps(first: 3) {
      nodes {
        id
        platform
        insights {
          reports {
            arpdau
            totalRevenue
          }
        }
      }
    }
  }
}
```

#### 앱 그룹 ID로 필터링##filter-by-app-group-id

이는 결과물을 특정 앱 그룹 ID 아래의 앱으로만 제한합니다.

```graphql
{
  publisher {
    publisherAppInsights(timePreset: TODAY, filter: {appGroupIds: ["00000000-0000-0000-0000-000000000000"]}) {
      timestamps
      reports {
        offerwallViews
        eCPM
        totalRevenue
      }
    }
```

#### 콘텐츠 카드로 필터링##filter-by-content-card

이렇게 하면 결과가 단일 콘텐츠 카드 ID로 제한됩니다.

```graphql
{
  publisher {
    placements(appId: "<app ID>") {
      id
      name
      content(id: "<content ID>") {
        id
        type
        insights(timePreset: TODAY) {
        timestamps
          reports {
            earnings
          }
        }
      }
    }
  }
} 
```

#### 국가로 필터링##filter-by-country

이를 통해 지정된 지역에 결과물이 한정됩니다.

```graphql
{
  publisher {
    publisherAppInsights(timePreset: TODAY, filter: {countries: ["KR, US"]}) {
      timestamps
      reports {
        offerwallViews
        eCPM
        totalRevenue
      }
    }
```

#### 플랫폼으로 필터링##filter-by-platform

이렇게 하면 결과가 지정된 플랫폼으로 제한됩니다.

```graphql
{
  publisher {
    publisherAppInsights(timePreset: TODAY, filter: {platforms: [ios]}) {
      timestamps
      reports {
        offerwallViews
        eCPM
        totalRevenue
      }
    }
```

#### 프리셋 기간으로 필터링##filter-by-a-preset-timeframe

이렇게 하면 결과가 프리셋 기간으로 제한됩니다. 상대적인 기간이며, 결과는 쿼리가 실행되는 시점에 따라 달라집니다.

**옵션**: *LAST\_30D*, *LAST\_WEEK*, *TODAY*, *YESTERDAY*.

> **Note:**
>
> 데이터 집계 레벨을 정의하려면 **timeIncrement**를 포함합니다. 이는 *DAILY*, *HOURLY*, *MONTHLY* 값을 가질 수 있습니다. **timeIncrement**는 선택 사항 파라미터이며 \_ALL\_로 기본 설정됩니다.

```graphql
{
  publisher {
    placements(appId: "<app ID>") {
      content(id: "<content card ID>") {
        insights(timePreset:LAST_30D, timeIncrement: DAILY) {
        timestamps
          reports {
            dailyUniqueViewers
          }
        }
      }
    }
  }
} 
```

#### 절대 시간 범위로 필터링##filter-by-an-absolute-time-range

이렇게 하면 결과가 지정된 절대 기간으로 제한됩니다.

최대 범위는 3개월이며, 최초 날짜는 지난 2년까지 지원됩니다.

> **Note:**
>
> 데이터 집계 레벨을 정의하려면 **timeIncrement**를 포함합니다. 이는 *DAILY*, *HOURLY*, *MONTHLY* 값을 가질 수 있습니다. **timeIncrement**는 선택 사항 파라미터이며 \_ALL\_로 기본 설정됩니다.

```graphql
{
  publisher {
    placements(appId: "<app ID>") {
      content(id: "<content card ID>") {
        insights(timeRange: {from: "2024-11-15T00:00:00Z", until: "2024-11-17T00:00:00Z"}, timeIncrement: DAILY) {
        timestamps
          reports {
            dailyUniqueViewers
          }
        }
      }
    }
  }
} 
```

## 사용 중단 예정인 측정 항목##deprecated-dimensions

다음 레거시 측정 항목은 2025년 2월 3일에 리포트 API에서 제거되었습니다. API 쿼리를 통해 탭조이의 오퍼월에서 데이터를 가져올 때 오류를 방지하기 위해 아래의 **굵은 글씨**로 된 측정 항목을 참고하지 **마십시오**.

Objects > ContentCard > **ecpmSettings**

Enums > PublisherContentType:

* `ANNOUNCEMENT`
* `DIRECT_PLAY_HOUSE_AD`
* `FEATURED`
* `FSI_HOUSE_AD`
* `IAP_PROMOTION`
* `INTERSTITIAL_VIDEO`
* `MEDIATED_DIRECT_PLAY`
* `MEDIATED_FSI`
* `PREVIEW_CODE`
* `PROGRAMMATIC_INTERSTITIAL_VIDEO`
* `PROGRAMMATIC_REWARDED_VIDEO`
* `REWARDED_VIDEO`
* `TJ_RECOMMENDED`
* `REWARD_UNLOCK`

Input Objects > `CreatePlacementAndContentSetInput` > **ecpmSettingsToAdd**

Input Objects > `UpdatePlacementAndContentSetInput`:

* `ecpmSettingsToAdd`
* `ecpmSettingsToDelete`
* `ecpmSettingsToUpdate`