來店客流量目標 - 推廣 API - 文件

推廣 API

版位

適用於 Facebook 桌面版和流動版（動態消息、限時動態及 Marketplace）與 Instagram（動態消息、限時動態、Reels 連續短片、個人檔案動態消息、探索、主頁及個人檔案連續短片）。

刊登優化

接觸人數優化：供可存取此 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> 為所有商店地點主要專頁的專頁編號。此編號會檢索屬於主要專頁的所有分店專頁和地點，並傳回每個地點的經緯度：

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 結構

將每個地點的 <CHILD_LOCATION_ID> 設定為 page_id，然後使用從之前呼叫獲取的 radius 和 distance_unit 參數建立最終地點 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": "405738580111111"
}

之後，您可以使用 ads_read 權限查詢該編號，以獲取 PageSet 編號。

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 表示我們已完成您的要求且已建立 PageSet。

使用半徑的 `metadata`

metadata 欄位可讓 Facebook 了解您希望鎖定地點的固定半徑範圍，還是希望 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，其中 mile 的 value 必須介乎 0.7 和 50，kilometer 則必須介乎 1 和 80。
audience 中的 size 參數是半徑範圍內的帳戶管理中心帳戶數量，前提是半徑長度為 1 至 80 公里之間。如果您提供 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": <PAGE_SET_ID>
}

如果專頁數量過多而無法使用 cURL 呼叫，您可以建立包含地點 JSON 結構的文字檔案，然後透過 -F "pages=<locations_json_structure.txt" 將其傳遞給 pages 屬性。

第 2 步：建立宣傳活動

建立廣告宣傳活動並將目標設定為 STORE_VISITS，以及將主要專頁編號設定為推廣的物件。

詳情請參閱廣告宣傳活動，參考資料。

第 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必須為不包含任何明確地點組合的專頁組合。請參閱透過地點 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

如果用戶觀看您的廣告，我們會自動為其刊登距離最近的商店之廣告。

第 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，則廣告帖子的專頁名稱和個人資料相片會從主要專頁地點提取。

呼籲字句

您也可以依據用戶所在地點，靈活加入呼籲字句按鈕：

使用 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

包含地圖卡的廣告創意

若要使用地圖卡，請為廣告創意新增 place_data 結構，以作為 child_attachments 欄位的附件。

在這個範例中，包含 Facebook 商店地點連結的地圖是 child_attachments 陣列的第二個項目。除了地圖卡之外，您必須提供最少一個項目。

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`