即時體驗

即時體驗是一種全螢幕體驗，用戶點擊廣告後便會前往特定目的地，此目的地幾乎可以立刻從動態消息的廣告中載入。

如果您在此 API 中見到任何提及 canvas 的內容，請將之理解為適用於即時體驗的內容。「全螢幕展示廣告」是這個格式的舊稱。

準備工作

若要建立及管理即時體驗，您需要：

限制

您只能更新未發佈的即時體驗。
Instagram 上的即時體驗 API 僅限特定對象使用。
Facebook 限時動態並不支援使用即時體驗的廣告。

建立

若要建立即時體驗，您需要 Facebook 專頁的編號（PAGE-ID），以及任何您想包含在體驗中的素材編號，例如相片、按鈕及文字。

curl \
  -F 'background_color=FFFFFF' \
  -F 'body_element_ids=["<CANVAS_PHOTO_ID>"]' \
  -F 'is_hidden=' \
  -F 'is_published=' \
  -F 'name=Canvas Name' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<PAGE_ID>/canvases

素材

名稱	說明
按鈕	即時體驗內的按鈕。`button_style` 為必要欄位。
輪播廣告	即時體驗的輪播廣告。
頁尾	即時體驗的頁尾。
頁首	即時體驗的頁首。
相片	即時體驗內的相片。您需要為上載至 Facebook 專頁的相片提供 `PHOTO-ID`。
商品清單	即時體驗的商品清單。
商品組合	來自進階高效速成目錄廣告商品目錄的商品組合，會顯示在即時體驗中。
商店定位工具	即時體驗內的商店定位工具。
文字	即時體驗內顯示的文字和文字風格。
影片	即時體驗內的影片。您需要為上載至 Facebook 專頁的影片提供 `VIDEO-ID`。

刪除素材

若要刪除某個素材，請傳送包含該素材編號的 DELETE 要求。

curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<CANVAS_ELEMENT_ID>

取得現有即時體驗

若要取得現有即時體驗的資訊，您需要擁有該即時體驗的編號（CANVAS-ID）。

curl -G \
  --data-urlencode 'fields=[ 
    "body_elements", 
    "canvas_link", 
    "id", 
    "is_hidden", 
    "is_published", 
    "name" 
  ]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<CANVAS_ID>

取得專頁的所有即時體驗

若要取得某個 Facebook 專頁全部現有即時體驗的資訊，您需要擁有該專頁的編號（PAGE-ID）。

curl -G \
  --data-urlencode 'fields=[ 
    "background_color", 
    "body_elements", 
    "canvas_link", 
    "id", 
    "is_hidden", 
    "is_published", 
    "last_editor", 
    "name", 
    "owner", 
    "update_time" 
  ]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<PAGE_ID>/canvases

更新即時體驗

若要更新即時體驗，該體驗必須未經發佈，而您需要擁有該即時體驗的編號（CANVAS-ID），以及任何您想更新的素材編號。

curl \
  -F 'background_color=FFFFFF' \
  -F 'body_element_ids=["<CANVAS_PHOTO_ID>"]' \
  -F 'is_hidden=' \
  -F 'is_published=' \
  -F 'name=Canvas Name' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<CANVAS_ID>

使用範本

您可以使用範本，針對特定業務目標快速建立即時體驗。每個範本的版面均為固定，但您可將預設內容換成自己的圖像、影片、商品、文字和連結。

API 範本名稱	範本編號	說明
吸引新顧客	`133471657203838`	透過流動版已連結頁面鼓勵用戶採取行動，增加轉換次數。廣告管理員內的「顧客招攬」範本。
展示業務內容	`1063217037112304`	以引人入勝的方式吸引用戶探索您的品牌、商品或服務。廣告管理員內的「故事營銷」範本。
銷售商品（不使用目錄）	`424787857903852`	透過上載商品資訊建立流動購物體驗，無需使用目錄。廣告管理員內的「銷售商品（不使用目錄）」範本。
銷售商品：生活品味版面	`1369752616394017`	以相片展示商品，方便用戶進一步探索。廣告管理員內的「型錄」範本。
銷售商品：網格版面	`1932289657009030`	透過商品目錄建立體驗，讓用戶直接從他們的流動裝置購物。廣告管理員內的「店面陳列」範本。
AR 體驗		「AR 體驗」範本只透過廣告管理員提供。

