그래프 API v25.0 및 마케팅 API v25.0 소개

2026년 2월 18일

그래프 API v25.0 및 마케팅 API v25.0 소개

제작: Manjari Jain

V25에 적용되는 새로운 GAPI/MAPI 변경 사항의 주요 내용은 아래와 같습니다. 전체 변경 사항 리스트와 자세한 내용은 변경 사항을 참조하세요.

일반 업데이트

그래프 API: 페이지 조회자 지표 도입

2026년 6월 말까지 그래프 API에 페이지 조회자 지표를 도입할 계획입니다. 조회자 지표는 기존 도달 지표를 대체하며, 여러 플랫폼(Facebook 및 Instagram)에서 콘텐츠를 본 사람의 수를 일관되게 측정합니다. 개발자는 타겟 인사이트에 계속 액세스할 수 있도록 조회자 지표로의 마이그레이션을 계획해야 합니다.

변경 내용

조회자 지표는 페이지 인사이트 및 스토리 인사이트에서 확인할 수 있습니다

게시물/페이지 인사이트

GET {page-id}/insights/page_total_media_view_unique*
GET {post-id}/insights/post_total_media_view_unique*

스토리 인사이트

새로운 지표가 추가될 예정임
GET {stories-id}/insights/metric
- PAGE_STORY_TOTAL_MEDIA_VIEW_UNIQUE

위의 그래프 API는 V25 출시 후 사용할 수 있습니다. 개발자는 그래프 API 변경 사항에서 최신 정보를 확인하는 것이 좋습니다.

Webhooks mTLS 인증서 업데이트

2026년 3월 31일부터 Meta는 Meta가 소유한 다른 인증 기관(CA)을 사용하여 Webhooks mTLS 인증서에 서명하기 시작합니다.

개발자에게 미치는 영향

서버가 Webhooks mTLS 인증서를 요구하고 인증하도록 구성되어 있는 경우, 새로운 Meta CA를 신뢰해야 합니다. 기한까지 신뢰 저장소를 업데이트하지 않으면 TLS 핸드셰이크가 실패하고 서버에서 모든 Webhooks 이벤트 수신이 중지됩니다.

조치 필요: 신뢰 저장소 업데이트

Webhooks를 중단 없이 수신하려면 다음과 같이 해야 합니다.

Meta 루트 CA 인증서 다운로드: Webhooks 시작하기로 이동하여 meta-outbound-api-ca-2025-12.pem이라는 파일을 다운로드합니다.
루트 CA가 Webhooks 요청에 표시될 리프 인증서에 서명합니다.
신뢰 저장소에 추가: 이 인증서를 Webhooks를 수신하는 모든 서버의 신뢰 저장소에 추가합니다.
현재 인증서 유지: 현재 인증서가 활성 상태인 동안 새로운 인증서를 신뢰 저장소에 추가해야 합니다.

중요: 기한이 될 때까지 기다리지 마세요. 3월 31일에 원활한 전환이 이루어질 수 있도록 신뢰 저장소에 새로운 인증서를 즉시 추가해야 합니다.

기한: 2026년 3월 31일 전까지.

변경 사유

현재 Webhooks mTLS 인증서는 DigiCert 루트 CA에 의해 서명됩니다. DigiCert가 클라이언트 인증 EKU 사용을 중단할 계획이므로 2025년 4월 15일에 만료되는 이 루트 CA로 인증서를 갱신할 수 없습니다.

따라서 새로운 Webhooks mTLS 인증서는 Meta 내부 루트 CA에 의해 서명됩니다. 현재 인증서와 동일한 공통 이름(client.webhooks.fbclientcerts.com)이 유지됩니다.

Webhooks mTLS에 대한 공개 문서가 이 변경 사항과 관련된 고지와 함께 업데이트되었습니다. 전환이 완료된 후 2026년 4월에 문서의 모든 기술 상세 정보가 영구적으로 업데이트될 예정입니다.

사용 중단 및 핵심 변경 사항

광고 인사이트 비동기 API의 향상된 오류 메시지

저희는 API를 통해 개발자 경험을 개선하기 위해 지속적으로 노력하고 있습니다. 투명성을 높이고 개발자가 더욱 회복력이 우수한 앱을 빌드할 수 있도록 광고 인사이트 비동기 API GET {AD_REPORT_RUN_ID} 엔드포인트의 오류 보고 방식을 개선합니다.

2026년 2월 18일에 출시될 다음 그래프 API 버전 V25.0부터 개발자는 비동기 보고가 실패할 경우 상세한 오류 정보에 액세스하여 보다 쉽게 실패를 진단하고 API 통합의 효율성을 개선할 수 있게 됩니다. 현재 error_code 필드에 액세스할 수 있는 개발자의 경우, 유형이 uint에서 int로 변경됩니다.

변경 내용

모든 앱에 대해 광고 인사이트 비동기 API GET {AD_REPORT_RUN_ID} 엔드포인트의 응답에 다음과 같은 새로운 기본 필드를 도입합니다.

