인사이트 API

광고 통계를 검색하기 위한 하나의 일관된 인터페이스를 제공합니다.

분석 데이터 - 그룹 결과에 대해 알아보세요.
행동 분석 데이터 - 행동 분석 데이터의 응답을 이해하는 방법을 알아보세요.
비동기 작업 - 결과가 많은 요청에 대해 비동기식 작업을 활용하는 방법을 알아보세요.
제한 및 모범 사례 - 호출 제한, 필터링 및 모범 사례에 대해 알아보세요.

광고 성과 데이터를 가져오기 전에 먼저 관심 있는 지표를 추적하도록 광고를 설정해야 합니다. 광고를 설정하려면 URL 태그, Meta 픽셀, 전환 API를 사용할 수 있습니다.

iOS 14.5 업데이트

Apple이 새로운 정책을 도입함에 따라 Facebook은 기여 기간에 영향을 미칠 핵심 변경 사항을 발표했습니다.

Apple의 iOS 14.5 요구 사항이 Facebook 광고에 미칠 영향에 대해 자세히 알아보려면 비즈니스 고객 센터 문서와 변경 사항을 참조하세요.

영향을 받는 엔드포인트

GET /{ad-account-id}/insights
GET /{ad-id}/insights
GET /{ad-set-id}/insights
GET /{campaign-id}/insights
POST /{ad-account-id}/insights
POST /{ad-id}/insights
POST /{ad-set-id}/insights
POST /{campaign-id}/insights

시작하기 전에

다음과 같은 항목이 필요합니다.

ads_read 권한.
앱. 자세한 내용은 Meta 앱 개발을 참조하세요.

캠페인 통계

최근 7일 동안의 캠페인 성과에 대한 통계를 가져오는 방법은 다음과 같습니다.

curl -G \
  -d "date_preset=last_7d" \
  -d "access_token=ACCESS_TOKEN" \
  "https://graph.facebook.com/API_VERSION/AD_CAMPAIGN_ID/insights"

자세한 내용은 광고 인사이트 참고 자료를 참조하세요.

호출하기

인사이트 API는 모든 광고 개체에서 에지로 사용할 수 있습니다.

API 메서드
`act_<AD_ACCOUNT_ID>/insights`
`<CAMPAIGN_ID>/insights`
`<ADSET_ID>/insights`
`<AD_ID>/insights`

요청

fields 매개변수에서 쉼표로 구분된 리스트가 있는 특정 필드를 요청할 수 있습니다. 예를 들면 다음과 같습니다.

curl -G \
-d "fields=impressions" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_OBJECT_ID/insights"

응답

