매장 유입 목표 - 마케팅 API - 문서

마케팅 API

노출 위치

Facebook 데스크톱과 모바일(피드, 스토리, Marketplace) 및 Instagram(피드, 스토리, 릴스, 프로필 피드, 둘러보기 홈, 프로필 릴스)에 제공됩니다.

게재 최적화

도달 최적화 — 이 API에 액세스할 권한이 있는 모든 광고주에게 제공합니다. 일일 고유 도달에 최적화되고 광고 관리자 보고에서 '노출'을 기본 지표로 표시합니다.

어드밴티지+ 카탈로그 광고 만들기

이 목표로 설정된 어드밴티지+ 카탈로그 광고를 만들려면 페이지에서 Facebook 위치를 사용해야 합니다.

요구 사항

캠페인은 objective를 STORE_VISITS로 설정해야 합니다.
캠페인은 promoted_object를 해당 <PARENT_PAGE_ID>로 설정해야 합니다.
promoted_object와 targeting에는 <PAGE_SET_ID>의 place_page_set_id가 포함되어야 합니다.
광고 세트 optimization_goal은 REACH로 설정해야 합니다.
광고 세트 billing_event는 IMPRESSIONS여야 합니다.

1단계. `PageSet` 만들기

Facebook은 PageSet를 사용해 광고를 타게팅하고 광고 내의 홍보 개체로 사용합니다.

PageSet 만들기:

매장 위치를 수집합니다. 즉, 각 매장 위치에 대한 Facebook 페이지와 기본 비즈니스의 위치입니다. 기본 비즈니스는 메인 페이지로 알려져 있습니다.
모든 위치를 대표할 위치 JSON 구조를 만듭니다.
위치 JSON 구조로 PageSet를 만듭니다.

모든 매장 위치 수집

<PARENT_PAGE_ID>는 모든 매장 위치에 대한 기본 페이지의 페이지 ID입니다. 모든 매장 페이지와 기본 페이지에 속한 위치를 검색하고 각 위치의 위도와 경도를 반환합니다.

curl -X GET \
  -d 'fields="location{latitude,longitude},is_permanently_closed"' \
  -d 'limit=30000' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<PARENT_PAGE_ID>/locations

예시 출력

{
    "data": [
        {
            "location": {
                "latitude": 29.173384,
                "longitude": 48.098807
            },
            "is_permanently_closed": false,
            "id": "1788030244802584"
        },
        {
            "location": {
                "latitude": 29.303635,
                "longitude": 47.937725
            },
            "is_permanently_closed": false,
            "id": "261533444245300"
        },
        {
            "location": {
                "latitude": 29.302303,
                "longitude": 47.933178
            },
            "is_permanently_closed": false,
            "id": "179435399132774"
        },
        {
            "location": {
                "latitude": 29.302591,
                "longitude": 47.931801
            },
            "is_permanently_closed": false,
            "id": "1790317704582144"
        }
    ],
    "paging": {
        "cursors": {
            "before": "MTc4ODAzMDI0NDgwMjU4NAZDZD",
            "after": "MTA4MTU4NjU5NjA5MDA4"
        }
    }
}

위치 JSON 구조 만들기

반환된 결과에서 각 항목을 이터레이션하면서 is_permanently_closed 필드를 확인하여 각 위치가 운영 중인지 확인합니다.

두 개의 GET 요청을 사용하여 추정된 반경을 가져오고 radius 및 distance_unit 매개변수를 얻습니다. 또는 일괄 API 호출로 아래의 값을 생성합니다.

개별 요청

메인 페이지에서 반환한 JSON 결과에서 얻은 각 매장 페이지의 위도와 경도를 사용하여 이 요청을 보냅니다. 각 위치에 대한 추정 반경이 반환됩니다.

curl -X GET \
  -d 'type="adradiussuggestion"' \
  -d 'latitude=51.5152253' \
  -d 'longitude=-0.1423029' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v20.0/search/

일괄 요청

여러 요청을 단일 요청으로 묶을 수도 있습니다.

curl \
  -F "access_token=<ACCESS_TOKEN>" \
  -F "include_headers=false" \
  -F "batch=[
    {
      \"method\": \"GET\",
      \"relative_url\": \"/<API_VERSION>/search?type=adradiussuggestion&amp;latitude=29.173384&amp;longitude=48.098807\"
    },
    {
      \"method\": \"GET\",
      \"relative_url\": \"/<API_VERSION>/search?type=adradiussuggestion&amp;latitude=29.303635&amp;longitude=47.937725\"
    }
  ]" \
  "https://graph.facebook.com"

