오프라인 전환 API

오프라인 전환 API를 사용하여 오프라인 전환 이벤트를 전송하고, 전환하기 전에 Meta 광고를 보거나 클릭한 고객의 수를 확인하세요.

시작하기 전에

이 API를 사용하려면 다음 항목이 필요합니다.

1. Meta 비즈니스 관리자

비즈니스 관리자가 없다면 하나 만듭니다.

2. Meta 앱 ID

마케팅 API에 액세스하는 데 사용합니다. Meta 앱을 만드는 방법은 다음과 같습니다.

• 비즈니스 관리자 > 비즈니스 설정으로 이동합니다.
• 앱을 선택합니다.
• 새 앱 추가를 클릭하고 지침을 따릅니다.

3. 앱 검수 및 권한

앱 검수와 권한에 대한 규칙은 API 구현 방법에 따라 달라집니다.

4. 비즈니스 관리자 시스템 사용자 및 토큰

시스템 사용자 액세스 권한이 있으면 앱에서 API를 통해 Meta에 데이터를 보낼 수 있습니다. 이를 만드는 방법은 다음과 같습니다.

• 비즈니스 관리자 > 비즈니스 설정으로 이동합니다.
• 시스템 사용자를 선택합니다.
• 새 시스템 사용자 추가를 클릭합니다.
• 시스템 사용자의 역할로 관리자 시스템 사용자를 선택합니다.

액세스 토큰은 Meta 데이터에 대한 액세스 권한을 제공합니다. 시스템 사용자 액세스 토큰을 만드는 방법은 다음과 같습니다.

• 비즈니스 관리자 > 비즈니스 설정으로 이동합니다.
• 시스템 사용자를 선택합니다.
• 시스템 사용자를 선택하고 새 토큰 생성을 클릭합니다.
• 범위에 앱을 선택하고 ads_management를 선택합니다.

5. 광고 계정

Meta에 광고 캠페인을 게재하려면 광고 계정이 필요합니다. 광고 계정을 만들려면 마케팅 API 또는 비즈니스 지원 센터: Meta 비즈니스 관리자의 비즈니스 설정 정보를 참조하세요.

6. 광고 계정에 시스템 사용자 액세스 권한 부여

광고 계정에 시스템 사용자 액세스 권한을 부여합니다.

• 비즈니스 관리자 > 비즈니스 설정으로 이동합니다.
• 시스템 사용자를 선택합니다.
• 시스템 사용자를 선택하고 자산 할당을 클릭합니다.
• 광고 계정을 선택합니다.

7. 오프라인 이벤트 세트

오프라인 전환 데이터와 함께 업로드되는 파일입니다. 광고를 만들 때 tracking_spec을 오프라인 이벤트 세트 ID로 설정하여 이벤트가 발생한 원인을 올바로 추적하세요. 그런 다음 이벤트 세트를 만들고 가져온 데이터에 대한 통계를 확인하고 비즈니스 관리자에서 이 데이터를 삭제하고 수정할 수 있습니다.

이전 구현에서는 비즈니스 관리자 수준에서 오프라인 이벤트 세트 CRUD 작업을 실행하여 다른 개체 및 항목과 이벤트 세트를 공유할 수 있습니다.

이벤트 데이터 업로드

오프라인 이벤트 세트를 만들거나 이벤트 세트의 데이터를 업로드하거나 보려면 특정한 액세스 권한이 필요합니다. 이러한 권한을 광고 계정에 할당하려면 이 액세스 권한이 필요합니다. 다음 중 하나여야 합니다.

• 비즈니스 관리자 운영자
• 오프라인 이벤트 세트를 만든 관리자 시스템 사용자
• 오프라인 이벤트 세트에 연결된 ad_account의 운영자

오프라인 전환 이벤트 세트, 참고 자료를 참조하세요.

1. 오프라인 이벤트 세트 만들기

curl 
  -F 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' 
  -F 'name=offline_event_set',
  -F 'description=conversion data used for superbowl campaign',
  https://graph.facebook.com/<API_VERSION>/<BUSINESS_MANAGER_ID>/offline_conversion_data_sets

HTTP POST 호출:

POST /<BUSINESS_MANAGER_ID>/offline_conversion_data_sets HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<BUSINESS_MANAGER_ID>/offline_conversion_data_sets

응답에 이벤트 세트 id가 포함됩니다.

{
  "id": <OFFLINE_EVENT_SET_ID>
}

매개변수

2. 광고 계정 권한 할당

광고 계정에 추적 및 읽기 권한을 할당하는 방법은 다음과 같습니다.

