앱 이벤트 API

앱 이벤트를 사용하면 모바일 앱이나 웹페이지에서 발생하는 행동(예: 앱 설치 및 구매 이벤트)을 추적할 수 있습니다. 이러한 이벤트를 추적하면 광고 성과를 측정하고 광고 타게팅을 위한 타겟을 빌드할 수 있습니다.

비즈니스 메시지의 앱 이벤트 추적에 대한 자세한 내용은 Messenger 플랫폼 문서의 비즈니스 메시지용 앱 이벤트 API를 참조하세요.

사용 방법

앱 이벤트에는 세 가지 유형이 있습니다.

• 자동 로깅된 이벤트 - Facebook SDK가 앱 설치, 앱 세션, 앱 내 구매를 자동 로깅합니다.
• 표준 이벤트 - Facebook에서 개발자를 위해 만든 인기 이벤트입니다.
• 맞춤 이벤트 - 개발자가 만든 앱 고유의 이벤트입니다.

앱 이벤트는 세 부분으로 구성됩니다.

1. name - 이벤트를 설명하는 문자열(필수). 이 이름은 앱 이벤트가 분석에 전송될 때 이벤트 로그에 표시됩니다.
2. valueToSum - 분석에서 이름이 같은 앱 이벤트의 다른 '집계 값'에 추가하는 값(선택 사항).
3. parameters - 앱 이벤트에 포함된 값(선택 사항).

서로 다른 이벤트 이름을 최대 1,000개까지 사용할 수 있습니다. 참고: 이 한도에 도달하면 새로운 이벤트 유형이 로깅되지 않으며, 한도를 초과하면 로깅 시 100 Invalid parameter 오류가 표시될 수 있습니다. 그러나 더 이상 사용하지 않는 이벤트를 비활성화할 수 있습니다. 이벤트 한도에 대한 자세한 내용은 FAQ를 참조하세요.

시작하기 전에

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

• 광고주 ID, Android 기기의 광고주 ID 또는 Apple 기기의 광고 ID(IDFA)
• Facebook이 인증할 앱 액세스 토큰. 클라이언트에 앱 액세스 토큰을 저장하지 마세요.

앱 설치

서버에서 POST 요청을 application_tracking_enabled 및 advertiser_tracking_enabled 매개변수가 포함된 /{app-id}/activities로 보냅니다.

curl -i -X POST "https://graph.facebook.com/{app-id}/activities
   ?event=MOBILE_APP_INSTALL
   &application_tracking_enabled=0      
   &advertiser_tracking_enabled=0       
   &advertiser_id={advertiser-tracking-id}
   &{app-access-token}"

성공할 경우 앱은 다음과 같은 응답을 받습니다.

{
  "success": true
}

주의 사항

• 사용자당 한 번의 설치만 보고해야 합니다. 가능한 경우 ID 및 사용자 수준에서 중복 ID를 제거하세요.

사용 가능한 매개변수 리스트는 앱 활동 참고 자료 가이드를 참조하세요.

광고 추적 활성화

advertiser_tracking_enabled 필드는 사용자가 기기에서 광고 추적을 활성화했는지 여부를 지정합니다. 0으로 설정하면 비활성화 상태이고 1로 설정하면 활성화 상태입니다. 이 데이터를 가져와서 Facebook에 반환하면 최적화 또는 전환에 광고 추적을 사용할 수 있는지 확인할 수 있습니다. Meta에서는 데이터 정책에 따라 (Meta 외부 사용자 활동에 대한 파트너의) 이벤트 데이터를 광고 보고서, 사기 탐지, (광고 전송 제품을 포함한) 제품 빌드 및 개선에 활용하지만 개인이 사용자 광고를 개인화하는 목적으로의 데이터 사용은 제한합니다. iOS 6 이전 버전을 실행하는 기기의 경우 이 매개변수는 1로 기본 설정되어야 합니다.

사용자 추적 상태를 가져오려면 Apple, AdSuppport 참고 자료를 참조하세요.