{
  "data": [
    {
      "impressions": "2466376",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

수준

정의된 개체 수준에서 결과를 집계하세요. 이렇게 하면 데이터가 자동으로 중복 제거됩니다.

요청

예를 들어, 광고 수준에서 캠페인의 인사이트를 확인할 수 있습니다.

curl -G \
-d "level=ad" \
-d "fields=impressions,ad_id" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/CAMPAIGN_ID/insights"

응답

{
  "data": [
    {
      "impressions": "9708",
      "ad_id": "6142546123068",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    },
    {
      "impressions": "18841",
      "ad_id": "6142546117828",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MQZDZD"
    }
  }
}

요청된 수준에서 모든 광고 개체에 대한 액세스 권한이 없으면 인사이트 호출에서 데이터가 반환되지 않습니다. 예를 들어, level을 ad로 설정하여 인사이트를 요청하는데 광고 계정에서 광고 개체 하나 이상에 대한 액세스 권한이 없는 경우 이 API 호출에서 권한 오류를 반환합니다.

기여 기간

iOS 14+ 업데이트

action_attribution_windows를 설정하지 않으면 기본 기여 값이 7d_click과 1d_view가 됩니다. 규정이 시행되기 시작하면 28일 조회를 더 이상 사용할 수 없고 빈 데이터를 반환합니다.
기간 값이 28일로 설정된 비활성화 상태의 기존 광고는 이 데이터를 반환합니다.
기본 또는 계정 수준의 기간은 정책 적용 후에 값이 7일로 설정됩니다.
use_account_attribution_setting 필드는 사용 중단되었습니다. 대신 이러한 요청은 action_attribution_windows 기본값인 7d_click 및 1d_view로 전환됩니다.

iOS 14로 인해 발생한 변경 사항에 대한 자세한 내용은 핵심 변경 사항을 참조하세요.

전환 기여 기간은 이벤트가 Meta 앱의 광고로 인해 발생한 것으로 간주할 기간을 설정합니다. 배경 정보는 Meta 비즈니스 지원 센터, 기여 기간 정보를 참조하세요. Facebook은 전환 이벤트가 발생할 때 해당 행동을 측정한 후 1일 및 7일의 기간을 돌아봅니다. 다른 기여 기간에 발생한 행동을 보려면 /{ad-account-id}/insights에 요청하세요. action_attribution_windows를 제공하지 않은 경우 7d_click을 사용하여 value 아래에 제공합니다.

예를 들어 action_attribution_windows를 지정하면 '값'이 7d_click 기여 기간에 고정됩니다. act_10151816772662695/insights?action_attribution_windows=['1d_click','1d_view']에 요청하면 다음과 같은 결과가 표시됩니다.

"spend": 2352.45,
"actions": [
{
"action_type": "link_click",
"value": 6608,
"1d_view": 86,
"1d_click": 6510
},
"cost_per_action_type": [
{
"action_type": "link_click",
"value": 0.35600030266344,
"1d_view": 27.354069767442,
"1d_click": 0.36135944700461
},

// if attribution window is _not_ specified in query. And note that the number under 'value' key is the same even if attribution window is specified.
// act_10151816772662695/insights
"spend": 2352.45,
"actions": [
{
"action_type": "link_click",
"value": 6608
},
"cost_per_action_type": [
{
"action_type": "link_click",
"value": 0.35600030266344
},

필드 확장

노드 수준에서 필드 확장에 지정된 필드를 기준으로 필드를 요청하세요.

요청

curl -G \
-d "fields=insights{impressions}" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_ID"

응답

{
  "id": "6042542123268",
  "name": "My Website Clicks Ad",
  "insights": {
    "data": [
      {
        "impressions": "9708",
        "date_start": "2016-03-06",
        "date_stop": "2016-04-01"
      }
    ],
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MAZDZD"
      }
    }
  }
}

정렬

sort 매개변수에 {fieldname}_descending 또는 {fieldname}_ascending을 제공하여 결과를 정렬하세요.

요청

curl -G \
-d "sort=reach_descending" \
-d "level=ad" \
-d "fields=reach" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_SET_ID/insights"

응답


{
  "data": [
    {
      "reach": 10742,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    },
    {
      "reach": 5630,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-03"
    },
    {
      "reach": 3231,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-02"
    },
    {
      "reach": 936,
      "date_start": "2009-03-29",
      "date_stop": "2016-04-02"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MQZDZD"
    }
  }
}

광고 레이블

이름이 동일한 모든 레이블에 대한 통계입니다. 광고 개체 수준에서 단일 값으로 집계됩니다. 자세한 내용은 광고 레이블 참고 자료를 참조하세요.

요청

curl -G \  
-d "fields=id,name,insights{unique_clicks,cpm,total_actions}" \
-d "level=ad" \
-d 'filtering=[{"field":"ad.adlabels","operator":"ANY", "value":["Label Name"]}]'  \
-d 'time_range={"since":"2015-03-01","until":"2015-03-31"}' \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_OBJECT_ID/insights"

응답

{
  "data": [
    {
      "unique_clicks": 74,
      "cpm": 0.81081081081081,
      "total_actions": 49,
      "date_start": "2015-03-01",
      "date_stop": "2015-03-31",
    },
  ], 
  "paging": {
    "cursors": {
      "before": "MA==",
      "after": "MA==",
    }
  }
}

클릭 정의

현재 Meta에서 제공하는 클릭 지표를 더 잘 이해하려면 아래에서 각각에 대한 정의 및 사용법을 읽어보세요.

링크 클릭, actions:link_click - Meta에서 소유한 자산 안팎의 특정 랜딩 페이지나 환경으로 연결되는 광고 링크를 클릭한 횟수입니다. 광고주 지원 센터, 링크 클릭을 참조하세요.
클릭(전체), clicks - 광고 컨테이너와의 특정 상호 작용 유형, 다른 랜딩 페이지 링크, 확장된 광고 환경 링크를 포함하여 여러 유형의 광고 클릭을 집계합니다. 광고주 지원 센터, 클릭(전체)을 참조하세요.

삭제 및 보관된 개체

광고 유닛은 DELETED 또는 ARCHIVED 상태일 수 있습니다. 삭제되거나 보관된 개체의 통계는 상위 개체를 쿼리할 때 표시됩니다. 즉, 광고 세트 수준에서 impressions를 쿼리하면 광고가 삭제 또는 보관된 상태에 있는지와 관계없이 세트 내 모든 광고의 impressions가 결과에 포함됩니다. 광고 개체 저장 및 검색 모범 사례도 참조하세요.

그러나 필터링을 사용하여 쿼리할 경우 상태 필터링이 기본적으로 적용되어 활성 개체만 반환합니다. 따라서 상위 노드의 모든 통계가 하위 노드의 통계보다 클 수 있습니다.

추가 filtering 매개변수를 제공하여 상위 노드에서 ARCHIVED 개체의 통계를 가져올 수 있습니다.

요청

나열된 광고 계정의 모든 ARCHIVED 광고에 대한 통계를 차례로 가져오는 방법은 다음과 같습니다.

curl -G \
  -d "level=ad" \
  -d "filtering=[{'field':'ad.effective_status','operator':'IN','value':['ARCHIVED']}]" \
  -d "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/insights/"

응답

이 응답에는 보관된 개체만 반환됩니다.

{
  "data": [
    {
      "impressions": "1741",
      "date_start": "2016-03-11",
      "date_stop": "2016-03-12"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

삭제된 개체 인사이트

해당 개체의 ID나 ad.effective_status 필터를 사용하는 경우 삭제된 개체에 대한 인사이트를 쿼리할 수 있습니다.

요청

예를 들어 광고 세트 ID가 있는 경우 다음 예시를 참조하세요.

curl -G \
-d "fields=id,name,status,insights{impressions}" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_SET_ID"

아래는 ad.effective_status를 사용하여 쿼리하는 방법의 예시입니다.

POST https://graph.facebook.com/<VERSION>/act_ID/insights?access_token=token&appsecret_proof=proof&fields=ad_id,impressions&date_preset=lifetime&level=ad&filtering=[{"field":"ad.effective_status","operator":"IN","value":["DELETED"]}]

응답

{
  "id": "6042147342661",
  "name": "My Like Campaign",
  "status": "DELETED",
  "insights": {
    "data": [
      {
        "impressions": "1741",
        "date_start": "2016-03-11",
        "date_stop": "2016-03-12"
      }
    ],
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MAZDZD"
      }
    }
  }
}

문제 해결

시간 초과

이 엔드포인트에서 오류의 원인이 되는 가장 일반적인 문제는 과도한 요청과 시간 초과입니다.

/GET 또는 동기식 요청에서 메모리 부족 또는 시간 초과 오류가 발생할 수 있습니다.
/POST 또는 비동기 요청에서 시간 초과 오류가 발생할 수 있습니다. 비동기식 요청의 경우 재시도를 포함하여 요청을 완료하는 데 최대 1시간이 걸릴 수 있습니다. 예를 들어, 여러 광고 수준 개체에 대해 과도한 양의 데이터를 가져오려고 쿼리하는 경우가 이에 해당합니다.

권장 사항

쿼리가 실패하는 경우에 대한 명시적인 한도는 없습니다. 쿼리 시간을 초과하면 기간 등의 필터에 추가하여 쿼리를 더 세분화해 보세요.
고유한 지표는 계산하는 데 많은 시간이 걸립니다. 고유하지 않은 지표의 성과를 개선하려면 별도의 호출로 고유한 지표를 쿼리해보세요.

사용 제한

Meta 인사이트 API는 모든 파트너에게 최적의 보고 환경을 제공하기 위해 사용 제한을 활용합니다. 자세한 내용 및 권장 사항은 Meta 인사이트 API 제한 및 모범 사례를 참조하세요.

광고 관리자와의 차이

API의 기본 동작은 광고 관리자에서의 기본 동작과는 차이가 있습니다. 광고 관리자와 동일한 동작을 보고 싶은 경우 use_account_attribution_setting 필드를 true로 설정하세요.

더 알아보기

위의 리스트에 없는 엔드포인트는 이 API에서 다루지 않습니다. 솔루션에 Meta에서 얻은 보고서를 포함하려는 경우 Meta 플랫폼 약관과 마케팅 API의 개발자 정책을 참조하세요.