# 광고주용 리포트 API

> 액세스, 접근 탭조이 오퍼월의 리포트 API에 액세스하여 상세한 데이터를 검색하고, 앱 성과를 모니터링하고 이를 평가하고, 리포트 쿼리를 최적화하여 더 나은 캠페인 분석 정보를 얻을 수 있습니다.

광고주는 리포트 API 사용하여 오퍼월에서 게재되는 광고에 대한 리포트 데이터를 가져올 수 있습니다.

## 필수 조건##prerequisites

[API로 인증](./api-authentication.md)해야 합니다.

* 리포트 API를 통해 캠페인을 관리하는 방법은 [캠페인 관리를 참고하십시오](./campaign-management.md).
* 리포트 API로 오류 처리 및 제한 사항에 관한 내용을 알아보려면 [리포트 API 베스트 프랙티스](./reporting-api-best-practices.md)를 참고하십시오.

## 광고주 리포트 지표##advertiser-reporting-metrics

리포트 API 사용하여 수익, 노출, 전환 등의 지표를 비롯한 광고 세트와 멀티 리워드 이벤트의 퍼포먼스 데이터를 요청할 수 있습니다. 모든 사용 가능한 광고주 리포트 지표는 아래 차트에 나와 있습니다.

광고주는 퍼포먼스 지표를 검색하는 데 다음 기본 쿼리로 시작하는 것이 좋습니다.

```graphql
query {
  adSet(id: "00000000-0000-0000-0000-000000000000") {
    insights(timeRange: {from: "YYYY-MM-DDT00:00:00Z", until: "YYYY-MM-DDT00:00:00Z"}) {
      timestamps
      reports {
        impressions
      }
    }
  }
}
```

| 광고주 지표                   | 설명                                                                                                                                                                                         |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| amount                   | 이벤트에 대한 단가                                                                                                                                                                                 |
| averageBid               | 총 지출을 총 전환 수로 나눈 값입니다.                                                                                                                                                                     |
| callToActionClicks       | CTA가 있는 경우 사용자가 이를 클릭한 횟수입니다.                                                                                                                                                              |
| clickToConversionTime    | 여러 방식으로 세분화된 전환 시간 데이터를 클릭합니다. CTCT 지표는 매일 첫 UTC 시간에만 리포트됩니다. `HOURLY` 세분화를 사용하는 경우, `00:00:00 UTC - 00:59:59 UTC`를 나타내는 시간만 0 이외의 값을 가집니다.                                                |
| conversions              | 광고 목표에 따른 전환 수입니다.                                                                                                                                                                         |
| csConversions            | 광고 목표에 따른 고객 서비스 전환 수입니다.                                                                                                                                                                  |
| csSpend                  | 총 고객 지원 지출액입니다.                                                                                                                                                                            |
| ecpi                     | 총 지출을 총 참여 수로 나눈 값입니다.                                                                                                                                                                     |
| engagementInstalls       | 참여를 통해 추론된 다운로드 수입니다.                                                                                                                                                                      |
| iaaRevenue               | 선택한 기간 동안 오퍼에서 창출한 총 광고 수익입니다.                                                                                                                                                             |
| iapRevenue               | 선택한 기간 동안 오퍼에서 창출한 총 IAP 수익입니다.                                                                                                                                                            |
| impressions              | 오퍼월에서 광고를 클릭한 횟수입니다. 이 지표는 `impressions`가 아니라 `clicks`를 더 정확하게 나타냅니다. 이 지표의 이름이 곧 변경될 예정입니다.                                                                                               |
| offerwallAverageRank     | 광고가 게재된 평균적인(가중치 반영) 오퍼월 위치입니다. 값은 1부터 오름차순으로, 1은 오퍼월의 최상위 포인트를 나타냅니다. 값이 0이면 선택한 기간 동안 오퍼가 오퍼월에 표시되지 않았음을 의미합니다.                                                                          |
| offerwallImpressions     | 오퍼월에 광고가 표시된 횟수입니다. 광고는 오퍼월에 표시되지만 사용자가 보지 못할 수 있습니다. 즉, 사용자가 광고가 표시될 만큼 화면을 스크롤하지 않았습니다. 광고주가 아래의 `offerwallTrueImpressions`를 사용하는 것을 권장합니다.                                              |
| offerwallTrueImpressions | 오퍼월에서 사용자가 광고를 본 횟수입니다. 각 보기는 진정성 있는 노출로 등록됩니다.                                                                                                                                            |
| returnOnAdSpend          | 매일 다운로드한 사용자의 ROAS(광고 비용 대비 수익률)입니다. ROAS 지표는 매일 첫 UTC 시간에만 리포트됩니다.                                                                                                                        |
| dayXRoas                 | 설치 후 `X`일간의 총 ROAS입니다. 이 값은 `dayXRoasRevenue`를 `dayXRoasSpend`로 나눈 값으로 계산됩니다. `dayXRoasRevenue`가 0이면 이 필드도 0이 됩니다. `X = 0, 1, 2, 3, 4, 5, 6, 7, 14, 30, 60, 90`에 사용할 수 있습니다.               |
| dayXRoasAdRevenue        | 선택한 기간 동안 오퍼를 설치한 사용자가 설치 후 `X`일 동안 오퍼를 통해 창출한 총 광고 수익입니다. `X = 0, 1, 2, 3, 4, 5, 6, 7, 14, 30, 60, 90`에 사용할 수 있습니다.                                                                       |
| dayXRoasEngagements      | 설치 후 `X`일간의 총 사용자 참여 수입니다. `X = 0, 1, 2, 3, 4, 5, 6, 7, 14, 30, 60, 90`에 사용할 수 있습니다.                                                                                                       |
| dayXRoasIapRevenue       | 선택한 기간 동안 오퍼를 설치한 사용자가 설치 후 `X`일 동안 오퍼를 통해 창출한 총 IAP 수익입니다. `X = 0, 1, 2, 3, 4, 5, 6, 7, 14, 30, 60, 90`에 사용할 수 있습니다.                                                                      |
| dayXRoasRevenue          | 선택한 기간 동안 오퍼를 설치한 사용자가 설치 후 `X`일간 오퍼를 통해 창출한 총 수익(IAP + 광고 수익)입니다. 이 값은 `dayXRoasIapRevenue`와 `dayXRoasAdRevenue`를 더한 값으로 계산됩니다. `X = 0, 1, 2, 3, 4, 5, 6, 7, 14, 30, 60, 90`에 사용할 수 있습니다. |
| dayXRoasSpend            | 설치 후 광고주가 `X`일간 지출한 금액입니다. `X = 0, 1, 2, 3, 4, 5, 6, 7, 14, 30, 60, 90`에 사용할 수 있습니다.                                                                                                       |
| spend                    | 총 지출액입니다.                                                                                                                                                                                  |
| totalRevenue             | 선택한 기간 동안 오퍼를 통해 창출한 총 수익(IAP + 광고 수익)입니다. 이 값은 `iaaRevenue`와 `iapRevenue`를 더한 값으로 계산됩니다.                                                                                                  |