다음의 픽셀 코드는 추적 활성화 플래그의 값을 가져오는 방법을 보여줍니다.

Settings.shared.isAdvertiserTrackingEnabled 속성에서 플래그가 활성화된 추적의 현재 설정을 가져올 수 있습니다.

print("isAdvertiserTrackingEnabled: \(Settings.shared.isAdvertiserTrackingEnabled)")

광고 추적 비활성화

앱 내에서 광고 추적을 해제하기 위한 사용자 설정을 앱에 포함할 수 있습니다. Facebook은 파트너에게 SDK에 이 옵션을 포함하고 사용자의 선택 사항을 설치 또는 전환 이벤트와 함께 Facebook에 다시 보고하도록 요청합니다. Facebook은 설치 또는 전환 이벤트를 광고 보고에 사용하지만 광고 최적화에 사용하지 못하도록 제한합니다. 사용자의 설정은 앱을 실행하는 동안 유지되어야 합니다.

전환 이벤트

event를 CUSTOM_APP_EVENTS로 설정하고 각 이벤트에 advertiser_tracking_enabled를 설정한 상태에서 POST 요청을 /{app-id}/activities 엔드포인트로 보냅니다. advertiser_id 또는 attribution 매개변수는 필수 항목입니다.

curl -i -X POST "https://graph.facebook.com/{app-id}/activities
   ?event=CUSTOM_APP_EVENTS" 
   &advertiser_id={advertiser-tracking-id}
   &advertiser_tracking_enabled=1 
   &application_tracking_enabled=1
   &custom_events=[
      {"_eventName":"fb_mobile_purchase",
       "event_id":"123456",
       "fb_content":"[
            {"id": "1234", "quantity": 2,}, 
            {"id": "5678", "quantity": 1,}
        ]",
       "fb_content_type":"product",
       "_valueToSum":21.97,
       "fb_currency":"GBP",
      }
    ]
   &{app-access-token}" 

성공할 경우 앱은 다음과 같은 응답을 받습니다.

{
  "success": true
}

성과 기여

attribution 엔드포인트는 28일 이내에 광고에 발생한 클릭수를 기반으로 설치 및 전환을 반환합니다. 광고 관리자는 28일 클릭 기여 모델을 통해 1일 조회를 사용하고 인사이트는 설치 또는 전환 시간이 아니라 노출 또는 클릭 시간에 따라 표시됩니다. 이는 보고서를 Facebook 광고 관리자 보고서와 비교하는 경우 중요합니다. 표준 광고 클릭 앱 이벤트 소유권 요청 외에 다음 시나리오도 염두에 두어야 합니다.

• 조회 기여 소유권 요청 — consider_views=TRUE로 설정하면 계정 센터 계정이 28일 이내에 광고를 클릭하지 않을 경우 광고 노출 후 1일 이내에 발생한 설치의 기여 데이터를 반환합니다. 반환된 응답은 is_view_through=TRUE가 되고 view_time이 click_time을 대체합니다. 그 외에 모든 기여는 광고 클릭 기여 데이터와 같습니다.

• 캠페인 간 소유권 요청 — 광고주는 앱 이벤트로 이어진 모든 광고의 성과를 추적할 수 있습니다. Facebook은 캠페인 목표가 모바일 앱 설치 또는 모바일 앱 참여로 설정되어 있지 않은 경우 광고 캠페인에서 이벤트에 대한 소유권 요청을 보냅니다. 이 데이터는 광고주가 앱을 광고의 "모바일 앱 이벤트 추적" 필드에 추가한 경우에만 표시됩니다.

• 사용자 사례 — 고객이 사용자를 모바일 사이트로 보내는 페이지 게시물 광고 또는 웹사이트 광고 클릭에 의해 생성된 설치를 추적하려는 경우 광고 관리자에서 추적할 수 있으며 Facebook은 관련 앱 설치의 소유권을 요청합니다.

• 기기 간 소유권 요청 — 여러 플랫폼에 앱이 있는 광고주는 이러한 여러 플랫폼에 게재한 광고에서 발생한 앱 설치 데이터를 확인할 수 있습니다.

