앱 이벤트용 전환 API

전환 API는 광고주가 여러 소스를 거치지 않고 하나의 엔드포인트를 통해 웹, 앱, 실물 매장 및 비즈니스 메시지 이벤트를 Meta로 보낼 수 있도록 지원합니다. 이 통합은 데이터 세트를 사용하여 광고주의 기술 스택을 단순화하고 Meta 이벤트 관리자 내에서 더욱 포괄적인 보기를 만듭니다.

이 문서는 전환 API에 앱 이벤트를 통합하기 위한 가이드를 제공합니다.

필수 조건

1. 데이터 세트

전환 API를 통해 전송된 앱 이벤트를 데이터 세트와 연결해야 합니다.

Datasets allow advertisers to connect and manage event data from web, app, store and business messaging event sources to the Conversions API. Datasets may show event data from any of these integrations that you choose to set up:

Meta Pixel (website events)
App Events API (app events, including Facebook SDK for iOS or Android, mobile measurement partners (MMPs))
Offline Conversions API (Meta’s legacy API for offline events)
Messaging Events API (messaging events)

Datasets enable you to view all customer activities from a single interface. They also allow you to reduce the effort to build and maintain multiple API integrations.

In Events Manager, advertisers have different options to create a dataset depending on their starting point. Or you can create a brand new dataset in Events Manager by linking during offline event set creation or through an existing mobile app or during messaging event set creation information. Note that linking a dataset to an application is required before sending mobile app events to the Conversions API and only one application can be linked to a dataset. See more details and instructions here.

https://graph.facebook.com/v16.0/{ads-pixel-id}/is_consolidated_container로 GET 호출을 보내서 광고주 데이터 세트가 통합되어 있고, 따라서 전환 API를 사용하여 앱 이벤트를 전달할 수 있는지 확인할 수 있습니다.

2. 권한

광고주로서 직접 통합을 구현하려면 필수 조건과 권한에 대한 지침(여기)을 따르세요.
파트너 플랫폼 통합을 구현하려면 필수 조건과 권한에 대한 지침(여기)을 따르세요.

구성

전환 API로 앱 이벤트 보내기

a. 데이터 세트 ID 및 앱 ID 연결

이벤트 관리자에는 앱과 데이터 세트를 연결하는 방법이 두 가지 있습니다.

'데이터 소스' 탭을 선택하고 앱의 '설정' 탭을 찾아서 연결을 수행합니다.
'데이터 소스' 탭을 선택하고 앱의 '개요' 탭에서 '모든 활동' 섹션의 '데이터 세트로 연결' 버튼을 사용합니다.

연결을 완료하고 나면 데이터 세트에 연결된 앱이 포함됩니다.

b. 필수 필드

전환 API를 통해 전송할 수 있는 현재 매개변수 세트는 여기를 참조하세요. 앱 이벤트를 전송하는 경우, 다음 server_event 필드를 페이로드에서 공유할 수 있습니다.

action_source 매개변수에는 앱 이벤트에 대한 app 값이 포함되어야 합니다.
중복 제거 설정 사례에는 event_id가 필수입니다.
app_data 필드
user_data 필드
custom_data 필드

앱 데이터 필드

Parameter	Description
`advertiser_tracking_enabled` boolean	Required for app events Use this field to specify ATT permission on an iOS 14.5+ device. Set to `0` for disabled or `1` for enabled.
`application_tracking_enabled` boolean	Required for app events A person can choose to enable ad tracking on an app level. Your SDK should allow an app developer to put an opt-out setting into their app. Use this field to specify the person's choice. Use `0` for disabled, `1` for enabled. `
`extinfo` object Please use the down arrow to the right to see the list of `extinfo` values.	Required for app events Extended device information, such as screen width and height. This parameter is an array and values are separated by commas. When using `extinfo`, all values are required and must be in the order indexed below. If a value is missing, fill with an empty string as a placeholder. Note: `version` must be `a2` for Android `version` must be `i2` for iOS
`0` string	Required extinfo version Example: `i2`
`1` string	app package name Example: `com.facebook.sdk.samples.hellofacebook`
`2` string	short version (int or string) Example: `1.0`
`3` string	long version Example: `1.0 long`
`4` string	Required OS version Example: `13.4.1`
`5` string	device model name Example: `iPhone5,1`
`6` string	locale Example: `En_US`
`7` string	timezone abbreviation Example: `PDT`
`8` string	carrier Example: `AT&T`
`9` string	screen width Example: `320`
`10` string	screen height Example: `568`
`11` string	screen density Example: `2`
`12` string	CPU cores Example: `2`
`13` string	external storage size in GB Example: `13`
`14` string	free space on external storage in GB Example: `8`
`15` string	device timezone Example: `USA/New York`
`campaign_ids` string	Optional An encrypted string and non-user metadata appended to the outbound URL (for example, ad_destination_url) or deep link (for App Aggregated Event Manager) when a user clicked on a link from Facebook. Graph API definition: Parameter passed via the deep link for Mobile App Engagement campaigns.
`install_referrer` string	Optional Third party install referrer, currently available for Android only, see here for more.
`installer_package` string	Optional Used internally by the Android SDKs
`url_schemes` array	Optional Used internally by the iOS and Android SDKs.
`windows_attribution_id` string	Optional Attribution token used for Windows 10.

고객 정보 매개변수

