유저 가이드개발자 가이드API
대시보드

    Actuals Report

    액츄얼스 리포트(Actuals Report)는 트래킹하고 있는 데이터를 자유롭게 확인할 수 있는 통계 리포트입니다.

    에어브릿지에서 제공하는 다양한 데이터 필드를 활용하여 메트릭을 지정하고 특정 기준(그룹바이)들로 데이터를 세분화하거나 필터를 적용하는 등 원하는 형태로 리포트를 커스텀하게 구성할 수 있습니다.

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

    리포트 생성하기

    POST

    https://api.airbridge.io/reports/api/v7/apps/{app_name}/actuals/query

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

    rate limit: 제한 없습니다.

    Request

    Headers

    Accept-Language
    string

    API 요청 및 결과 반환에 사용할 언어를 지정할 수 있습니다. ISO-639-1 포맷을 따릅니다.

    Content-Type
    string

    리소스의 미디어 타입을 나타냅니다. 기본값으로 application/json을 사용합니다.

    Authorization
    string

    API 요청에 사용하는 키값입니다. 키값 생성 및 조회 방법을 확인하여 획득할 수 있습니다.

    Path Params

    app_name
    필수string

    에어브릿지 앱 이름(App Name)

    Body Params

    from
    필수string

    요청할 리포트 데이터의 시작일.

    • YYYY-MM-DD 형태입니다.

    • 에어브릿지 앱의 타임존이 적용된 날짜이어야 합니다.

    to
    필수string

    요청할 리포트 데이터의 종료일.

    • YYYY-MM-DD 형태입니다.

    • 에어브릿지 앱의 타임존이 적용된 날짜이어야 합니다.

    • 현재 날짜까지 설정할 수 있으며 최대 조회 기간은 92일입니다.

    groupBys
    필수string[]

    리포트 그룹바이.

    세분화하여 보고자 하는 항목을 ‘그룹바이'으로 설정하여 리포트를 조회할 수 있습니다. 액츄얼스 리포트에서 선택할 수 있는 전체 그룹바이 리스트는 메타데이터 가져오기 (GroupBy) API를 통해서 확인 할 수 있습니다.

    최대 10개까지 설정할 수 있습니다.

    metrics
    필수string[]

    리포트 메트릭.

    메트릭으로 다양한 광고 성과 데이터를 조회할 수 있습니다. 액츄얼스 리포트에서 선택할 수 있는 전체 메트릭 리스트는 메타데이터 가져오기 (Metric) API를 통해서 확인 할 수 있습니다.

    최대 20개까지 설정할 수 있습니다.

    filters
    필수object[]

    '그룹바이'로 제공하는 항목들에 대한 필터.

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

    sorts
    필수object[]

    '그룹바이' 또는 '메트릭'을 기준으로 리포트 데이터를 정렬할 수 있습니다.

    option
    object

    추가 옵션을 설정할 수 있습니다.

    Request
    12345
    curl -X POST 'https://api.airbridge.io/reports/api/v7/apps/{app_name}/actuals/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","groupBys":["event_source","event_type","event_category"],"metrics":["app_events"],"filters":[{"dimension":"channel","filterType":"IN","values":["App"]}],"sorts":[{"fieldName":"event_type","isAscending":true}]}'
    Payload
    123456789101112131415161718192021222324252627
    {
  "from": "2022-11-04",
  "to": "2022-11-11",
  "groupBys": [
    "event_source",
    "event_type",
    "event_category"
  ],
  "metrics": [
    "app_events"
  ],
  "filters": [
    {
      "dimension": "channel",
      "filterType": "IN",
      "values": [
        "App"
      ]
    }
  ],
  "sorts": [
    {
      "fieldName": "event_type",
      "isAscending": true
    }
  ]
}

    Response

    200SUCCESS

    task.status

    #{"style":{"minWidth":"130px"}}

    PENDING

    데이터 집계를 위한 준비를 하고 있습니다.

    RUNNING

    데이터를 집계중입니다.

    SUCCESS

    집계가 완료되어 결과값을 반환합니다.

    FAILURE

    요청이 실패하였습니다.

    CANCELED

    요청이 취소되었습니다.

    404ERROR

    Response
    123456
    {
  "task": {
    "status": "RUNNING",
    "taskId": "5e286bd4-b4b1-4c04-8f6a-670dc7ce637d"
  }
}

    리포트 가져오기

    GET

    https://api.airbridge.io/reports/api/v7/apps/{app_name}/actuals/query/{task_id}

    비동기 요청 상태 정의

    비동기 요청 상태는 API 요청 결과의 task.status로 확인할 수 있습니다.

    #{"style":{"minWidth":"130px"}}

    PENDING

    데이터 집계를 위한 준비를 하고 있습니다

    RUNNING

    데이터를 집계중입니다

    SUCCESS

    집계가 완료되어 결과값을 반환합니다

    FAILURE

    알 수 없는 이유로 요청이 실패하였습니다

    CANCELED

    요청이 취소되었습니다

    안내 메세지(Notification) 정의

    집계 과정에서 일부 데이터를 제거하거나 가려졌을 경우(마스킹), notification[0].code에 해당 사유를 확인할 수 있습니다.

    #{"style":{"minWidth":"310px"}}

    MEDIA_PARTNER_DATA_FILTERED_BY_CHANNEL

    미디어 파트너 권한으로 요청을 하여, 데이터 중 볼 수 없는 매체의 데이터를 제외하였습니다.

    AGG_DATA_MASKING_BY_FACEBOOK

    페이스북 개인정보 보호 정책으로 인해 일부 데이터가 제거되거나 가려졌습니다.

    EXCEEDED_LIMIT_ON_MAX_ROW_COUNT

    요청에 해당하는 결과값이 10,000건을 넘습니다. Raw Data Export를 사용해 데이터를 추출하는 것을 권장합니다.

    SAN_PERIOD_LIMIT

    페이스북 등 Self-Attributed Network에 기여된 데이터 중 175일 이전의 데이터를 제거하였습니다.

    메타 개인정보보호정책

    메타 개인정보보호정책에 따라 에어브릿지 리포트에 설정한 조회 기간 동안 발생한 일부 메타 비즈니스(facebook.business) 데이터가 마스킹됩니다. isMasked가 true면 마스킹된 데이터입니다.

    메타 개인정보보호정책에 대한 자세한 내용은 에어브릿지 가이드를 참고해 주세요.

    Request

    Headers

    Accept-Language
    string

    API 요청 및 결과 반환에 사용할 언어를 지정할 수 있습니다. ISO-639-1 포맷을 따릅니다.

    Content-Type
    string

    리소스의 미디어 타입을 나타냅니다. 기본값으로 application/json을 사용합니다.

    Authorization
    string

    API 요청에 사용하는 키값입니다. 키값 생성 및 조회 방법을 확인하여 획득할 수 있습니다.

    Path Params

    app_name
    필수string

    에어브릿지 앱 이름(App Name)

    task_id
    필수string

    '리포트 생성하기' API의 결과값에서 반환한 task_id입니다.

    Query Params

    skip
    number

    결과값에서 건너뛸 Row의 수.

    결과값에서 처음 N개의 Row를 제외하고 가져옵니다.

    기본값은 0 입니다.

    size
    number

    반환할 Row 수.

    skip으로 건너뛴 결과의 다음부터 N개의 Row를 가져옵니다.

    기본값은 100입니다.

    예시) ?skip=200&size=100

    이면 처음 200개를 건너뛰고 201번쨰부터 300번째 까지의 Row를 가져옵니다.

    keyword
    string

    GroupBy에서 필터링할 검색 키워드.

    viewFormat
    booleannullable

    대시보드에서 Actuals Report에 대한 값을 표현해 줄 때 사용하는 포맷 정보를 포함할지 여부를 결정합니다.

    true일 경우 viewFormat 필드에 (메타 애즈 마스킹과 같은) 포맷 정보가 "{value}", "{value} +α", "Privacy Block" 등 과 같은 형태로 추가됩니다.

    기본값은 false 입니다.

    Request
    1234
    curl -X GET 'https://api.airbridge.io/reports/api/v7/apps/{app_name}/actuals/query/{task_id}?skip=0&size=100&viewFormat=false' \
  -H 'Accept-Language: ko' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AIRBRIDGE-API-TOKEN}'

    Response

    200SUCCESS

    데이터 집계가 완료된 결과를 반환합니다. status 가 SUCCESS일 경우, actuals에 데이터 및 메타데이터, 메세지 등을 담아 전송합니다.

    200SUCCESS

    비동기 요청을 처리하는 중입니다.

    해당 API를 주기적으로 폴링(Polling)하여 결과를 확인할 수 있으며, 요청 상태는 요청 상태는 task.status로 확인할 수 있습니다.

    Response
    123456789101112131415161718192021222324252627282930313233343536373839404142434445
    {
  "task": {
    "status": "SUCCESS",
    "taskId": "5e286bd4-b4b1-4c04-8f6a-670dc7ce637d",
    "endedAt": "2022-10-01T00:00:00+00:00"
  },
  "actuals": {
    "data": {
      "rows": [
        {
          "values": {
            "app_installs": {
              "value": 100,
              "isMasked": false,
              "viewFormat": "{value}"
            }
          },
          "groupBys": [
            "<groupBy>"
          ]
        },
        {
          "values": {
            "app_installs": {
              "value": 13,
              "isMasked": true,
              "viewFormat": "{value} +α"
            }
          },
          "groupBys": [
            "<groupBy>"
          ]
        }
      ]
    },
    "metadata": {
      "rowCount": 2
    }
  },
  "pagination": {
    "hasNext": true,
    "totalCount": 200
  },
  "notifications": []
}

    메타데이터 가져오기 (Metric)

    GET

    https://api.airbridge.io/dataspec/v2/apps/{app_name}/actual-report/metrics

    사용할 수 있는 리포트 메트릭을 조회합니다. [참고]

    Request

    Headers

    Accept-Language
    string

    API 요청 및 결과 반환에 사용할 언어를 지정할 수 있습니다. ISO-639-1 포맷을 따릅니다.

    Content-Type
    string

    리소스의 미디어 타입을 나타냅니다. 기본값으로 application/json을 사용합니다.

    Authorization
    string

    API 요청에 사용하는 키값입니다. 키값 생성 및 조회 방법을 확인하여 획득할 수 있습니다.

    Path Params

    app_name
    필수string

    에어브릿지 앱 이름(App Name)

    Request
    1234
    curl -X GET 'https://api.airbridge.io/dataspec/v2/apps/{app_name}/actual-report/metrics' \
  -H 'Accept-Language: ko' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AIRBRIDGE-API-TOKEN}'

    Response

    200SUCCESS

    404ERROR

    입력한 필드에 오류가 있거나 해당하는 리소스가 없습니다.

    Response
    123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778
    {
  "data": [
    {
      "fields": [
        {
          "key": "touchpoints_impression_click",
          "name": "Touchpoints (Impression+click)",
          "description": "Impression 수와 Click 수의 합"
        },
        {
          "key": "impressions",
          "name": "Impressions",
          "description": "Impression 수"
        },
        {
          "key": "clicks",
          "name": "Clicks",
          "description": "Click 수"
        }
      ],
      "groupName": "Touchpoint",
      "parentGroupName": "Touchpoint"
    },
    {
      "fields": [
        {
          "key": "app_events",
          "name": "Events (App)",
          "description": "앱에서 발생한 이벤트 수"
        },
        {
          "key": "app_event_value",
          "name": "Event 값 (App)",
          "description": "앱에서 발생한 이벤트 값의 합"
        }
      ],
      "groupName": "App Event",
      "parentGroupName": "App"
    },
    {
      "fields": [
        {
          "key": "app_installs",
          "name": "Installs (App)",
          "description": "Install 수"
        },
        {
          "key": "app_first_installs",
          "name": "First Installs (App)",
          "description": "최초로 설치된 Install 수"
        }
      ],
      "groupName": "App Install",
      "parentGroupName": "App"
    },
    {
      "fields": [
        {
          "key": "app_sign_up",
          "name": "회원가입 (App)",
          "description": "앱에서 발생한 회원가입 이벤트 수"
        },
        {
          "key": "app_sign_in",
          "name": "로그인 (App)",
          "description": "앱에서 로그인 이벤트 수"
        },
        {
          "key": "app_sign_out",
          "name": "로그아웃 (App)",
          "description": "앱에서 로그아웃 이벤트 수"
        }
      ],
      "groupName": "App Standard Event",
      "parentGroupName": "App"
    }
  ]
}

    메타데이터 가져오기 (GroupBy)

    GET

    https://api.airbridge.io/dataspec/v2/apps/{app_name}/actual-report/fields

    사용할 수 있는 리포트 그룹바이를 조회합니다. [참고]

    Request

    Headers

    Accept-Language
    string

    API 요청 및 결과 반환에 사용할 언어를 지정할 수 있습니다. ISO-639-1 포맷을 따릅니다.

    Content-Type
    string

    리소스의 미디어 타입을 나타냅니다. 기본값으로 application/json을 사용합니다.

    Authorization
    string

    API 요청에 사용하는 키값입니다. 키값 생성 및 조회 방법을 확인하여 획득할 수 있습니다.

    Path Params

    app_name
    필수string

    에어브릿지 앱 이름(App Name)

    Request
    1234
    curl -X GET 'https://api.airbridge.io/dataspec/v2/apps/{app_name}/actual-report/fields' \
  -H 'Accept-Language: ko' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AIRBRIDGE-API-TOKEN}'

    Response

    200SUCCESS

    404ERROR

    입력한 필드에 오류가 있거나 해당하는 리소스가 없습니다.

    Response
    123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778
    {
  "data": [
    {
      "fields": [
        {
          "key": "event_date",
          "name": "Event Date",
          "example": "2019-05-31",
          "description": "이벤트 발생 날짜와 시간 (YYYY-MM-DD)",
          "serveToFilter": true
        },
        {
          "key": "event_year",
          "name": "Event Year",
          "example": "2019",
          "description": "이벤트 발생 년도",
          "serveToFilter": true
        },
        {
          "key": "event_month",
          "name": "Event Month",
          "example": "04",
          "description": "이벤트 발생 월",
          "serveToFilter": true
        }
      ],
      "groupName": "Event Datetime",
      "parentGroupName": null
    },
    {
      "fields": [
        {
          "key": "event_source",
          "name": "Event Source",
          "example": "App",
          "description": "Event가 발생한 소스",
          "serveToFilter": true
        },
        {
          "key": "event_type",
          "name": "Event Type",
          "example": "Impression",
          "description": "Event 타입",
          "serveToFilter": true
        },
        {
          "key": "event_category",
          "name": "Event Category",
          "example": "Move to App Store (Link)",
          "description": "Event 카테고리",
          "serveToFilter": true
        }
      ],
      "groupName": "Event Hierarchy",
      "parentGroupName": null
    },
    {
      "fields": [
        {
          "key": "channel",
          "name": "Channel",
          "example": "moloco",
          "description": "Touchpoints 와 Conversion이 발생한 Channel\n",
          "serveToFilter": true
        },
        {
          "key": "campaign",
          "name": "Campaign",
          "example": "2018_summer_campaign",
          "description": "Touchpoints 와 Conversion이 발생한 Campaign \n(SAN Publisher 대시보드에서 입력한 값 또는 Tracking Link의 캠페인 파라미터 값)",
          "serveToFilter": true
        }
      ],
      "groupName": "Touchpoint",
      "parentGroupName": null
    }
  ]
}

    도움이 되었나요?

    더 필요한 내용이 있나요?