3：開發人員實作方式

本頁說明手動整合工具的相關資訊，並涵蓋以下主題：

為 CRM 整合工具組建承載
產生存取權杖並準備 API 呼叫
傳送測試承載
傳送生產資料

只有在決定使用手動整合工具和開發人員資源來完成此整合時，才適用本小節。如果您決定使用合作夥伴來完成此整合，請依照相應的合作夥伴指示進行整合。完成合作夥伴整合後，您可以跳至本指南的「4：驗證資料」一節。

須有企業管理平台的管理員存取權限，才能完成這些整合步驟。如果您受邀成為開發人員，您可在所收到的電子郵件中取得存取權限。若否，請聯絡企業管理平台管理員，以要求存取權限。

步驟 1：組建承載

此步驟將列出「轉換潛在客戶」整合工具的承載規範，並提供一些建議，以說明如何從伺服器發送整合工具。

從 CRM 像素的設定頁籤開啟 CRM 整合指南，以開始執行。

請參閱轉換 API 開發人員指南，以瞭解轉換 API 的運作原理。

建議使用承載協助工具組建承載。承載協助工具將設定承載格式並檢查錯誤。解決所有承載錯誤後，請點擊承載協助工具內的取得程式碼按鈕，依照您的程式設計語言產生程式碼範本。

以下列出所需的參數。請參閱承載規範指南：轉換潛在顧客整合工具，以查看每種參數的完整說明。此承載規範僅應用於「轉換潛在顧客最佳化」事件。因此，事件僅能與 Meta 潛在顧客廣告相關，並具有有效的潛在顧客編號。請勿將此承載規範用於其他事件類型，例如網站潛在顧客人數。

參數

名稱	說明
`event_name` 字串	自由格式欄位，用於擷取在 CRM 內使用的潛在顧客階段。 `event_name` 參數應會指出正在進行 CRM 銷售漏斗流程的潛在顧客。請務必發送更新後的所有階段，包括初始潛在顧客。
`event_time` 整數	Unix 時間戳記（以秒為單位）可指出 CRM 潛在顧客階段更新事件的更新時間。時間戳記須在潛在顧客產生時間之後，否則系統可能會捨棄事件。
`action_source` 字串	值：`system_generated` （使用轉換 API，即表示您同意 `action_source` 參數就您所知是正確的。）
`lead_id` 整數	您下載的潛在顧客所包含的 15 位數或 16 位數 `leadgen_id`。
`lead_event_source` 字串	事件來源的 CRM 名稱。
`event_source` 字串	值：`crm`

範例
承載範例可能如下所示。注意：必須使用有效的 lead_id，否則系統將拒絕事件。

{
    "data": [
        {
            "event_name": "initial_lead",
            "event_time": 1629424350,
            "action_source": "system_generated",
            "user_data": {
                "lead_id": 525645896321548
            },
            "custom_data": {
                "event_source": "crm",
                "lead_event_source": "salesforce"
            }
        }
    ]
}

如果事件未遵守承載規範，或與 Meta 潛在顧客廣告不相符，將不在整合工具的辨識範圍內，也不會用於訓練模型。
例如，轉換 API 可接受網路承載，並會顯示在事件管理工具中，但此整合工具並不會識別網路承載。您也必須使用有效的 lead_id，否則系統將拒絕事件。
只有「轉換潛在顧客承」載會在整合工具的辨識範圍內，並可用於訓練。

步驟 2：建立存取權杖和 API 呼叫

配置要傳送的內容後，接下來要配置資料的傳送位置。

此步驟將有助於為 Meta 像素產生存取權杖，隨後便能用於在伺服器和轉換 API 之間建立連線。

您可以返回 CRM 像素的設定頁籤查看 CRM 整合指南。

向下捲動至建立端點區塊，然後點擊產生存取權杖按鈕。存取權杖將用於組建 API 呼叫。
若要產生新的存取權杖，您可以返回整合指南，或從事件管理工具的設定頁籤中，導覽至轉換 API 區塊，然後點擊產生存取權杖連結。

本指南的其餘內容依據使用 Meta SDK 與否而有所不同。建議使用 Meta 商業 SDK，因為其提供更出色的錯誤與診斷訊息傳送功能。您將需要像素編號和存取權杖，才能透過 Meta 商業 SDK 進行 API 呼叫。若要取得存取權杖，您可以點擊 CRM 整合指南中的複製存取權杖並儲存權杖。如需 SDK API 呼叫範例，可參閱轉換 API 開發人員指南，或使用 Meta 承載協助工具中的取得程式碼功能。

此端點格式無需透過 SDK，即可向轉換 API 發送 POST 要求。若要取得完整端點，您可以點擊 CRM 整合指南中的複製端點杖並儲存端點。
```
https://graph.facebook.com/API_VERSION/PIXEL_ID/events?access_token=ACCESS_TOKEN
```
- API_VERSION：行銷 API 的現行版本
- PIXEL_ID：可從每個像素的事件管理工具取得像素編號
- ACCESS_TOKEN：前面步驟中產生的存取權杖
在「API 版本」說明文件中，可查看行銷 API 的發布日期和到期日期。請務必在行銷 API 到期日之前，更新程式碼中的 API 版本或 Meta 商業 SDK。若在程式碼中使用已停用的版本，可能會導致錯誤發生，系統也可能會將捨棄事件。