대시보드에서 사용 가능한 추가 광고주 지표

* CVR(전환율)
* 명령 CVR
* 전환/노출
* CTR(Click-through Rate)
* *총* 지출 기준 ROAS(리포트 API는 *복합* 지출 기준 ROAS를 반환함)

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

API는 쿼리에 세그먼트 필드를 추가하여 이벤트, 퍼블리셔 앱, 국가 등으로 세분화된 퍼포먼스 데이터를 반환할 수 있습니다. 리포트 API는 다음과 같은 세분화를 지원합니다.

* country
* attributionSource
* language
* platform
* id(퍼블리셔 앱 ID)
* id(광고 세트/오퍼 ID)
* multiRewardEngagementEvent

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

#### 국가, 어트리뷰션 소스, 언어별 세그먼트##segment-by-country-attribution-source-and/or-language

다음 쿼리 특정 광고 세트와 기간별로 국가, 어트리뷰션 소스, 언어를 기준으로 세분화된 전환 데이터를 반환합니다.

```graphql title="Query"
{
  adSet(id: "00000000-0000-0000-0000-000000000000") {
    insights(timeRange: {from: "2024-08-01T00:00:00Z", until: "2024-08-01T11:59:59Z"}, timeIncrement: DAILY) {
      timestamps
      reports {
        country
        attributionSource
        language
        conversions
      }
    }
  }
}
```

```graphql title="Result"
{
  "data": {
    "adSet": {
      "insights": {
        "timestamps": [
          "2024-08-01T00:00:00Z"
        ],
        "reports": [
          {
            "country": "FR",
            "attributionSource": "OTHER",
            "language": "RU",
            "conversions": [
              1
            ]
          },
          {
            "country": "FR",
            "attributionSource": "OTHER",
            "language": "FR",
            "conversions": [
              17
            ]
          },
          {
            "country": "CA",
            "attributionSource": "OTHER",
            "language": "EN",
            "conversions": [
              16
            ]
          },
          {
            "country": "AU",
            "attributionSource": "OTHER",
            "language": "EN",
            "conversions": [
              3
            ]
          },
        ]
      }
    }
  }
}
```

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

다음 쿼리 플랫폼별로 세분화된 처음 두 캠페인의 노출 데이터를 반환합니다.

```graphql title="Query"
{
  advertiser{
    id
    campaigns(first: 2){
      nodes{
        insights{
          reports{
            impressions
            platform
          }
        }
      }
    }
  }
}
```

