> ## Documentation Index
> Fetch the complete documentation index at: https://help.airbridge.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 리포트 생성하기

레비뉴 리포트(Revenue Report)는 매출에 관한 다양한 지표를 확인할 수 있는 통계 리포트입니다. 에어브릿지 사용자는 이 리포트에서 설정한 기간에 앱을 설치하거나 딥링크로 앱에 유입된 유저가 발생시킨 매출 관련 성과를 일자별(Day N)로 확인할 수 있습니다.

또한, 요청 횟수에 대한 제한이 없어 필요할 때마다 자유롭게 리포트를 생성할 수 있습니다.

Revenue Report의 통계 데이터를 요청합니다.

해당 API를 호출하여 `task_id`를 생성한 뒤, 생성한 `task_id`를 '리포트 가져오기' 호출에 사용하여 요청 상황을 확인하고 데이터를 확인할 수 있습니다. 리포트 결과는 요청에 따라 최대 5분까지 소요될 수 있습니다.

rate limit: 일반적인 사용량에는 별도의 제한이 없습니다. 다만, 서비스 안정성을 위협하는 과도한 요청이 감지될 경우, 일시적으로 429 Too Many Requests 응답이 반환될 수 있습니다.

<Card title="Try API Request" icon="rectangle-api" horizontal href="https://www.postman.com/airbridge-engineering/workspace/airbridge-api/request/22395869-1f99e448-f982-4854-9127-c874bdfdefcc" />

```text POST theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
https://api.airbridge.io/reports/api/v3/apps/{app_name}/revenue/query
```

<h2 id="리포트-생성하기-request">
  Request
</h2>

***

<h3 id="리포트-생성하기-headers">
  Headers
</h3>

<ParamField header="Accept-Language" type="string">
  API 요청 및 결과 반환에 사용할 언어를 지정할 수 있습니다. ISO-639-1 포맷을 따릅니다.
</ParamField>

<ParamField header="Content-Type" type="string">
  리소스의 미디어 타입을 나타냅니다. 기본값으로 `application/json`을 사용합니다.
</ParamField>

<ParamField header="Authorization" type="string">
  API 요청에 사용하는 키값입니다. [키값 생성 및 조회 방법](/ko/references/introduction)을 확인하여 획득할 수 있습니다.
</ParamField>

<h3 id="리포트-생성하기-path-params">
  Path Params
</h3>

<ParamField path="app_name" type="string" required>
  에어브릿지 앱 이름(App Name)
</ParamField>

<h3 id="리포트-생성하기-body-params">
  Body Params
</h3>

<ParamField body="from" type="string" required>
  요청할 리포트 데이터의 시작일.

  * `YYYY-MM-DD` 형태입니다.
  * 에어브릿지 앱의 타임존이 적용된 날짜이어야 합니다.
</ParamField>

<ParamField body="to" type="string" required>
  요청할 리포트 데이터의 종료일.

  * `YYYY-MM-DD` 형태입니다.
  * 에어브릿지 앱의 타임존이 적용된 날짜이어야 합니다.
  * 현재 날짜까지 설정할 수 있으며 한 번에 조회할 수 있는 최대 기간은 92일입니다.
</ParamField>