최종 위치 JSON 구조

이전의 호출에서 얻은 radius 및 distance_unit 매개변수를 사용하고 각 위치의 <CHILD_LOCATION_ID>를 page_id로 사용해서 최종 위치 JSON 구조를 만듭니다.

[
    {
      "page_id": 1788030244802584,
      "radius": 1,
      "distance_unit": "mile"
    },
    {
      "page_id": 261533444245300,
      "radius": 1,
      "distance_unit": "mile"
    }
]

위치 JSON 구조로 `Pageset` 만들기

현재 PageSet 엔드포인트는 허용 리스트에 등록된 파트너에게만 제공합니다. 액세스하려면 Facebook 담당자에게 문의하세요.

위치 JSON 구조에 있는 정보로 PageSet를 만들 수 있습니다.

PageSet에서 사용할 수 있는 위치의 최대 개수는 10,000개입니다.

비동기식 요청

비동기식 요청으로 PageSet를 만들 수 있습니다. 이렇게 하면 시간 초과 없이 1,000개 이상의 위치를 포함한 큰 PageSets를 만들 수 있습니다. 50개가 넘는 위치로 Pageset를 만들 때는 항상 비동기식 요청을 사용하는 것이 좋습니다.

요청

curl -X POST \
  -d 'name=<AD_SET_NAME>' \
  -d 'parent_page=<PARENT_PAGE_ID>' \
  -d 'pages=[{"page_id":<CHILD_PAGE_ID>}]' \
  -d 'metadata={"audience":{"size":<AUDIENCE_SIZE>}}' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/ad_place_page_sets_async/

참고:동기식 요청에 /ad_place_page_sets를 사용할 수 있지만 50개가 넘는 위치에는 비동기식 요청을 사용해야 합니다.

매개변수 형식은 동기식 요청에 사용하는 것과 동일합니다.

PageSet 안에서 metadata 필드를 사용하여 광고 게재에 위치별 고정 반경을 지정하거나 특정 타겟 규모에 도달하도록 지정할 수 있습니다. 후자를 선택할 경우 Facebook이 해당 계정 센터 계정 수에 도달하기 위한 위치별 반경을 계산합니다.

이 예시에서 metadata 필드는 권장 audience 크기로 설정됩니다. 반경 metadata를 참조하세요. ad_place_page_set_async_request ID가 반환됩니다.

{
  "id": "405738580111111"
}

나중에는 ads_read 권한으로 이 ID를 쿼리하여 PageSet ID를 얻을 수 있습니다.

curl -i -X GET \
 "https://graph.facebook.com/<API_VERSION>/405738580111111?access_token=ACCESS_TOKEN"

예시 출력

{
  "id": "405738580111111", 
  "place_page_set": {
    "id": "555555791481678",
    "name": "test_ad_set"
  },
  "progress": 1
}

progress가 0.0~1인 경우 1은 Facebook에서 요청을 처리하고 PageSet를 생성했다는 것을 의미합니다.

반경에 `metadata` 사용

metadata 필드는 위치에 고정 반경을 사용할지, Facebook에서 지정된 타겟 규모를 기준으로 위치별 반경을 자동 계산할지 지정합니다.

요청

동기식 요청으로 고정 반경을 설정하는 방법은 다음과 같습니다.

curl -X POST \
  -d 'name=<PAGE_SET_NAME>' \
  -d 'parent_page=<PARENT_PAGE_ID>' \
  -d 'pages=[{"page_id":<CHILD_PAGE_ID>}]' \
  -d 'metadata={"fixed_radius":{"value":5,"distance_unit":"mile"}}' \
  -d 'access_token=ACCESS_TOKEN' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/ad_place_page_sets/

그러면 Facebook이 PageSet 내의 모든 위치에서 반경 5마일 이내에 있는 사용자에게 광고를 게재합니다.

예시 출력

{
  "id": "1618547271777777"
}

참고:metadata 필드는 fixed_radius 또는 audience로 설정되어야 합니다.

fixed_radius를 사용할 경우 distance_unit과 value를 제공해야 합니다.

{
  "fixed_radius": {
     "distance_unit": "<distance_unit>",
     "value": <distance>
  }
}

audience를 사용할 경우 size를 제공해야 하지만 max_radius는 선택 사항입니다.