```graphql title="Result"
{
  "data": {
    "advertiser": {
      "id": "00000000-0000-0000-0000-000000000000",
      "campaigns": {
        "nodes": [
          {
            "insights": {
              "reports": [
                {
                  "impressions": [
                    0
                  ],
                  "platform": null
                }
              ]
            }
          },
          {
            "insights": {
              "reports": [
                {
                  "impressions": [
                    0
                  ],
                  "platform": null
                }
              ]
            }
          }
        ]
      }
    }
  }
}
```

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

다음 쿼리 퍼블리셔 앱별로 세분화된 특정 광고 세트의 노출, 전환, 지출을 반환합니다.

```graphql title="Query"
query {
  adSet(id: "00000000-0000-0000-0000-000000000000") {
    ads {
      id
      insights(timePreset: TODAY) {
        reports {
          app {
            bundleId
          }
          impressions
          conversions
          spend
        }
      }
    }
  }
}
```

```graphql title="Result"
{  
  "data": {  
    "adSet": {  
      "ads": [  
        {  
          "id": "10000000-0000-0000-0000-000000000000",
          "insights": {  
            "reports": [  
              {  
                "app": {  
                  "bundleId": "com.example.app",
                },
                "impressions": [  
                  6147
                ],
                "conversions": [  
                  24
                ],
                "spend": [  
                  73000000
                ]
              },
              {  
                "app": {  
                  "bundleId": "com.example.app2",
                },
                "impressions": [  
                  4131
                ],
                "conversions": [  
                  12
                ],
                "spend": [  
                  73000000
                ]
              },
              {  
                "app": null,
                "impressions": [  
                  5427
                ],
                "conversions": [  
                  34
                ],
                "spend": [  
                  73000000
                ]
              }
            ]
          }
        },
        {  
          "id": "20000000-0000-0000-0000-000000000000",
          "insights": {   
            "reports": [  
              {  
                "app": {  
                  "bundleId": "com.example.app",
                },
                "impressions": [  
                  6142
                ],
                "conversions": [  
                  24
                ],
                "spend": [  
                  73000000
                ]
              },
              {  
                "app": {  
                  "bundleId": "com.example.app2",
                },
                "impressions": [  
                  4111
                ],
                "conversions": [  
                  12
                ],
                "spend": [  
                  73000000
                ]
              },
              {  
                "app": null,
                "impressions": [  
                  5227
                ],
                "conversions": [  
                  30
                ],
                "spend": [  
                  73000000
                ]
              }
            ]
          }
        }
      ],
      "insights": {  
        "reports": [  
          {  
            "app": {  
              "bundleId": "com.example.app",
            },
            "impressions": [  
              12550
            ],
            "conversions": [  
              49
            ],
            "spend": [  
              147000000
            ]
          },
          {  
            "app": {  
              "bundleId": "com.example.app2",
            },
            "impressions": [  
              8242
            ],
            "conversions": [  
              24
            ],
            "spend": [  
              146000000
            ]
          },
          {  
            "app": null,
            "impressions": [  
              10654
            ],
            "conversions": [  
              64
            ],
            "spend": [  
              146000000
            ]
          }
        ]
      }
    }
  }
}
```

#### 광고 세트 또는 캠페인별 세그먼트##segment-by-ad-set-or-campaign

다음 쿼리 지정된 기간 동안 최대 50개의 활성 광고 세트에 대한 전환과 지출을 반환합니다.

```graphql title="Query"
query {
  advertiser {
    adSets(first: 50, configuredStatus: ACTIVE) {
      edges {
        node {
          id
          insights(timeRange: {from: "2024-11-15T00:00:00Z", until: "2024-11-16T00:00:00Z"}) {
            timestamps
            reports {
              conversions
              spend
            }
          }
        }
      }
    }
  }
}
```

```graphql title="Result"
{
  "data": {
    "advertiser": {
      "adSets": {
        "edges": [
          {
            "node": {
              "id": "00000000-0000-0000-0000-000000000000",
              "insights": {
                "timestamps": [
                  "2024-11-15T00:00:00Z"
                ],
                "reports": [
                  {
                    "impressions": [
                      13550
                    ],
                    "conversions": [
                      53
                    ],
                    "spend": [
                      159000000
                    ]
                  }
                ]
              }
            }
          },
          {
            "node": {
              "id": "00000000-0000-0000-0000-000000000001",
              "insights": {
                "timestamps": [
                  "2024-11-15T00:00:00Z"
                ],
                "reports": [
                  {
                    "impressions": [
                      1220
                    ],
                    "conversions": [
                      8
                    ],
                    "spend": [
                      12300000
                    ]
                  }
                ]
              }
            }
          }
        ]
      }
    }
  }
}
```