POST /<OFFLINE_EVENT_SET_ID>/adaccounts HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/adaccounts

매개변수

3. 광고 추적 설정

tracking_spec을 업데이트하면 Facebook이 덮어씁니다. 먼저 GET을 호출한 다음 오프라인 이벤트 세트에 대해 연결된 String을 기존 tracking_spec에 추가하세요. 광고 관리를 참조하거나 광고 관리자를 사용하세요. 예를 들어 적절한 추적 사양을 제공하세요.

curl \
  -F 'tracking_spec=[{action.type:"offline_conversion", dataset:["123"]}]' \
  -F 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<AD_ID>

광고의 추적 사양을 업데이트하는 방법은 다음과 같습니다.

POST /<AD_ID>/?tracking_specs=[{"action.type":"offline_conversion","dataset": <OFFLINE_EVENT_SET_ID>}] HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<AD_ID>/?tracking_specs=[{"action.type":"offline_conversion","dataset": <OFFLINE_EVENT_SET_ID>}]

매개변수

4. 오프라인 이벤트 업로드

전환 후 62일 이내에 거래를 업로드해야 합니다. 전환 데이터를 업로드하는 방법은 다음과 같습니다.

curl \
  -F 'access_token=SYSTEM_USER_ACCESS_TOKEN' \
  -F 'upload_tag=store_data' \
  -F 'data=[ \
    { 
      match_keys: {"phone": ["HASH1","HASH2"], "email": ["HASH3","HASH4"]}, 
      currency: "USD", 
      value: 16,
      event_name: "Purchase",
      event_time: 1456870902,
      contents: [
        {id: "A", quantity: 1},
        {id: "B", quantity: 2},
        {id: "C", quantity: 1}
      ]
      custom_data: {             
      },
    }, 
    { 
      match_keys: {"lead_id": "12345"}, 
      event_name: "Lead",
      event_time: 1446336000,
      contents: [
        {id: "A", quantity: 1},
        {id: "B", quantity: 2},
        {id: "C", quantity: 1}
      ]
      custom_data: {
        event_source: "email",
        action_type: "sent_open_click",
        email_type: "email_type_code", 
        email_provider: "gmail_yahoo_hotmail",
      }
    }, 
  ]'
  https://graph.facebook.com/VERSION/OFFLINE_EVENT_SET_ID/events

전환을 보내려면 HTTP POST를 호출합니다.

POST /<OFFLINE_EVENT_SET_ID>/events HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/events

매개변수

같은 배치의 모든 이벤트 업로드 API 호출에 대해 같은 upload_tag를 사용하여 그룹화합니다. 이렇게 하면 이벤트 업로드를 디버깅하는 데 도움이 되며, 두 개 이상의 API 호출에서 만든 모든 이벤트 업로드에 대해 이를 사용해야 합니다.

data의 매개변수는 다음과 같습니다.

예를 들어 data 필드를 사용하여 정보를 업로드할 수 있습니다.

{
  match_keys: MATCH_KEYS,
  event_time: EVENT_TIME,
  event_name: "Purchase",
  value: 400,
  currency: "USD",
  contents: [
    {
        id: "A",
        quantity: 1,
        brand: "brand_of_A",
        category: "Apparel & Accessories | Clothing",
        price: 100,
    },
    {
        id: "B",
        quantity: 2,
        brand: "brand_of_B",
        category: "Apparel & Accessories | Shoes",
        price: 50,
    },
    {
        id: "C",
        quantity: 1,
        brand: "brand_of_C",
        category: "Apparel & Accessories | Jewelry | Watches",
        price: 200,
    }
  ],
}

같은 배치의 모든 이벤트 업로드 API 호출에 대해 같은 upload_tag를 사용하여 그룹화합니다. 이렇게 하면 이벤트 업로드를 디버깅하는 데 도움이 되며, 두 개 이상의 API 호출에서 만든 모든 이벤트 업로드에 대해 이를 사용해야 합니다.

매칭 키

match_keys는 기여를 위해 사람들을 매칭하기 위한 ID의 집합입니다. 데이터를 정규화하고 암호화하려면 CRM 데이터를 기반으로 한 맞춤 타겟을 참조하세요. SHA256만 지원되며 해시되지 않은 데이터는 허용하지 않습니다.

응답:

오류에는 잘못된 항목을 포함한 예외 및 이유가 표시됩니다. 오류를 수정하거나 오류가 있는 데이터 행을 건너뛰고 API 호출을 다시 시도하세요.

업로드 통계 보기