步驟 3：測試承載（選用）

在此階段，您可以先向像素發送測試承載，再於伺服器上實作程式碼。您可以使用事件管理工具中的測試事件頁籤來發送測試承載。

在測試伺服器事件區塊中，點擊圖形 API 測試工具連結。透過此專屬連結，系統將預先填入部分的像素資訊。（如有需要，您也可以直接存取圖形 API 測試工具。）記下 test_event_code 值，該值可能會隨時間而變化。

在圖形 API 測試工具中完成以下操作：
1. 確保處於 POST 模式。
2. 檢查 API 版本和像素編號是否正確。
3. 切換到 JSON 檢視。
4. 輸入承載。這可透過承載協助工具手動建立或產生。請確保包含前一個步驟中的 test_event_code 參數和有效的 lead_id。
輸入像素存取權杖，然後點擊提交按鈕。

如果承載不包含任何語法或 API 錯誤，您應該會收到含有 fbtrace_id 的成功訊息。

稍後，測試事件應會出現在事件管理工具中的測試事件頁籤下。

步驟 4：發送生產資料

生產資料的格式應與步驟 3 中產生的承載相同，除非是直接來自伺服器的資料。每個整合工具的這個步驟都有所不同，因此本小節將提供守則，而非逐步指示。

配對時，請傳送 lead_id 而非 PII。

請確保在更新後傳送所有潛在顧客階段，包括代表在 Meta 上產生且下載到 CRM 中的所有潛在顧客的初始潛在顧客事件。以下是漏斗範例。事件名稱和階段由廣告商定義，因此不必符合此範例。

如果您的行銷活動產生 100 個潛在顧客，則我們預計會上傳 100 個「初始潛在顧客」事件，以代表第一個潛在顧客階段。傳送第一個潛在顧客階段後，系統便知道該潛在顧客已收到並經過處理。隨著潛在顧客進行銷售漏斗流程，我們預計會上傳 70 個「符合行銷資格的潛在顧客」、30 個「銷售機會」和 15 個「已轉換」階段。

回顧一下，行銷活動產生了 100 個潛在顧客，但我們預計會在此範例情境中上傳 215 個事件。

請建立函數，用以在潛在顧客狀態更新時，從 CRM 的 API 或資料庫擷取更新。然後使用自訂函數或 Meta 的商業 SDK，將承載傳送到 Meta 的轉換 API。對整合工具最重要的因素，視 CRM 和資料庫配置而定。

建議將變數用於：

lead_id
event_name
event_time

例如，明確說明參數值的承載可能如下所示：

{
  "event_name": "initial_lead",
  "event_time": 1628294742,
  "user_data": {
    "lead_id": 1234567890123456
  },
  "action_source": "system_generated",
  "custom_data:" {
    "lead_event_source": "Salesforce",
    "event_source": "crm"
  }
}

使用變數從資料庫傳遞值的承載可能如下所示：

{
  "event_name": lead_stage // "initial_lead"
  "event_time": unix_time // 1628294742
  "user_data": {
    "lead_id": fb_lead_id // 1234567890123456
  },
  "action_source": "system_generated",
  "custom_data:" {
    "lead_event_source": "Salesforce",
    "event_source": "crm"
  }
}

請每天至少上傳一次資料。理想情況下，對 CRM 的呼叫應即時進行，然若無法執行即時整合，則可採用每小時或每天批次進行的方式。
如果選擇批次方式，請務必擷取潛在顧客的狀態變更記錄，而非批次當下的潛在顧客快照。例如，如果潛在顧客的狀態在批次之間更新 3 次，我們預計此潛在顧客會有 3 個事件，而非只有最終更新。
注意：每個批次最多可包含 1,000 個事件。如果批次中存在錯誤，系統將會捨棄整個批次，因此強烈建議採用較小的批次，並加入嘗試重試的邏輯。

選用。建議記錄來自 CAPI 呼叫的錯誤訊息，並在出現問題時建立警告。您也可以將這些錯誤視為例外情況處理。

最多可回填過去 7 天內的資料。系統會計算 event_time 和 upload_time 之間的時間差。透過回填部分資料，可能會加快訓練速度。
警告：請勿嘗試透過修改 event_time 值來回填超過 7 天的資料。模型須依靠準確的時間戳記來進行最佳化。此作法可能會導致系統捨棄所有回填的資料。
請確保 event_time 值位於潛在顧客產生時間戳記之後，否則系統可能會捨棄事件。

如果整合工具將事件上傳到 Meta，事件應會在一小時內開始顯示於像素的事件管理工具中。請記得在承載中使用有效的 lead_id，以便顯示事件。請在事件管理工具中，開啟為「轉換潛在顧客」CRM 整合工具傳送的每個事件，並確認這些事件是否已填入自訂參數 lead_event_source 和 event_source。如果事件中沒有這些參數，便不會登記為「轉換潛在顧客」事件。
系統將驗證是否有任何事件是有效的「轉換潛在顧客」事件。1 天後，如果偵測到有效事件，整合工具的傳送 CRM 事件步驟旁將顯示綠色勾選符號。

< 2: Getting Started With the CRM Integration

4：驗證資料