마케팅 API

버전 관리

마케팅 API의 현재 버전은 v21.0입니다.

Facebook 플랫폼에는 코어 및 확장 버전 관리 모델이 있습니다. 마케팅 API 버전 관리를 사용하면 모든 주요 변경 사항을 새 버전에서 확인할 수 있습니다. 버전마다 다른 기능이 포함된 여러 버전의 마케팅 API 또는 SDK가 동시에 존재할 수 있습니다.

개발자는 마케팅 API 또는 SDK가 언제 변경되는지 미리 파악해야 합니다. 변경 사항 적용 기간은 90일이지만 새 버전으로 이동하는 방법과 시기는 개발자가 결정합니다.

버전 일정

마케팅 API의 새 버전이 출시되는 경우, Facebook에서는 마케팅 API의 이전 버전을 최소 90일 동안 계속 지원합니다. 새 버전으로 이동하기 위한 유예 기간은 최소 90일입니다. 90일의 유예 기간 동안에는 현재 버전과 사용 중단된 버전을 모두 호출할 수 있으며 90일 유예 기간 이내에 새 버전으로 이동해야 합니다. 90일의 유예 기간이 종료된 후에는 사용 중단된 버전이 더 이상 작동하지 않습니다. 버전을 사용할 수 없게 되면 해당 버전 번호로 보낸 호출은 실패하거나 다음으로 사용 가능한 버전으로 자동 업그레이드될 수 있습니다.

예를 들어 마케팅 API v17.0은 2023년 5월 23일에 출시되었고 마케팅 API v16.0은 2024년 2월 6일에 만료되어 새 버전으로 이동하기 위한 유예 기간을 90일 이상 제공했습니다.

샘플 타임라인은 다음과 같습니다. 이전 버전의 사용 중단에 대한 90일 유예 기간이 종료될 때 항상 새 버전이 출시되는 것은 아닙니다. 예시에서 v16.0은 v18.0이 출시되기 얼마 전에 사용 중단되었습니다.

SDK의 경우 다운로드할 수 있는 패키지이므로 버전이 항상 이용 가능한 상태이지만, 사용 종료된 후에는 더 이상 작동하지 않는 마케팅 API 또는 메서드에 의존할 수 있으므로 사용 종료된 SDK는 더 이상 작동하지 않는다고 가정해야 합니다.

버전이 지정된 요청 보내기

모든 마케팅 API 엔드포인트는 버전이 지정된 경로를 통해 이용할 수 있습니다. 요청 경로 앞에 버전을 붙입니다. 예를 들면 다음과 같습니다.

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/v21.0/me/adaccounts"

이 방법은 모든 버전에 적용되며, 일반적인 형식은 다음과 같습니다.

https://graph.facebook.com/v{n}/{request-path}

여기서 n은 필요한 버전을 나타냅니다. 변경 사항에 있는 이용 가능한 버전의 전체 리스트를 참조하세요. 모든 마케팅 API 참고 자료는 버전별 정보를 제공합니다.

마이그레이션

마이그레이션은 버전 관리로 이동할 수 없는 변경이 필요한 특별한 시나리오에만 사용됩니다. 일반적으로 기본 데이터 모델이 변경된 경우가 이에 해당합니다. 마이그레이션은 모든 버전에 적용됩니다.

현재 진행 중인 마이그레이션은 마이그레이션 페이지에 기록되어 있습니다. 마이그레이션에는 90일 이상의 기간이 주어지며, 이 기간 동안에 앱을 마이그레이션해야 합니다. 기간이 시작되면 마이그레이션 이후 동작이 새 앱을 위한 기본값이 됩니다. 그런 다음 마이그레이션 기간이 종료되면 마이그레이션 이전 동작이 완전히 이용 중단됩니다.

그래프 API를 통한 마이그레이션 관리

마이그레이션은 /app 노드의 마이그레이션 필드를 통해 관리할 수 있습니다.

에지에서 업데이트 호출을 만들어 마이그레이션을 활성화하거나 비활성화할 수 있습니다.

앱 대시보드를 통한 마이그레이션 관리

앱 대시보드의 설정 > 마이그레이션에서 사용 가능한 마이그레이션을 활성화하거나 비활성화할 수 있습니다. 사용 가능한 마이그레이션은 앱, 시간별로 다르기 때문에 마이그레이션 리스트가 아래 이미지와 다를 수도 있습니다. Use Graph API v2.0 by default 마이그레이션이 표시되는 경우 마케팅 API가 아닌 그래프 API 전용 마이그레이션을 나타냅니다.

임시 클라이언트 측 마이그레이션 활성화

앱 대시보드에서나 마케팅 API를 통해 마이그레이션을 활성화하는 대신 마이그레이션을 설정하는 특별한 플래그를 마케팅 API 호출에 추가할 수 있습니다. 플래그는 migrations_override라고 하며 설정하거나 해제할 마이그레이션을 설명하는 JSON Blob을 지정해야 합니다. 예를 들어 원시 호출을 하는 경우 다음을 전달할 수 있습니다.

http://graph.facebook.com/path?
  migrations_override={"migration1":true, "migration2":false}

이를 사용하여 모든 호출자가 동시에 새 마케팅 API를 호출하도록 업데이트하는 대신 클라이언트 업데이트를 통해 새 마케팅 API를 호출할 수 있습니다. 디버깅에도 매우 유용합니다.

이러한 마이그레이션의 이름은 /app 위에 언급된 노드에서 확인할 수 있습니다.

버전 자동 업그레이드