비즈니스 관리자 운영자나 오프라인 이벤트 세트를 만든 시스템 사용자는 업로드 통계를 가져올 수 있습니다. 오프라인 이벤트 세트에 연결된 ad_account의 운영자라면 누구나 이 데이터를 읽을 수 있습니다.

유효한 항목 및 일치하는 항목 등 오프라인 이벤트 세트에 대한 통계를 확인하는 방법은 다음과 같습니다.

GET /<OFFLINE_EVENT_SET_ID>/uploads HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/uploads

비즈니스 관리자의 Offline Events Manager에서 오프라인 이벤트의 일일 분석 데이터를 확인하세요. 더 정확한 분석 데이터를 보려면 다음을 호출하세요.

GET /<OFFLINE_EVENT_SET_ID>/stats HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/stats

매개변수

오프라인 맞춤 전환 만들기

오프라인 맞춤 전환은 현재 백필되지 않습니다. 맞춤 전환을 만들기 전에 업로드된 이벤트의 데이터는 고려하지 않습니다. 광고 게재 최적화에는 오프라인 맞춤 전환 데이터를 사용할 수 없습니다. 맞춤 전환, 참고 자료를 참조하세요.

오프라인 이벤트를 사용하여 맞춤 전환을 만들려면 POST를 호출하세요.

POST /act_<ACCOUNT_ID>/customconversions HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/act_<ACCOUNT_ID>/customconversions

매개변수:

성공 시 응답:

{
  "id": <CUSTOM_CONVERSION_ID>
}

맞춤 데이터를 사용하여 측정

custom_data 필드를 사용하여 나중에 특정 전환을 계산에 포함할 것인지 결정하는 규칙을 만들 수 있습니다. 이는 오프라인 맞춤 타겟과 유사합니다. 광고 계정당 최대 40개의 맞춤 전환을 가질 수 있습니다.

예를 들어 custom_data를 사용하여 제품 카테고리를 업로드에 포함하세요.

data=[
  {
    match_keys: {"phone": ["<HASH>","<HASH>"], "email": ["<HASH>","<HASH>"]}, 
    currency: "USD", 
    value: 16,
    event_name: "Purchase",
    event_time: 1456870902,
    custom_data: {
      product_category: "ICECREAM",
    },
  },
]

그런 다음 custom_data.{YOUR_CUSTOM_PARAM}를 사용하여 맞춤 전환 규칙을 만드세요.

curl \
  -F 'name=Ice Cream Purchasers' \
  -F 'custom_event_type=Purchase' \
  -F 'event_source_id=<OFFLINE_EVENT_SET_ID>' \
  -F 'rule={"and": [{"event_name":{"eq":"Purchase"}},{"custom_data.product_category":{"i_contains":"ICECREAM"}}]}' \
  -F 'access_token=<ACCESS_TOKEN>' \

"https://graph.facebook.com/<API_VERSION>/act_<ACCOUNT_ID>/customconversions"

파트너를 위한 오프라인 전환

클라이언트의 광고로 인해 발생한 오프라인 전환 이벤트를 확인하려면 다음 단계를 따르세요. 이 단계 대부분에서 사용한 API 호출은 누군가 자신의 오프라인 이벤트 세트와 캠페인을 관리할 때와 같습니다.

1. 파트너 - 오프라인 이벤트 세트 만들기
2. 파트너 - 클라이언트의 비즈니스 관리자와 이벤트 세트 공유
3. 클라이언트 - 광고 계정 오프라인 추적 권한 할당
4. 클라이언트 - 광고에 오프라인 추적 설정
5. 파트너 - 오프라인 이벤트 업로드, 통계 확인
6. 파트너 - 클라이언트를 위해 광고 인사이트 표시

이 단계는 클라이언트 광고 계정에서 설정된 파트너 또는 에이전시의 권한에 따라 다릅니다.

• 클라이언트의 모든 광고 계정, 이벤트 세트 또는 다른 자산에 대한 소유권을 가질 수도 있습니다.
• 특정 행동을 수행하기 위해 클라이언트의 자산에 대한 권한을 가질 수도 있습니다.

이러한 권한을 설정하려면 비즈니스 관리자 자산을 참조하세요.

파트너 - 이벤트 세트 공유

클라이언트의 비즈니스 관리자와 이벤트 세트를 공유합니다. 그런 다음 클라이언트가 이벤트 세트를 광고 추적에 사용할 수 있습니다.

GET /<OFFLINE_EVENT_SET_ID>/agencies HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/agencies

매개변수

클라이언트 - 광고 계정 오프라인 추적 권한 할당