• 사용 사례 — 사용자가 앱의 iPhone 광고를 클릭한 후 해당 앱을 iPad에 설치합니다. 그러면 Facebook에서 광고 타게팅에 관계없이 iPhone 광고로 인해 iPad 앱 설치가 발생한 것으로 간주할 수 있습니다.

고급 매칭

고급 매칭을 사용하면 고객 데이터를 Facebook으로 보낼 수 있습니다. Facebook에서는 이 데이터를 사용하여 광고에 대해 어떤 계정 센터 계정이 행동을 취했는지 더욱 정확하게 확인할 수 있습니다. Facebook은 이 데이터로 전환 이벤트와 고객을 매칭하여 광고를 최적화하고 더욱 큰 규모의 리마케팅 타겟을 빌드할 수 있습니다.

ud 매개변수를 고객을 추적하는 데 도움이 되는 매개변수(예: 고객 이메일, 전화번호)로 설정하고 POST 요청을 /{app-id}/activities 엔드포인트로 보냅니다. 모든 고객 데이터는 해시되어야 하고 그렇지 않을 경우 Facebook에서 이를 무시합니다. 각 개별 이벤트에 advertiser_tracking_enabled를 설정하세요.

curl -i -X POST "https://graph.facebook.com/{app-id}/activities
   ?event=CUSTOM_APP_EVENTS
   &advertiser_id={advertiser-tracking-id}
   &advertiser_tracking_enabled=1 
   &application_tracking_enabled=1
   &custom_events=[
      {"_eventName":"fb_mobile_purchase",
      "event_id":"123456",
       "fb_content":"[
            {"id": "1234", "quantity": 2,}, 
            {"id": "5678", "quantity": 1,}
        ]",
       "fb_content_type":"product",
       "_valueToSum":21.97,
       "fb_currency":"GBP",
      }
    ]
   &ud[em]={sha256-hashed-email}
   &{app-access-token}"

성공할 경우 앱은 다음과 같은 응답을 받습니다.

{
  "success": true
}

모든 사용자 데이터는 Facebook에 전송하기 전에 SHA256 해시 처리되어야 합니다. Facebook에서는 해시 처리되지 않은 데이터를 무시합니다.

중복 제거

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

확장된 기기 정보

/{app-id}/activities?extinfo를 사용하여 앱 이벤트 호출에서 기기 정보(예: 화면의 너비, 높이)를 전송합니다. 값은 쉼표로 구분되며 /application/activites 참고 자료 가이드에 색인된 순서로 정렬되어야 합니다. extinfo를 사용할 때는 모든 값이 필수입니다.

• Android의 경우 version은 a2여야 합니다.
• iOS의 경우 version은 i2여야 합니다.

참고 자료

• ApplicationActivities 매개변수
• Android 개발자 문서 - 디스플레이 지표
• Android 개발자 개발자 문서 - 외부 스토리지
• Apple 개발자 문서 - 디스플레이 지표
• Apple 개발자 문서 - 외부 스토리지
• Apple 개발자 문서 - 화면 크기

모바일 쿠키 가져오기

앱 이벤트는 advertiser_id와 연결하는 것이 좋습니다. 그러나 Android 기기 및 iOS 6 이전 iOS 기기의 경우 기기의 모바일 쿠키에 설정된 attribution 매개변수를 사용할 수도 있습니다.

참고: 모바일 쿠키는 사용자 또는 기기 기여에서 파생되지 않습니다. 이 쿠키는 영구적이지 않으며 수시로 새로 고침되도록 설계되었습니다. 광고 리타게팅에 모바일 쿠키를 사용하지 마세요.

Android

쿠키는 22자의 무작위 영숫자 문자열입니다.

ContentProvider를 사용하여 Facebook 성과 기여 ID를 가져옵니다.

public static final Uri ATTRIBUTION_ID_CONTENT_URI = Uri.parse("content://com.facebook.katana.provider.AttributionIdProvider");