error_code: 오류 코드입니다. 참고: 현재 해당 필드에 액세스할 수 있는 개발자의 경우, 필드가 uint에서 int로 변경됩니다
error_message: error_code에 해당하는 메시지입니다.
error_subcode: 오류의 특정 하위 코드입니다.
error_user_title: 오류 하위 코드에 대한 사용자 친화적인 제목입니다.
error_user_msg: 오류 하위 코드를 자세히 설명하는 사용자 친화적인 메시지입니다.

이러한 필드는 보고서 실행이 실패할 때 입력됩니다. API 통합을 검토하여 응답에서 새로운 기본 필드와의 호환성을 확인하시기 바랍니다.

이 업데이트는 다음 그래프 API 버전과 함께 출시될 예정입니다. 개발자라면 그래프 API 변경 사항에서 최신 정보를 확인하는 것이 좋습니다. 개발자 문서도 이러한 변경 사항을 반영하여 업데이트되었습니다.

그래프 API: 메타데이터 쿼리 매개변수 사용 중단

그래프 API v25부터 metadata=1 쿼리 매개변수를 사용 중단합니다. 이 매개변수는 이전에 API 응답 내에서 노드의 필드와 연결에 대한 메타데이터를 반환하는 데 사용되었습니다. 이 기능은 사용량이 적어 플랫폼을 단순화하기 위해 사용 중단됩니다. 사용 중단 후에는 API 요청에서 metadata 매개변수가 무시됩니다.

현재 metadata=1을 사용하는 개발자는 공식 API 문서를 통해 각 노드 유형에 사용 가능한 필드와 연결을 알아보아야 합니다.

변경 내용

변경	일정
`metadata=1` 쿼리 매개변수 사용 중단	v25(2026년 2월)
`metadata=1` 쿼리 매개변수 삭제	2026년 5월

변경 전(v24 이하):

그래프 API 요청에 ?metadata=1을 추가하면 사용 가능한 필드와 연결을 포함하여 해당 노드에 대한 추가 메타데이터가 반환되었습니다.

변경 후(v25 이상):

metadata=1 매개변수가 무시됩니다. 이 매개변수를 포함하는 요청은 계속해서 메타데이터가 없는 표준 응답을 반환합니다. 실패나 핵심 변경 사항이 발생하지 않습니다. 요청에 metadata=1이 포함된 경우 오류가 발생하거나 요청이 중단되지 않으며, 매개변수는 단순히 아무런 효과가 없습니다.

그래프 API: 페이지 도달/노출 지표 사용 중단

2026년 6월에 그래프 API에서 게시물/페이지 도달, 동영상 노출, 스토리 노출 지표를 사용 중단할 계획입니다. 이러한 기존 지표는 더 이상 인사이트 도구에 표시되지 않지만 지금까지는 API를 통해 계속 사용할 수 있었습니다.

단일하고 일관된 지표 프레임워크를 바탕으로 제품과 API를 조정하고 전반적인 시스템 안정성을 개선하기 위해 이러한 기존 지표를 사용 중단합니다. 사용 중단 이후 개발자는 기존 노출, 도달, 동영상 시청자 컨셉을 대체하는 새로운 미디어 조회 및 미디어 시청자 지표로 마이그레이션해야 합니다.

변경 내용

다음 지표가 2026년 6월에 모든 API 버전에서 사용 중단됩니다. 개발자라면 그래프 API 변경 사항에서 최신 정보를 확인하는 것이 좋습니다.

게시물/페이지 도달

GET {page-id}/insights/page_impressions_unique*
GET {page-id}/insights/page_impressions_paid_unique*
GET {page-id}/insights/page_impressions_viral_unique*
GET {page-id}/insights/page_impressions_nonviral_unique*
GET {page-id}/insights/page_posts_impressions*
GET {page-id}/insights/page_posts_impressions_unique*
GET {page-id}/insights/page_posts_impressions_paid*
GET {page-id}/insights/page_posts_impressions_paid_unique*
GET {page-id}/insights/page_posts_impressions_organic_unique*
GET {page-id}/insights/page_posts_served_impressions_organic_unique*
GET {page-id}/insights/page_posts_impressions_viral*
GET {page-id}/insights/page_posts_impressions_viral_unique*
GET {page-id}/insights/page_posts_impressions_nonviral*
GET {page-id}/insights/page_posts_impressions_nonviral_unique*
GET {post-id}/insights/post_impressions_unique*
GET {post-id}/insights/post_impressions_paid_unique*
GET {post-id}/insights/post_impressions_fan_unique*
GET {post-id}/insights/post_impressions_organic_unique*
GET {post-id}/insights/post_impressions_viral_unique*
GET {post-id}/insights/post_impressions_nonviral_unique*
GET {post-id}/insights/post_impressions_nonviral_unique*

동영상 노출