파트너가 만든 오프라인 이벤트 세트를 클라이언트와 공유하세요. 광고 계정의 광고 추적을 활성화하려면 비즈니스 관리자 운영자 또는 오프라인 이벤트 세트를 만든 운영자 시스템 사용자여야 합니다. 오프라인 이벤트 세트에 연결된 광고 계정의 운영자도 광고 추적을 활성화할 수 있습니다. 이 API를 호출하려면 호출의 비즈니스에서 오프라인 이벤트 세트에 액세스할 수 있어야 합니다.

다음 호출을 사용하여 광고 계정에 오프라인 이벤트 추적 및 보기 권한을 할당할 수 있습니다.

POST /<OFFLINE_EVENT_SET_ID>/adaccounts HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/adaccounts

매개변수

외부 ID 제공

고객을 나타내고 Meta 사용자와 일치시키기 위해 자체 외부 ID를 제공해야 하는 경우도 있습니다. 이렇게 하려면 이 가이드라인에 따라 extern_id를 사용하세요.

일치 과정을 통과한 데이터 파트너는 파트너 ID를 네임스페이스 ID로, extern_id를 tpid로 사용할 수 있습니다.

match_keys만 제공

Meta에서는 match_keys를 사용하여 공유한 전환 데이터를 Meta 사용자와 매칭할 수 있는지 확인합니다. match_keys를 제공할 경우 namespace_id 매개변수도 제공할 수는 없습니다.

match_keys와 extern_id 모두 제공

Meta에서는 match_keys를 사용하여 Meta 사용자를 찾고 {dataset_id, extern_id}에서 {facebook_user_id}로 매핑을 전달합니다. match_keys와 extern_id를 제공할 경우 namespace_id는 제공할 수 없습니다.

extern_id만 제공

이미 match_keys와 extern_id를 사용하여 데이터를 보낸 경우 Meta는 {dataset_id, extern_id}를 사용하여 {facebook_user_id}를 가져옵니다.

namespace_id 제공

namespace_id 매개변수는 전체 API 호출에 적용됩니다. 이 매개변수를 사용하여 비즈니스 또는 파트너 프로필 ID로 액세스할 수 있거나 소유한 다른 오프라인 이벤트 세트를 참조할 수 있습니다. 이미 match_keys와 extern_id를 사용하여 데이터를 보낸 경우 Meta는 {namespace_id, extern_id}를 사용하여 {facebook_user_id}를 가져옵니다. 데이터 행 1개당 extern_id를 하나만 제공해야 합니다.

인사이트 및 기여

누군가 광고를 조회하거나 클릭하여 발생한 오프라인 이벤트를 확인하세요. 2일 후에 발생한 오프라인 전환만 계산에 포함됩니다. 즉 기여 기간을 28d_view 또는 action_attribution_windows=['28d_view']'로 설정해야 하며, 그렇지 않으면 보고서에 전환이 표시되지 않습니다. 인사이트 API 및 인사이트 가이드를 참조하세요.

GET /act_<ADACCOUNT_ID>/insights HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/act_<ADACCOUNT_ID>/insights

매개변수

결과는 다음과 같습니다.

{
  "data": [
    {
      "date_start": "2015-12-01",
      "date_stop": "2015-12-01",
      "actions": [
        {
          "action_type": "offline_conversion.purchase",
          "value": 1
        },
        {
          "action_type": "offsite_conversion.lead",
          "value": 3
        },
      ],
      ...
    }
  ]
}

예를 들어 기여를 조회하는 방법은 다음과 같습니다.

curl -G \
  -d 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' \
  -d 'fields=unique_actions,action_values' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/insights

결과는 다음과 같습니다.

{
  "data": [
    {
      "unique_actions": [
        {
          "action_type": "link_click",
          "value": 94
        },
        {
          "action_type": "offline_conversion",
          "value": 1
        },
        {
          "action_type": "offline_conversion.purchase",
          "value": 1
        },
        {
....
          "value": 1
        }
      ],
      "action_values": [
        {
          "action_type": "offline_conversion.purchase",
          "value": 27.5
        },
        {
          "action_type": "offline_conversion",
          "value": 27.5
        }
      ],
      "date_start": "2016-06-06",
      "date_stop": "2016-06-07"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

미국 사용자를 위한 데이터 처리 옵션

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": []
        }
    ]
}

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>",
                "client_ip_address": "256.256.256.256"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": ["LDU"],
            "data_processing_options_country": 0,
            "data_processing_options_state": 0
        }
    ]
}

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": ["LDU"],
            "data_processing_options_country": 1,
            "data_processing_options_state": 1000
        }
    ]
}

데이터 처리 옵션에 대해 자세히 알아보세요.