#### 멀티 리워드 참여 이벤트별 세그먼트##segment-by-multi-reward-engagement-event

다음 쿼리 특정 광고 세트의 전환과 D0 ROAS를 다중 보상형 참여 이벤트 세분화하여 반환합니다.

```graphql title="Query"
{
  adSet(id: "00000000-0000-0000-0000-000000000000") {
    id
    insights(timeRange: {from: "2024-11-15T00:00:00Z", until: "2024-11-15T11:59:59Z"}, timeIncrement: DAILY) {
      timestamps
      reports {
        conversions
        returnOnAdSpend {
          day0Roas
        }
        multiRewardEngagementEvent {
          eventName
        }
      }
    }
  }
}
```

```graphql title="Result"
{
  "data": {
    "adSet": {
      "id": "00000000-0000-0000-0000-000000000000",
      "insights": {
        "timestamps": [
          "2024-11-15T00:00:00Z"
        ],
        "reports": [
          {
            "conversions": [
              10
            ],
            "returnOnAdSpend": {
              "day0Roas": [
                0
              ]
            },
            "multiRewardEngagementEvent": {
              "eventName": "Purchase=#"
            }
          },
          {
            "conversions": [
              15
            ],
            "returnOnAdSpend": {
              "day0Roas": [
                0
              ]
            },
            "multiRewardEngagementEvent": {
              "eventName": "LEVEL_#"
            }
          }
        ]
      }
    }
  }
}
```

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

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

* adSet(단일 광고 세트)
* adSets(여러 광고 세트)
* appIds(퍼블리셔 앱)
* configuredStatus(*ACTIVE*, *ARCHIVED*, *PAUSED*)
* countries
* timePreset
* timeRange

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

#### 광고 세트로 필터링##filter-by-ad-set

이렇게 하면 결과가 단일 \_adSet\_로 제한됩니다.

```graphql title="GraphQL"
query {
  adSet(id: "00000000-0000-0000-0000-000000000000") {
    insights(timeRange: {from: "2024-08-06T00:00:00Z", until: "2024-08-07T00:00:00Z"}) {
      timestamps
      reports {
        impressions
        conversions
        spend
        offerwallAverageRank
      }
    }
  }
}
```

#### 여러 광고 세트로 필터링##filter-for-multiple-ad-sets

이렇게 하면 결과가 \_first\_나 *last* x개 광고 세트로 제한됩니다.

```graphql title="GraphQL"
query {
  advertiser {
    adSets(first: 2) {
      edges {
        node {
          insights(timePreset:TODAY) {
            reports {
              conversions
            }
          }
        }
      }
    }
  }
}
```

#### 퍼블리셔 앱으로 필터링##filter-by-publisher-app

이렇게 하면 결과가 지정된 퍼블리셔 앱 ID로 제한됩니다.

```graphql title="GraphQL"
query {
  adSet(id: "00000000-0000-0000-0000-000000000000") {
    insights(filter:{appIds: ["00000000-0000-0000-0000-000000000000", "00000000-0000-0000-0000-000000000000"]}) {
      timestamps
      reports {
        conversions
      }
    }
  }
}
```

#### 설정된 상태로 필터링##filter-by-configured-status

이렇게 하면 결과가 지정된 상태의 광고 세트나 캠페인으로 제한됩니다.

**옵션**: `ACTIVE`, `ARCHIVED`, `PAUSED`

```graphql title="GraphQL"
query {
  advertiser {
    adSets(first: 2, configuredStatus: ACTIVE) {
      edges {
        node {
          insights(timePreset:TODAY) {
            reports {
              conversions
            }
          }
        }
      }
    }
  }
}
```

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

이렇게 하면 결과가 지정된 국가로 제한됩니다.

```graphql title="GraphQL"
query {
  adSet(id: "00000000-0000-0000-0000-000000000000") {
    insights(filter:{countries: [JP, US]}) {
      timestamps
      reports {
        conversions
      }
    }
  }
}
```

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

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

**옵션**: `LAST 30D`, `LAST WEEK`, `TODAY`, `YESTERDAY`.

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

```graphql title="GraphQL"
query {
  adSet(id: "00000000-0000-0000-0000-000000000000") {
    insights(timePreset:LAST_30D, timeIncrement: DAILY) {
      reports {
        impressions
      }
    }
  }
}
```

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

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

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

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

```graphql title="GraphQL"
query {
  adSet(id: "00000000-0000-0000-0000-000000000000") {
    insights(timeRange: {from: "2024-11-15T00:00:00Z", until: "2024-11-17T00:00:00Z"}, timeIncrement: DAILY) {
      reports {
        impressions
      }
    }
  }
}
```

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

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

* Enums > TargetConnectionType > **MOBILE**
* Enums > TargetDeviceType > **WINDOWS**