public static final String ATTRIBUTION_ID_COLUMN_NAME = "aid";

public static String getAttributionId(ContentResolver contentResolver) {
        String [] projection = {ATTRIBUTION_ID_COLUMN_NAME};
        Cursor c = contentResolver.query(ATTRIBUTION_ID_CONTENT_URI, projection, null, null, null);
        if (c == null || !c.moveToFirst()) {
            return null;
        }
        String attributionId = c.getString(c.getColumnIndex(ATTRIBUTION_ID_COLUMN_NAME));
        c.close();
        return attributionId;
    }

Android 앱의 광고 ID도 가져와야 합니다.

iOS

모바일 쿠키는 Facebook iOS 앱이 CFUUIDCreateString을 사용하여 만들며 128비트 UUID 문자열로 표시됩니다.

다음과 같이 쿠키 ID와 IDFA를 모두 가져와서 Facebook에 식별자로 전송합니다.

ASIdentifierManager *manager = [ASIdentifierManager sharedManager];
NSString *advertiserID = [[manager advertisingIdentifier] UUIDString];

if (advertiserID) {
  // do stuff
}

X-Forwarded-For HTTP 헤더

서버나 프록시와 같이 중앙의 위치에서 POST 요청이 실행되는 경우 기본적으로 서버 간 호출 후 X-Forwarded-For HTTP 헤더가 있어야 정확한 위치와 기기 정보를 얻을 수 있습니다. 각 앱 이벤트 요청을 보낼 때마다 X-Forwarded-For HTTP 헤더 매개변수를 통해 기기의 IP 주소(IPv4 또는 IPv6 형식)를 보내세요. 이렇게 하면 advertiser_id를 정확한 IP 주소와 페어링한 다음 Facebook 플랫폼에서 사용할 수 있습니다.

IPv6 예시

curl ...
  -H "X-Forwarded-For: fd45:f238:3b40:23b1:ffff:ffff:ffff:abcd" \
  https://graph.facebook.com/<APP_ID>/activities/

IPv4 예시

curl ...
  -H "X-Forwarded-For: 192.168.0.99" \
  https://graph.facebook.com/<APP_ID>/activities

테스트

1. 이벤트 관리자로 이동합니다.
2. 페이지 왼쪽에서 데이터 소스 아이콘을 클릭합니다.
3. 데이터의 이름과 ID를 선택합니다.
4. 테스트 이벤트를 클릭하고 채널을 앱으로 선택합니다.
5. 그래프 API 도구를 사용하여 AE-API 요청을 보냅니다.
6. 얼마 후 테스트 이벤트 탭에 상호작용이 표시됩니다.

불일치

고객이 모바일 측정 파트너의 보고서를 Facebook 보고서와 비교한 결과, 불일치하면 다음 몇 가지 항목을 확인해보세요.

Facebook이 MMP보다 적은 수의 설치를 보고하는 경우:

• FB SDK가 올바르게 통합되었나요?
• 고객이 잘못된 앱 ID를 사용하고 있나요?

Facebook이 MMP보다 많은 수의 설치를 보고하는 경우:

• 기여 기간이 같은가요? Facebook의 기여 기간은 일반적으로 대부분의 모바일 측정 파트너보다 깁니다.
• MMP SDK가 올바르게 통합되었나요?
• 고객이 잘못된 앱 ID를 사용하고 있나요?
• iOS7만 불일치하나요? MMP가 기기에서 Apple의 광고 ID(IDFA)를 수신하고 FB에 올바르게 전달하고 있나요?

참고 자료

앱 활동 확장 정보

앱 확장 정보에 대한 자세한 내용은 /application/activites 참고 자료 가이드를 참조하세요.

사용자 데이터 매개변수

표준 이벤트 이름

표준 이벤트 매개변수

기타 참고 자료

• 앱 이벤트
• 앱 이벤트 모범 사례
• 오류 처리
• GDPR 규정 준수
• Facebook 광고 관리자
• Facebook 앱 대시보드