取得範本的素材類型

步驟 1：取得範本的文件資料

傳送 GET 要求以決定特定範本所需的素材，我們在以下範例中採用了「開發新客戶」範本。

curl -i -X GET \
 "https://graph.facebook.com/VERSION/133471657203838?fields=document&access_token=ACCESS-TOKEN"

回應範例

{
  "document": {
    "name": "Get New Customers",
    "id": "397246414010297"
  },
  "id": "133471657203838"
}

步驟 2：取得素材類型

在 document 欄位使用編號，以取得指定範本可用的特定素材。

curl -i -X GET \
 "https://graph.facebook.com/VERSION/397246414010297?fields=body_elements&access_token=ACCESS-TOKEN"

傳回的清單會列出「開發新客戶」範本可用的素材類型。

    {
  "body_elements": [
    {
      "name": "Cover Image or Video",
      "element_type": "PHOTO",
      "id": "397271930674412"
    },
    {
      "name": "Text",
      "element_type": "RICH_TEXT",
      "id": "397271920674413"
    },
    {
      "name": "Text",
      "element_type": "RICH_TEXT",
      "id": "397271910674414"
    },
    {
      "name": "Button",
      "element_type": "BUTTON",
      "id": "397271914007747"
    },
    {
      "name": "Carousel",
      "element_type": "CAROUSEL",
      "id": "397271940674411"
    },
    {
      "name": "Text",
      "element_type": "RICH_TEXT",
      "id": "397271917341080"
    },
    {
      "name": "Button",
      "element_type": "BUTTON",
      "id": "397271924007746"
    }
  ],
  "id": "397246414010297"
}

發佈

若要發佈您的即時體驗廣告，請傳送 POST 要求至您的即時體驗編號（CANVAS-ID），並將 is_published 欄位設為 true。

curl \
  -F 'is_published=1' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<CANVAS_ID>

建立廣告創意

透過現有即時體驗的連結（CANVAS-LINK）建立廣告創意。

curl -X POST \
  -F 'image_hash="<IMAGE_HASH>"' \
  -F 'object_story_spec={
       "page_id": "<PAGE_ID>",
       "link_data": {
         "image_hash": "<IMAGE_HASH>",
         "link": "<CANVAS_LINK>",
         "name": "Creative message",
         "call_to_action": {
           "type": "LEARN_MORE"
         }
       }
     }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/adcreatives

即時體驗準備就緒後，您可以進一步建立廣告群組、廣告組合及廣告宣傳活動。

即時體驗廣告對話框

您可以使用即時體驗廣告對話框，以在您的網站提供 Facebook 即時體驗廣告建立用戶介面。如需進一步了解用戶介面元件，請參閱對話框。

設定 Facebook JavaScript SDK，請參見：

JavaScript SDK 必須取得已登入用戶的權限，方可建立即時體驗。如果用戶沒有必要的權限來為提供的專頁和企業建立即時體驗，對話框便會彈出錯誤提示。如要避免出錯，用戶必須為企業的成員，且須獲取專頁的「建立廣告」權限。

然後，觸發對話框：

FB.ui({         
  display: 'popup',
  method: 'instant_experiences_builder',
  business_id: '<BUSINESS_ID>',
  page_id: '<PAGE_ID>'
}, function(response) {
  // callback
});

您可以為附加程式提供這些設定：

名稱	必填	說明
`display`	是	此為必要參數，設定值為 `popup`
`method`	是	此為必要參數，設定值為 `instant_experiences_builder`
`business_id`	是	您的企業管理平台編號
`page_id`	是	您想將即時體驗連結至的專頁編號
`canvas_id`	否	您想編輯的即時體驗編號

canvas_id 參數為選用項目，用作允許用戶編輯或預覽現有的即時體驗。即時體驗建立完成後，您將無法再編輯。若要預覽即時體驗，我們建議使用即時體驗預覽對話框。

成功的話，附加程式會提供以下回應：

{
  "success": true,
  "id": "CANVAS-ID"
}

傳回的編號為已發佈的即時體驗。您現在可將之用於廣告宣傳活動。若沒有回應或傳回 undefined 回應，則表示觀眾在完成即時體驗前已關閉對話框。用戶可能已儲存即時體驗但尚未完成。您可以使用 Graph API 擷取屬於某個專頁的所有即時體驗，以查看是否有任何尚未完成的體驗。