Facebook에서는 마케팅 API 버전이 약 4개월 주기로 빠르게 순환하는 것을 고려하여 업그레이드 프로세스를 간소화하고 있습니다. 2024년 5월부터 버전 간에 영향을 받지 않는 마케팅 API 엔드포인트에 대한 자동 버전 업그레이드 기능이 활성화됩니다. 즉, 사용 중단될 버전과 다음으로 사용 가능한 버전 간에 엔드포인트가 영향을 받지 않는 경우, Facebook 플랫폼은 요청 처리를 직접 거부하기보다 다음으로 사용 가능한 버전으로 호출을 업그레이드합니다. 이 변경 사항은 더 원활하고 효율적인 API 경험을 제공하기 위해 고안되었습니다.

예를 들어 2024년 5월 14일에 v17.0이 사용 중단됩니다. v18.0 변경 사항에 따르면 다음 엔드포인트가 영향을 받습니다.

  • POST /act_{ad-account-id}/reachfrequencypredictions
  • GET /act_{ad-account-id}/reachestimate
  • GET /act_{ad-account-id}/delivery_estimate
  • POST /act_{ad-account-id}/adsets
  • POST /{adset-id}
  • POST /act_{ad-account-id}/saved_audiences
  • POST /{saved-audience-id}
  • POST /act_{ad-account-id}/credit_cards

2024년 5월 14일에 v17.0이 사용 중단된 후에 앱이 v17.0으로 POST /{adset-id} 호출을 보내는 경우, 다음으로 사용 가능한 버전(v18.0)의 영향을 받는 엔드포인트에 자동 업그레이드가 적용되지 않으므로 이 API 요청이 실패합니다.

v17.0이 사용 중단된 후에 앱이 v17.0으로 GET /{ad-account-id}/insights 호출을 보내는 경우, Facebook 플랫폼이 다음으로 사용 가능한 버전(v18.0)으로 호출을 업그레이드합니다.

참고: 앱이 이미 v17.0보다 높은 버전으로 호출을 보내고 있는 경우, 버전 사용 중단 날짜와 관련하여 아무것도 변경되지 않습니다.

각 버전에서 영향을 받는 엔드포인트를 확인하려면 마케팅 API 변경 사항을 참조하세요.

FAQ

버전 일정

We refer to this as an unversioned call. Unversioned calls are invalid and will fail when made against Marketing API endpoints.

고유 링크

You can call the version of the Marketing API that was the latest available when the app was created, as long as it has not been deprecated. It can also make calls to any newer, undeprecated versions launched after the app is created.

Starting May 14, 2024, if a deprecated version is provided, the platform may upgrade selected endpoints to the next available version instead of failing the request. To learn more about the behavior, refer to Marketing API Auto-version upgrade.

For example:

  • If your app was created before the launch of v17.0, while v16.0 was available, then it will be able to make calls to v16.0 until the expiration date of that version. After v16.0 has been deprecated, calls to v16.0 will fail.
  • If your app was created after v17.0 was released, it will be able to make calls to v17.0 until the expiration date of that version, and any subsequent versions (v18.0, etc) until their expiration dates. After v17.0 has been deprecated, calls to v17.0 will fail.
  • Your app will not be able to make calls to v16.0, since 1) that was before your app was created and 2) that version is deprecated and calls to v16.0 may fail or be upgraded to the next available version.

If an app was not used - to make any Marketing API calls or requests - after being created, it will not have the ability to use those versions if any newer version is launched. Here's another example to explain this:

  • If your app was created while v16.0 was the latest version available, but not used until after v17.0 had launched, it will only be to use v17.0, and not v16.0.
  • If your app was created while v16.0 was the latest version available, and then used before v17.0 had launched, it will still be able to use v16.0 even after the launch of v17.0.
고유 링크

There are a few differences between how Marketing API and the rest of Graph API. For the details on Platform API versioning, see Graph API, Versioning.

  1. Marketing API is versioned on a 90-day deprecation schedule, whereas Platform API has core and extended APIs with a 2 year guarantee for core APIs.
  2. Marketing API does not support unversioned calls. If you do not specify a working version in your call, it fails.
고유 링크

버전이 지정된 요청 보내기

With migrations, you set migration on or off in App Dashboard, as described in the Migrations section. With versioning, we are making Marketing API functionality more transparent by moving the setting into the endpoint:

https://graph.facebook.com/v{n}/{request-path}

You can know what behavior to expect out without having to manually visit your app's migration panel.

고유 링크

버전 자동 업그레이드

The upgrade will apply on any deprecated version to the next available version. This means hypothetically if your app is making calls to v15.0 after v16.0 is deprecated, the call will also be upgraded to v17.0 if the endpoint is not listed as affected endpoint on both v16.0 and v17.0.

고유 링크

No. We highly encourage developers to perform version upgrades before a version gets deprecated for the following reasons

  • You may still need to manually upgrade endpoints being impacted by next version.
  • You might want to upgrade to newer versions to benefit from new features instead of the lowest available version.
고유 링크

You can look up affected endpoints from Marketing API Changelog.

고유 링크

You can disable the version auto-upgrade via the Marketing API Version setting under Marketing API App Product Page > Settings.

고유 링크

If an API call targets a version that has been deprecated and has been automatically upgraded, an API response header is included for any call that has been auto-upgraded.

Example notification header

X-Ad-Api-Version-Warning: 'X-Ad-Api-Version-Warning: 'The call has been auto-upgraded to vXXX as vXXX has been deprecated''
고유 링크