참고: 이는 ad_place_page_sets_async에만 작동됩니다.

 {
  "audience": {
     "size": <audience_size>,
     "max_radius": { // optional
       "distance_unit": "<distance_unit>",
       "value": <distance>
     }
  }
}

metadata 모범 사례

locations도 제공해야 합니다. 하지만 그 안에 반경을 지정하지 마세요. 또는 locations 매개변수를 사용해서 반경을 제공할 경우 metadata에도 반경을 지정해서는 안 됩니다.
distance_unit은 mile 또는 kilometer여야 하고 value는 mile에 대해서는 0.7~50, kilometer에 대해서는 1~80이어야 합니다.
audience의 size 매개변수는 반경 내에 있는 계정 센터 계정 수입니다. 단, 반경은 길이 1~80km 범위여야 합니다. max_radius를 입력하면 실제 반경은 1~max_radius 사이의 값으로 계산됩니다.
metadata에 audience를 지정하면 비동기식 엔드포인트로 요청을 보내야 합니다(ad_account_ID/ad_place_page_set_async).

동기식 요청

동기식 요청을 사용해 PageSet를 만들 수도 있습니다.

curl -X POST \
  -d "name=<PAGESET_NAME>" \
  -d "parent_page=<PARENT_PAGE_ID>" \
  -d "pages=<LOCATIONS_JSON_STRUCTURE>" \
  -d "access_token=<ACCESS_TOKEN>" \
 https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/ad_place_page_sets

PageSet ID가 반환되며, 이는 나중에 사용합니다.

예시 출력

{
  "id": <PAGE_SET_ID>
}

페이지 개수가 cURL을 호출하기에 너무 많다면 위치 JSON 구조가 포함된 텍스트 파일을 만들고 이를 -F "pages=<locations_json_structure.txt"와 함께 pages 속성으로 전달하면 됩니다.

2단계: 캠페인 만들기

목표를 STORE_VISITS로 설정하고 메인 페이지 ID를 홍보 개체로 설정하여 광고 캠페인을 만듭니다.

광고 캠페인, 참고 자료를 참조하세요.

3단계: 광고 세트 만들기

광고를 포함할 광고 세트를 만듭니다. 참고 자료, 광고 세트, 참고 자료, 타게팅 사양 및 참고 자료, 페이지 위치를 참조하세요.

Facebook은 광고 게재 시점에 로컬 페이지라고 하는 가장 가까운 페이지 위치에서 50마일 이상 떨어진 광고 타게팅 위치는 모두 무효화합니다.

curl \
  -F 'name=Store Visits Ad Set' \
  -F 'promoted_object={"place_page_set_id":"<PAGE_SET_ID>"}' \
  -F 'optimization_goal=REACH' \
  -F 'billing_event=IMPRESSIONS' \
  -F 'is_autobid=true' \
  -F 'daily_budget=1000' \
  -F 'campaign_id=<CAMPAIGN_ID>' \
  -F "targeting={
    'age_min' : <MIN_AGE>,
    'age_max' : <MAX_AGE>,
    'place_page_set_ids': ['<PAGE_SET_ID>'],
    'device_platforms': ['mobile','desktop'],
    'facebook_positions': ['feed']
   }" \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adsets

지역 타게팅

매장 방문 캠페인에서 geo_locations를 기준으로 타게팅할 수도 있습니다.

참고: 이 목표는 광고 세트 타게팅에 geo_locations또는place_page_set_ids만 사용할 수 있습니다.

고급 타게팅 및 노출 위치에서는 국가, 도시, 우편번호별 타게팅을 포함한 모든 유형의 geo_location 타게팅을 지원합니다. 또한 location_types(예: recent, home, travel_in)도 선택할 수 있습니다.

그래도 promoted_object에 place_page_set_id를 제공해야 합니다. 이 PageSet는 명시적 위치 세트가 없는 페이지 세트여야 합니다. 이 PageSet를 만들려면 위치 JSON 구조로 PageSet 만들기를 참조하세요. 그러나 이 경우에는 매개변수 페이지를 전달하지 마세요.

먼저 나중에 홍보 개체에 제공할 PageSet를 만듭니다.

curl -X POST \
  -d "name=My geo targeting page set" \
  -d "parent_page=<PARENT_PAGE_ID>" \
  -d "access_token=<ACCESS_TOKEN>" \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/ad_place_page_sets/