預覽即時體驗

iframe 預覽 API

您可透過呼叫預覽 API 產生即時體驗預覽，此 API 會傳回 iframe，類似於廣告預覽 API：

curl -X GET \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v18.0/<CANVAS_ID>/preview
  
Open In Graph API Explorer

API 會傳回類似以下的內容，此內容可透過在 HTML 中嵌入傳回的 iframe 素材查看：

{
"data": [
    {
      "body": "<iframe src=\"https://www.facebook.com/ads/canvas/preview?d=AQKELApdJxoVp2f3PHl8-pRtYuAh4-_eDupMDbh-pS9zde_EFxckhYQCXu7NYUi4PhhBA7uskIo2Ys3IjIVNGZiS&t=AQKGOPqGI-NWcv1YKbA\" width=\"405\" height=\"720\" scrolling=\"yes\" style=\"border: none;\"></iframe>"
    }
  ],
  "__www_request_id__": "AQnyr47Qp2r5M-ISqSiMgrw"
}

Facebook SDK

您可以使用此對話框提供即時體驗預覽，了解 Facebook 用戶從您網站看到的即時體驗會是怎樣。如需進一步了解用戶介面元件，請參閱對話框。

設定 Facebook JavaScript SDK，請參見：

JavaScript SDK 必須取得已登入用戶的權限，方可建立即時體驗。如果用戶沒有查看即時體驗的必要權限，對話框便會彈出錯誤提示。

然後，觸發預覽對話框：

FB.ui({         
  display: 'popup',
  method: 'instant_experiences_preview',
  canvas_id: 'CANVAS-ID'
});

您可以為附加程式提供這些設定：

名稱	必填	說明
`display`	是	此為必要參數，設定值為 `popup`
`method`	是	此為必要參數，設定值為 `instant_experiences_preview`
`canvas_id`	是	您想預覽的即時體驗編號

為即時體驗建立廣告受眾

若要建立互動廣告受眾，亦即曾與即時體驗互動的廣告受眾，請在 POST /act_AD-ACCOUNT/customaudiences 呼叫中將 rule 欄位的 object_id 參數設定為即時體驗編號（CANVAS-ID）。

曾開啟即時體驗的用戶

curl \
  -F 'name=Instant Experience Engagement Audience' \
  -F 'description=People who opened this Instant Experience' \
  -F 'rule=[{"object_id":"<CANVAS_ID>","event_name":"instant_shopping_document_open"}]' \
  -F 'access_token=<ACCESS_TOKEN>' \  
https://graph.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/customaudiences
Open In Graph API Explorer

曾點擊即時體驗中任何連結的用戶

curl \
  -F 'name=Instant Experience Engagement Audience' \
  -F 'description=People who clicked any links in this Instant Experience' \
  -F 'rule=[{"object_id":"<CANVAS_ID>","event_name":"instant_shopping_element_click"}]' \
  -F 'access_token=<ACCESS_TOKEN>' \  
https://graph.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/customaudiences
Open In Graph API Explorer

如需更多有關自訂廣告受眾的資訊，請參閱自訂廣告受眾：參考資料。

即時體驗與 Instagram 廣告

如要在 Instagram 執行即時體驗，所使用的 API 呼叫與 Facebook 即時體驗的相同。請注意，使用 Instagram 與即時體驗時會有以下限制：

廣告版位 - 適用於 Instagram 動態消息及 Instagram 限時動態。如果您選擇 Instagram 限時動態，請選擇此版位作為唯一的廣告版位。
即時體驗素材：全面支援頁首與商品組合。

在 Instagram，我們僅支援部分即時體驗素材：

頁首 - 如無 swipe to open，用戶端會顯示為 Tap to open。
輪播廣告：不得含有連結至其他即時體驗的相片；在用戶端顯示為無法點擊的連結。至於相片與影片，系統無法將之改為符合畫面高度、符合畫面闊度或傾移檢視；此會顯示為符合畫面闊度。
按鈕 - 無法連結至其他即時體驗或 App Store。
文字：不支援 RTL 語言。
影片 - 不支援 360 度影片。
商店定位工具 - 不支援。

廣告洞察報告

請參閱廣告洞察報告，了解可用衡量數據的概覽與描述。

另請參閱

Facebook 廣告指南：即時體驗規格
企業商家幫助中心：了解即時體驗