매개변수	설명
`anon_id` 문자열	해시 금지. 설치 ID. 이 필드는 고유한 앱 설치 인스턴스를 나타냅니다.
`madid` 문자열	해시 금지. 모바일 광고주 ID, Android 기기의 광고 ID, Apple 기기의 광고 식별자(IDFA).

맞춤 데이터

매개변수	설명
`description` 문자열	선택 사항. 문자열, 이벤트 설명, 맞춤.
`level` 문자열	선택 사항. 문자열, 게임 레벨, 맞춤.
`max_rating_value`	선택 사항. long, 평가 등급의 상한(예: 5개 별 등급에서 5), 맞춤.
`success` 부울	선택 사항. 예인 경우 `1`, 아니요인 경우 `0`, 맞춤.

요컨대, 전환 API를 사용하여 공유된 앱 이벤트에는 다음과 같은 데이터 매개변수가 필요합니다.

action_source: 'app'으로 설정해야 합니다. (전환 API를 사용하면 자신이 아는 한도 내에서 action_source 매개변수가 정확하다는 데 동의하는 것으로 간주됩니다.)
event_id: 중복 제거 설정에 필수 항목입니다. 자세한 내용은 '여러 채널에 대한 중복 제거 설정' 섹션을 참조하세요.
advertiser_tracking_enabled
application_tracking_enabled
extinfo

extinfo의 예시는 다음과 같습니다. 아래의 모든 하위 매개변수가 입력되어 있고 순차적인지 확인하세요. 누락된 것이 있는 경우, 빈 문자열을 자리 표시자로 사용하세요.

하위 매개변수 이름	필수	데이터 유형	예
extinfo 버전	예	문자열	`i2`(버전은 Android의 경우 a2, iOS의 경우 i2여야 함)
앱 패키지 이름	아니요	문자열	`com.facebook.sdk.samples.hellofacebook`
짧은 버전	아니요	문자열	`1.0`
긴 버전	아니요	문자열	`1.0 long`
os 버전	예	문자열	`13.4.1`
기기 모델명	아니요	문자열	`iPhone5,1`
로캘	아니요	문자열	`En_US`
시간대 약어	아니요	문자열	`PDT`
이동통신사	아니요	문자열	`AT&T`
화면 너비	아니요	문자열	`320`
화면 높이	아니요	문자열	`568`
화면 밀도	아니요	문자열	`2`
cpu 코어	아니요	문자열	`2`
외장 스토리지 용량	아니요	문자열	`13`
외장 스토리지의 빈 공간	아니요	문자열	`8`
기기 시간대	아니요	문자열	`USA/New York`

c. 여러 채널에 대한 중복 제거 설정

전환 API 통합과 앱 이벤트에 사용하는 그 외의 모든 기존 통합(예: SDK, MMP, 앱 이벤트 API) 사이에서 중복된 이벤트 트래픽을 삭제하려면 중복 제거 메커니즘이 필요합니다.

앱 이벤트의 경우, Meta에서는 웹 이벤트의 경우와 동일한 중복 제거 기능을 적용합니다. 이 로직은 event_id 및 event_name 필드 기반 중복 제거를 사용합니다(동일한 event_id가 있는 전환 API 및 SDK/앱 이벤트 API 이벤트). event_id 매개변수는 유사한 이벤트를 고유하게 구분할 수 있는 식별자입니다. 이벤트 ID가 부정확할 경우, 전환에 대한 중복 제거가 잘못 실행되어 전환 보고 및 캠페인 성과에 추가 영향을 미칠 수 있습니다.

중복 제거 설정을 구현하려면 다음 개발자 문서를 참조할 수 있습니다.

맞춤 이벤트를 로깅하는 방법의 예시는 다음과 같습니다. 이를 위해서는 iOS SDK에서 이벤트 이름을 AppEvents.Name으로 전달하세요.

AppEvents.shared.logEvent(.achievedLevel, parameters: [AppEvents.ParameterName(rawValue: "event_id"): "123"])

앱 설치 이벤트의 경우, 최근 90일 동안 하나의 설치만 기여 분석되도록 하는 중복 제거 메커니즘이 이미 존재합니다. 이벤트가 발생한 행동 출처와 관계없이 첫 번째 이벤트는 수신하고 나중 이벤트는 거부합니다. 설치 이벤트와 관련된 앱 이벤트의 경우, 중복 제거를 필수로 구현하지 않아도 됩니다.

d. 이벤트 보내기

새로운 이벤트를 전송하려면 https://graph.facebook.com/{API_VERSION}/{DATASET_ID}/events?access_token={TOKEN} 경로에서 전환 API로 POST 요청을 보내세요. 이 에지에 POST 요청을 보내면 Meta가 새 앱 서버 이벤트를 생성합니다. 자세한 내용은 다음 개발자 문서를 참조하세요.

페이로드의 전체 스키마에 매개변수가 어떻게 통합되는지 보여주는 개요는 다음과 같습니다.

** 문제 해결**

페이로드 도우미 도구를 사용하여 페이로드 데이터를 생성할 수 있습니다.

해당할 경우 app 행동 출처를 선택합니다.
Meta로 전송할 이벤트에 대한 정보를 입력합니다.
그러면 이벤트 페이로드가 생성되며, 이를 전환 API 통합의 템플릿으로 사용할 수 있습니다.

이벤트 관리자에서 이벤트 테스트 도구를 사용하여 테스트합니다.