GET {video-id}/video_insights/post_impressions_unique
GET {video-id}/video_insights/total_video_impressions
GET {video-id}/video_insights/total_video_impressions_unique
GET {video-id}/video_insights/total_video_impressions_paid_unique
GET {video-id}/video_insights/total_video_impressions_paid
GET {video-id}/video_insights/total_video_impressions_organic_unique
GET {video-id}/video_insights/total_video_impressions_organic
GET {video-id}/video_insights/total_video_impressions_viral_unique
GET {video-id}/video_insights/total_video_impressions_viral
GET {video-id}/video_insights/total_video_impressions_fan_unique
GET {video-id}/video_insights/total_video_impressions_fan
GET {video-id}/video_insights/total_video_impressions_fan_paid_unique
GET {video-id}/video_insights/total_video_impressions_fan_paid

스토리 노출

두 지표가 대체됨
GET {stories-id}/insights/metric
- PAGE_STORY_IMPRESSIONS_BY_STORY_ID
- PAGE_STORY_IMPRESSIONS_BY_STORY_ID_UNIQUE

대신 다음 지표를 사용하는 것이 좋습니다.

GET {page-id}/insights/page_total_media_view_unique
GET {post-id}/insights/post_total_media_view_unique

광고 도달 범위와 일반 도달 범위를 구분하는 경우 다음과 같은 지표를 사용하는 것이 좋습니다. 이 경우 실질적으로 유사한 인사이트를 얻을 수 있습니다.

GET {page-id}/insights/page_media_view
GET {post-id}/insights/post_media_view

그래프 API: 3초 이상 조회한 사람 지표 사용 중단

2026년 6월에 3초 이상 조회한 사람 지표를 사용 중단할 계획입니다. 이러한 기존 지표는 더 이상 인사이트 도구에 표시되지 않지만 지금까지는 그래프 API를 통해 계속 사용할 수 있었습니다.

변경 내용

다음 지표가 2026년 6월에 모든 API 버전에서 사용 중단됩니다. 개발자라면 그래프 API 변경 사항에서 최신 정보를 확인하는 것이 좋습니다.

GET {page-id}/insights/page_video_views_unique
GET {post-id}/insights/post_video_views_organic_unique
GET {post-id}/insights/post_video_views_paid_unique
GET {post-id}/insights/post_video_views_unique
GET {video-id}/video_insights/total_video_views_organic_unique
GET {video-id}/video_insights/total_video_views_paid_unique
GET {video-id}/video_insights/total_video_views_unique

대신 다음 지표를 사용하는 것이 좋습니다.

GET {page-id}/insights/page_total_media_view_unique
GET {post-id}/insights/post_total_media_view_unique

특히 광고 3초 이상 조회한 사람과 일반 3초 이상 조회한 사람을 구분하는 경우 다음과 같은 지표를 사용하는 것이 좋습니다. 이 경우 실질적으로 유사한 인사이트를 얻을 수 있습니다.

GET {page-id}/insights/page_media_view
GET {post-id}/insights/post_media_view

마케팅 API: ASC 및 AAC 사용 중단

자동화 통합을 통해 앱, 판매 및 잠재 고객 캠페인에서 자동화에 최적화된 어드밴티지+ 설정을 기본적으로 사용할 수 있습니다. 또한 광고주와 파트너가 가장 뛰어난 성과를 자랑하는 Meta의 최신 자동화 제품을 간편하게 이용할 수 있습니다. 기존 API에 대한 지원은 단계적으로 중단되며, 마케팅 API 개발자를 대상으로 새로운 자동화 통합, 어드밴티지+ 설정으로의 마이그레이션이 진행됩니다.

V25.0(2026년 2월 18일)부터 ASC 및 AAC 캠페인을 더 이상 마케팅 API를 사용하여 만들거나 업데이트할 수 없으며, 90일 후(2026년 5월 19일까지) 모든 MAPI 버전에 해당 조치가 적용될 예정입니다.

V26.0(2026년 9월 예정)에서는 나머지 ASC 및 AAC 캠페인이 모두 일시 중단됩니다.

기존 고객 예산 한도(ECBC)를 활용하는 ASC 또는 AAC 캠페인은 V26.0까지 계속 수정 가능합니다. 이 기능은 어드밴티지+ 캠페인에서는 제공되지 않습니다. ECBC 캠페인을 사용하는 개발자는 V26.0 전에 아래 방법 중 하나를 사용하여 ECBC 캠페인을 복제해야 합니다.

수동 복제: 광고 관리자에서 ECBC가 포함된 기존 ASC/AAC 캠페인을 열면 '캠페인 복제' 메시지가 표시됩니다. 이 원클릭 단계를 통해 기존 캠페인의 설정을 그대로 적용한 새로운 캠페인이 만들어집니다.
API를 사용하여 ECBC 캠페인 복제: 개발자 문서에 제공된 안내(여기)에 따라 API를 사용하여 캠페인을 복제합니다.
광고 계정 수준에서 일괄 마이그레이션 요청: Facebook 담당자가 지정되어 있는 파트너의 경우, 합의된 날짜에 모든 ECBC 캠페인을 복제하는 일회성 작업을 제공할 수 있습니다. Meta POC에게 연락하여 계정 ID와 마이그레이션을 원하는 날짜를 알리세요.

참고: 모든 ECBC 캠페인 복제의 경우 새로운 캠페인 ID가 생성됩니다.

이 변경 사항은 다음 엔드포인트에 영향을 미칩니다.