참고: 평소처럼 pages 매개변수를 제공할 필요가 없습니다.

그런 다음, geo_locations를 타게팅하는 매장 방문 목표로 설정한 광고 세트를 만들 수 있습니다.

curl \
  -F 'name=Store Traffic Ad Set' \
  -F 'promoted_object={"place_page_set_id":"<PAGE_SET_ID>"}' \
  -F 'optimization_goal=REACH' \
  -F 'billing_event=IMPRESSIONS' \
  -F 'is_autobid=true' \
  -F 'daily_budget=1000' \
  -F 'campaign_id=<CAMPAIGN_ID>' \
  -F "targeting={
    'geo_locations': {"countries":["US"],"location_types": ["home"]}, 
    'device_platforms': ['mobile','desktop'],
    'facebook_positions': ['feed']
  }" \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adsets

Facebook에서는 광고 시청자와 가장 가까운 매장의 광고를 자동 게재합니다.

4단계: 광고 크리에이티브 제공

누군가의 위치를 기준으로 크리에이티브를 동적으로 삽입할 수 있습니다. 템플릿 자리 표시자 세트를 사용하여 크리에이티브를 맞춤 설정하면 Facebook이 런타임에서 광고의 자리 표시자를 가장 가까운 페이지 위치에서 얻은 데이터로 교체합니다.

사용 가능한 자리 표시자:

{{page.hours.today}}
{{page.location.city}}
{{page.location.region}}
{{page.location.postcode}}
{{page.location.street_address}}
{{page.name}}
{{page.phone_number}}

dynamic_ad_voice 필드를 통해 광고의 음성을 제어할 수 있습니다.

dynamic_ad_voice를 DYNAMIC으로 설정한 경우, 광고 게시물의 페이지 이름과 프로필 사진을 가장 가까운 페이지 위치에서 가져옵니다.
dynamic_ad_voice를 STORY_OWNER로 설정한 경우, 광고 게시물의 페이지 이름과 프로필 사진을 기본 페이지 위치에서 가져옵니다.

행동 유도

누군가의 위치에 따라 행동 유도 버튼(CTA)을 동적으로 추가할 수 있습니다.

GET_DIRECTIONS 또는 CALL_NOW를 사용할 때는 CTA value 필드를 사용하지 않아도 됩니다. 사용자가 가장 가까운 위치로 자동 리디렉션되거나 가장 가까운 위치 전화번호로 연락하라는 메시지가 표시됩니다.
dynamic_ad_voice가 STORY_OWNER로 설정된 경우에만 MESSAGE_PAGE가 허용됩니다. 메시지가 기본 페이지로 전달됩니다.
선택 필드입니다. 각 광고에 지정하지 않을 경우 Like Page 버튼이 표시됩니다.

자세한 내용은 참고 자료, 광고 크리에이티브를 참조하세요.

dynamic_ad_voice 유형 call_to_action 유형

`dynamic_ad_voice` 유형	`call_to_action` 유형
`DYNAMIC`	`CALL_NOW` `GET_DIRECTIONS`
`STORY_OWNER`	`CALL_NOW` `GET_DIRECTIONS` `LEARN_MORE` `MESSAGE_PAGE` `ORDER_NOW` `SHOP_NOW`

DYNAMIC

CALL_NOW

GET_DIRECTIONS

STORY_OWNER

CALL_NOW

GET_DIRECTIONS

LEARN_MORE

MESSAGE_PAGE

ORDER_NOW

SHOP_NOW

예

동적 페이지 이름과 도시를 사용하여 광고 크리에이티브를 제공합니다.

curl \
  -F 'dynamic_ad_voice=DYNAMIC' \
  -F 'object_story_spec={ 
    "page_id": "<PARENT_PAGE_ID>", 
    "template_data": { 
      "description": "Ad Description", 
      "link": "<URL>", 
      "message": "Ad Message for {{page.location.city}}", 
      "name": "{{page.name}}", 
      "picture": "<IMAGE_URL>" 
    } 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adcreatives

지도 카드를 사용한 광고 크리에이티브

지도 카드를 사용하려면 광고 크리에이티브의 child_attachments 필드에 있는 첨부 파일에 place_data 구조를 추가합니다.

이 예시에서 Facebook 매장 찾기 링크가 포함된 지도는 child_attachments 배열의 두 번째 항목입니다. 지도 카드 외에도 1개 이상의 항목을 제공해야 합니다.