<ParamField body="cohorts" type="object[]">
  최대 1개의 코호트를 설정할 수 있습니다.

  [여기](https://www.postman.com/airbridge-engineering/workspace/airbridge-api/request/22395869-fe6e8212-2259-4bae-9306-0566e7786a68?ctx=documentation)에서 코호트 코드 예시를 확인할 수 있습니다.

  <Expandable title="하위 변수">
    <ParamField body="cohorts[0].id" type="number" required>
      0으로 입력해 주세요. 다른 값은 지원하지 않습니다.
    </ParamField>

    <ParamField body="cohorts[0].name" type="string" required>
      Cohort로 입력해 주세요. 다른 값은 지원하지 않습니다.
    </ParamField>

    <ParamField body="cohorts[0].definition" type="object" required>
      레비뉴 리포트에서 사용하는 코호트를 정의합니다. 항상 `andClauses`, `orClauses`, `segment` 순서로 하위 변수를 정의합니다. 아래에서 각 변수의 관계를 확인하세요.

      <Expandable title="하위 변수">
        <ParamField body="cohorts[0].definition.andClauses" type="object[]" required>
          코호트 정의의 최상위 조건입니다. 설정한 조건을 모두 and로 연결합니다. 하위 변수로 `negated`와 `orClauses`를 반드시 설정해야 합니다.

          * `negated` (boolean): `orClauses`에 설정한 조건의 부정 여부를 설정합니다.

            * `true`: `orClauses`에 설정한 조건을 부정합니다. 따라서 `orClauses`에 설정한 조건이 거짓입니다.
            * `false`: `orClauses`에 설정한 조건을 부정하지 않습니다. 따라서 `orClauses`에 설정한 조건이 참입니다.

          cohorts\[0].definition.andClauses\[\*].**orClauses** | <em>필수 ・</em> object\[]

          `andClauses` 하위에 설정하는 조건입니다. 설정한 조건을 모두 or로 연결합니다. 하위 변수로 `negated` 와 `segment`를 반드시 설정해야 합니다.

          * `negated` (boolean): `orClauses`에 설정한 조건의 부정 여부를 설정합니다.

            * `true`: `orClauses`에 설정한 조건을 부정합니다. 따라서 `orClauses`에 설정한 조건이 거짓입니다.
            * `false`: `orClauses`에 설정한 조건을 부정하지 않습니다. 따라서 `orClauses`에 설정한 조건이 참입니다.

          cohorts\[0].definition.andClauses\[\*].orClauses\[\*].**segment** | <em>필수 ・</em> object

          코호트 정의의 최소 조건입니다. 하위 변수로 `event`, `filters`, `time`을 설정할 수 있습니다.

          * `event` (object): 유저가 발생시킨 이벤트와 이벤트 발생 횟수를 정의할 수 있습니다. 하위 변수로 `type`, `operator`, `value`를 설정할 수 있습니다.

            * `type` (string): 유저가 발생시킨 이벤트를 설정합니다. `any-event`를 사용하면 모든 이벤트로 설정할 수 있습니다. 설정할 수 있는 다른 이벤트는 \[[에어브릿지 데이터 스펙](https://docs.google.com/spreadsheets/d/13ThNnryqRmZQwJVecM8lZ2OB7LzA8s3cwLlQBGpbXLg/edit#gid=1066355972)]>\[Revenue Report -  Audience Events]의 Event Key 열에서 확인할 수 있습니다.  , `_` 사용에 주의해 주세요.
            * `operator` (enum): 이벤트 발생 횟수에 사용하는 비교 연산자를 설정할 수 있습니다. `equals`, `more than or equals`, `more than`, `less than or equals`, `less than` 등 총 5가지 중에서 1가지만 사용할 수 있습니다 .
            * `value` (number): 이벤트 발생 횟수를 설정할 수 있습니다. 자연수를 입력해 주세요.
          * `filters` (object\[]): 정의한 이벤트 중 특정 이벤트만 확인할 수 있습니다. 코호트 정의의 had property와 같습니다. 하위 변수로 `field`, `filterType`를 설정할 수 있습니다.

            * `field` (string): 필터로 설정할 수 있는 프로퍼티입니다. 설정할 수 있는 프로퍼티는 \[[에어브릿지 데이터 스펙](https://docs.google.com/spreadsheets/d/13ThNnryqRmZQwJVecM8lZ2OB7LzA8s3cwLlQBGpbXLg/edit#gid=66435896)]>\[Revenue Report- Audience Properties]의 Property Key 열을 참고해 주세요.
            * `filterType` (enum): 프로퍼티에 사용할 수 있는 연산자를 설정합니다. 설정한 프로퍼티에 따라 사용할 수 있는 연산자와 필터로 설정하는 값(없음, value, values)이 변경됩니다.

          | filterType                  | 프로퍼티 데이터 타입                 | 하위 변수  |
          | --------------------------- | --------------------------- | ------ |
          | is / is not                 | string, boolean             | values |
          | contains / does not contain | string                      | value  |
          | exists / does not exist     | string, boolean, int, float | 없음     |
          | equals / does not equal     | int, float                  | value  |
          | does not equal              | int, float                  | value  |
          | greater than or equals      | int, float                  | value  |
          | greater than                | int, float                  | value  |
          | less than or equals         | int, float                  | value  |
          | less than                   | int, float                  | value  |
          | between                     | int, float                  | values |
          | does not between            | int, float                  | value  |

          * `time` (object): 이벤트가 발생한 시각에 대한 조건을 설정할 수 있습니다. 설정한 조건에 따라 하위 변수가 변경됩니다.

            * `operator` (enum): `during`, `between`, `since` 중에서 조건을 설정합니다. 3가지 중에서 1가지만 설정할 수 있습니다. 조건이 `between`이면 조회 기간은 2023년 2월 1일부터 설정할 수 있습니다. 최대로 설정할 수 있는 조회 기간은 90일입니다.

          | Operator | 하위 변수                | 설명                            |
          | -------- | -------------------- | ----------------------------- |
          | during   | values, isNowEnabled | isNowEnabled은 오늘 포함 여부를 설정합니다 |
          | between  | values               | values에 시작일과 종료일을 모두 설정해야 합니다 |
          | since    | values               | 시작일만 설정합니다                    |
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="groupBy" type="object" required>
  그룹바이는 조회할 메트릭의 수치를 나누는 기준입니다.
  조회에 사용할 그룹바이 항목 혹은 코호트를 설정할 수 있습니다.

  <Expandable title="하위 변수">
    <ParamField body="groupBy.fields" type="string[]" required>
      리포트 그룹바이.

      최대 6개의 그룹바이를 설정할 수 있으며, 선택할 수 있는 리스트는 [그룹바이 목록](https://docs.google.com/spreadsheets/d/13ThNnryqRmZQwJVecM8lZ2OB7LzA8s3cwLlQBGpbXLg/edit#gid=1419762398)에서 확인할 수 있습니다.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="granularity" type="enum" required>
  분석 기간 주기.

  | 벨류      | 설명                                                                                        |
  | ------- | ----------------------------------------------------------------------------------------- |
  | `day`   | 일별로 데이터를 분석합니다.                                                                           |
  | `week`  | 주별로 데이터를 분석합니다. 시작일로부터 7일 단위로 계산됩니다.                                                      |
  | `month` | 월별로 데이터를 분석합니다. 시작일로부터 다음달 같은 일자까지를 같은 달로 계산합니다. 예를 들어 3월 10일이 시작일이면 4월 10일까지를 같은 달로 봅니다. |
</ParamField>

<ParamField body="intervalsPeriodIndexes" type="number[]">
  주기에 따라 제공되는 구간 범위이며, 레비뉴 리포트 결과는 주기에 따라 조회 기간이 여러 구간으로 나뉘어 제공됩니다.

  * `0`(Day 0) 은 자동으로 추가되지 않습니다. 사용자가 명시적으로 요청하지 않으면 결과에 포함되지 않습니다.
  * 주기가 `day`, `week`, `month`면 선택 가능 범위는 각각 `0~180`, `0~52`, `0~36`입니다.
  * 주기가 hour, minute 이면 사용하지 않습니다. 구간은 각각 `59`, `23` 으로 고정 처리됩니다.
</ParamField>

<ParamField body="startEvents" type="enum[]" required>
  설정한 기간에 유저가 유입되면서 발생한 이벤트.

  스타트 이벤트를 실행하지 않은 유저는 레비뉴 리포트의 분석 대상에서 제외됩니다.

  | 벨류                      | 설명                                                          |
  | ----------------------- | ----------------------------------------------------------- |
  | `app_install`           | Install (App). 선택 기간 내 발생한 Install 이벤트.                     |
  | `app_deeplink_open`     | Deeplink Open (App). 선택 기간 내 발생한 Deeplink Open 이벤트.         |
  | `app_deeplink_pageview` | Deeplink Pageview (App). 선택 기간 내 발생한 Deeplink Pageview 이벤트. |
  | `app_sign_up`           | 회원가입 (App). 선택 기간 내 발생한 앱 회원가입 이벤트.                         |
  | `app_sign_in`           | 로그인 (App). 선택 기간 내 발생한 앱 로그인 이벤트.                           |
</ParamField>

<ParamField body="returnEvents" type="enum[]" required>
  스타트 이벤트를 실행한 유저가 발생시킨 리턴 이벤트. 서비스 또는 캠페인 특성에 따라 여러 개의 리턴 이벤트를 설정할 수 있습니다.

  | 벨류                         | 설명                                                                 |
  | -------------------------- | ------------------------------------------------------------------ |
  | `app_order_complete`       | 구매 완료 (App). Start Event를 수행한 사용자 중 선택 기간 내 수행한 구매 완료 이벤트.         |
  | `app_first_order_complete` | 첫 구매 완료 (App). Start Event를 수행한 사용자 중 선택 기간 내 수행한 첫 구매 이벤트.        |
  | `app_ad_impression`        | Ad Impression (App). Start Event를 수행한 사용자 중 선택 기간 내 수행한 광고 노출 이벤트. |
  | `app_ad_click`             | 광고 클릭 (App). Start Event를 수행한 사용자 중 선택 기간 내 수행한 광고 클릭 이벤트.         |
  | `app_subscribe`            | 구독 (App). Start Event를 수행한 사용자 중 선택 기간 내 수행한 구독 이벤트.               |
</ParamField>

<ParamField body="metric" type="enum" required>
  레비뉴 리포트 메트릭.

  스타트 이벤트와 레비뉴 이벤트를 실행한 유저를 대상으로 아래의 메트릭을 일자별로 계산할 수 있습니다.

  | 벨류                | 설명                                                                                |
  | ----------------- | --------------------------------------------------------------------------------- |
  | `app_revenue`     | Revenue (App). 앱에서 발생한 결제의 매출액 (현지 통화기준). cumulative, on-day 집계 방식을 지원합니다.        |
  | `app_user_count`  | User Count (App). 레비뉴 이벤트를 실행한 고유 유저수                                             |
  | `app_event_count` | Event Count (App). 레비뉴 이벤트 횟수                                                     |
  | `app_roas`        | ROAS (App). 광고 비용당 매출. 마케팅 활동에 지출한 비용 대비 매출액 (현지 통화 기준). cumulative 집계 방식만 지원합니다. |
  | `app_arpu`        | ARPU (App). 유저당 평균 매출액 (현지 통화기준). cumulative 집계 방식만 지원합니다.                        |
  | `app_arppu`       | ARPPU (App). 결제 유저(Paying User)당 평균 매출액.                                          |
</ParamField>

<ParamField body="aggregationType" type="enum" required>
  데이터의 집계 방식. \[[참고](https://help.airbridge.io/hc/ko/articles/4409764368409-Revenue?utm_source=Zendesk#메트릭-표시-방식)]

  | 벨류           | 설명                                                   |
  | ------------ | ---------------------------------------------------- |
  | `cumulative` | 누적 집계. 분석 기간 첫 날(Day 0)부터 마지막 날(Day N)까지의 수치를 누적합니다. |
  | `on-day`     | 분절 집계. 수치를 누적하지 않고 날짜 단위로 분절합니다.                     |
</ParamField>

<ParamField body="filters" type="object[]" required>
  '그룹바이'로 제공하는 항목들에 대한 필터.

  조건을 만족하는 데이터에 대한 통계 데이터를 리포트에서 조회할 수 있습니다.

  <Expandable title="하위 변수">
    <ParamField body="filters[0].field" type="string" required>
      필터를 지정할 그룹바이.

      `groupBys` 내에 정의된 값만 사용하실 수 있습니다.
    </ParamField>

    <ParamField body="filters[0].filterType" type="enum" required>
      필터에 적용할 연산자.

      | 벨류          | 설명                                            |
      | ----------- | --------------------------------------------- |
      | `IN`        | 속해있다. 액츄얼스 리포트에서는 같다(is, =)에 대응합니다.           |
      | `NOT IN`    | 속해있지 않다. 액츄얼스 리포트에서는 같지 않다(is not, ≠)에 대응합니다. |
      | `LIKE`      | 포함한다. (contains, ∋)                           |
      | `NOT LIKE`  | 포함하지 않는다. (does not contain, ∌)               |
      | `EXIST`     | 값이 존재한다. (exists)                             |
      | `NOT EXIST` | 값이 존재하지 않는다. (does not exist)                 |
    </ParamField>

    <ParamField body="filters[0].values" type="string[]">
      필터에 적용할 값.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="sorts" type="object[]" required>
  '그룹바이' 또는 '메트릭'을 기준으로 리포트 데이터를 정렬할 수 있습니다.

  <Expandable title="하위 변수">
    <ParamField body="sorts.[0].fieldName" type="string" required>
      필터를 지정할 그룹바이 또는 메트릭.

      `groupBy.dimensions` 또는 `subMetrics` 내에 정의된 값만 사용하실 수 있습니다.
    </ParamField>

    <ParamField body="sorts.[0].isAscending" type="boolean">
      오름차순 정렬.

      * true: 오름차순
      * false: 내림차순
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="resultSpec" type="object">
  결과 값의 형태를 선택할 수 있습니다.

  <Expandable title="하위 변수">
    <ParamField body="resultSpec.csv" type="object">
      csv의 형태를 설정합니다.

      <Expandable title="하위 변수">
        <ParamField body="resultSpec.csv.includesMetadata" type="boolean">
          metadata 를 포함할지 여부. (선택한 startEvent, groupBy 등)
        </ParamField>

        <ParamField body="resultSpec.csv.includesTotal" type="boolean">
          total 데이터를 포함할지 여부.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<RequestExample>
  ```shellscript Request theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
  curl -X POST 'https://api.airbridge.io/reports/api/v3/apps/{app_name}/revenue/query' \
    -H 'Accept-Language: ko' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {AIRBRIDGE-API-TOKEN}' \
    -d '{
    "from": "2022-11-04",
    "to": "2022-11-11",
    "groupBy": {
      "fields": [
        "channel"
      ]
    },
    "granularity": "day",
    "intervalsPeriodIndexes": [
      1,
      3,
      7
    ],
    "startEvents": [
      "app_install"
    ],
    "returnEvents": [
      "app_order_complete"
    ],
    "metric": "app_revenue",
    "aggregationType": "cumulative",
    "filters": [
      {
        "field": "campaign",
        "filterType": "IN",
        "values": [
          "App"
        ]
      }
    ],
    "sorts": [
      {
        "fieldName": "totalRevenue",
        "isAscending": true
      }
    ],
    "resultSpec": {
      "csv": {
        "includesTotal": true
      }
    }
  }'
  ```
</RequestExample>

<h2 id="리포트-생성하기-response">
  Response
</h2>

***

### 200

### 400

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
  {
    "data": {
      "taskId": "5e286bd4-b4b1-4c04-8f6a-asdf1234zxcv"
    }
  }
  ```

  ```json 400 theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
  {}
  ```
</ResponseExample>