curl \
  -F 'dynamic_ad_voice=DYNAMIC' \
  -F 'object_story_spec={ 
    "page_id": "<PARENT_PAGE_ID>", 
    "template_data": { 
      "description": "Ad Description", 
      "link": "<URL>", 
      "message": "Ad Message for {{page.location.city}}", 
      "name": "{{page.name}}", 
      "child_attachments":[
        {
          "description": "Come visit us!",
          "link": "http://yourweburl.com",
          "name": "{{page.location.street_address}} - {{page.location.city}}",
          "call_to_action": {
            "type":"GET_DIRECTIONS"
          },
        },
        {
          "link": "https://fb.com/store_locator",
          "name": "Check out our stores.",
          "place_data": {
            "type":"DYNAMIC"
          },
        }
      ]
    } 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adcreatives

매장 찾기(링크 대상)

광고를 만들 때 link를 'https://fb.com/store_locator'로 설정하면 그 광고에서는 매장 찾기가 링크 대상으로 표시됩니다.

5단계: 광고 만들기

다음과 같이 광고를 만듭니다.

curl \
  -F 'name=My Ad' \
  -F 'adset_id=<AD_SET_ID>' \
  -F 'creative={"creative_id":"<CREATIVE_ID>"}' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/ads

매장 방문을 위한 광고를 만들려면 페이지와 광고 계정이 매장 방문수 측정에 대해 승인을 받아야 합니다. 그렇지 않으면 Reach estimate isn't available because 'store_visits' isn't a valid action type과 같은 오류가 표시됩니다.

매장 방문수 측정

매장 방문수는 위치 서비스를 활성화한 사용자의 데이터를 기반으로 추정한 지표입니다. 최종적으로는 매장 방문 목표에 대해 매장 방문수 측정과 최적화를 제공합니다. 매장 방문수 측정은 매장 방문 목표를 설정한 캠페인에만 제공됩니다.

매장 방문수는 매장 방문 목표를 사용하는 광고의 클릭 및 조회수를 기준으로 합니다. 이는 각 매장 광고를 보거나 클릭한 계정 센터 계정이 광고주 매장을 방문한 횟수를 추정한 값입니다. 기여 기간을 설정할 수 있습니다. 1일, 7일 또는 28일 클릭수나 조회수를 기준으로 맞춤 설정할 수 있습니다. 구성을 맞춤 설정하지 않았다면 광고 계정의 기본 기여가 적용됩니다. 인사이트 API, 기여 기간을 참조하세요.

이 기능은 다음의 항목에 대한 보고와 관��이 있습니다.

매장 방문수 — 광고로 인해 매장을 방문한 것으로 추산되는 횟수
매장 방문당 비용 — 광고로 인해 매장을 방문한 것으로 추산되는 횟수에 대한 평균 비용

광고 관리자 사용

ENGAGEMENT: ACTIONS 아래의 열을 참조하세요. 이 열은 매장 방문수 및 매장 방문당 비용을 보고하는 인터페이스에 표시됩니다.

참고: 매장 방문 데이터는 Meta 팀에서 캠페인에 대해 측정 가능하다고 확인한 매장에만 제공됩니다.

인사이트 API 사용

인사이트 API에서 매장 방문수 데이터를 가져올 수 있습니다. 일반 인사이트 호출에 추가 필드(cost_per_store_visit_action 및 store_visit_actions)를 제공합니다. 인사이트, 참고 자료를 참조하세요.

매개변수

필드 설명

필드	설명
`point_estimate` int32	The point prediction of the value 기본

point_estimate

int32

The point prediction of the value

기본

노출 위치

게재 최적화

어드밴티지+ 카탈로그 광고 만들기

요구 사항

1단계. PageSet 만들기

모든 매장 위치 수집

위치 JSON 구조 만들기

개별 요청

일괄 요청

최종 위치 JSON 구조

위치 JSON 구조로 Pageset 만들기

비동기식 요청

반경에 metadata 사용

동기식 요청

2단계: 캠페인 만들기

3단계: 광고 세트 만들기

지역 타게팅

4단계: 광고 크리에이티브 제공

행동 유도

예

지도 카드를 사용한 광고 크리에이티브

매장 찾기(링크 대상)

5단계: 광고 만들기

매장 방문수 측정

광고 관리자 사용

인사이트 API 사용

매개변수

1단계. `PageSet` 만들기

위치 JSON 구조로 `Pageset` 만들기

반경에 `metadata` 사용