轉換 API

參數建立工具資料庫

Meta 在用戶端（JavaScript）和伺服器端（PHP、Java、Python、NodeJS、Ruby）都有提供 SDK 資料庫清單。這些 SDK 程式庫旨在協助開發人員改善轉換 API 事件 參數的品質（例如，fbc、fbp 、client_ip_address 和其他顧客資訊參數，像是 em 和 ph），並讓廣告主能夠遵循 Meta 用於產生這些參數的最佳作法。

本文件包含上述兩個資料庫的總覽、應使用哪個資料庫的指引，以及使用案例範例。

資料庫總覽

用戶端：資料庫和事件位於瀏覽器端的前端。資料庫以 JavaScript 實作。開發人員可以直接將其整合到他們的網頁中。

伺服器端：資料庫和事件位於伺服器端的後端。Meta 會根據後端使用的語言，提供不同語言（PHP、Java、Python、NodeJS 和 Ruby）的資料庫。

選擇資料庫

所有程式庫都能獨立運作。為了讓您或您的顧客充分發揮潛力，請查看此處的建議。

Parambuilder 遵循 Meta 開發人員文件中提及的最佳作法。實作於用戶端（JavaScript）和伺服器端（PHP、Java、Python、NodeJS、Ruby）。

使用案例參考範例

建立解決方案時，下列使用案例可能值得考慮。

建議：伺服器端參數建立工具 + 用戶端參數建立工具

將伺服器端參數建立工具與用戶端參數建立工具搭配使用，可協助您充分發揮潛力來達到高 fbc 和 IPv6 覆蓋率。

若要這麼做，您需要將兩個程式庫整合在一起：伺服器端參數建立工具和用戶端參數建立工具。




工作流程範例

  • 廣告主用戶端應用程式載入用戶端參數建立工具，並使用函數指標 getIpFn 來叫用提供的 API processAndCollectAllParams。
  • 系統將會呼叫提供的 getIpFn，並根據實際的 getIpFn 實作從廣告商設定的端點擷取 IPv6。
  • IPv6 將會從廣告主設定的端點傳回，並從 getIpFn 的傳回值傳回給用戶端參數建立工具。擷取的 IPv6 將儲存在索引鍵為 _fbi 的 Cookie 中，以供稍後擷取。
  • 在用戶端，使用擷取 API（或其他前後端通訊）和第一方 Cookie，開始與後端伺服器進行日常通訊。
  • 在伺服器端，根據您在接收端點（例如，ExampleController）中選擇的語言來整合伺服器端程式庫，並叫用提供的 API processRequest 來處理要求。
  • processRequest API 將傳回建議在用戶端更新的 Cookie 的清單。
  • 在回應標頭中設定建議的 Cookie，以指示用戶端瀏覽器進行儲存。
  • 叫用提供的各種 API，例如 getFbc()、getFbp()、getClientIpAddress() 和 getNormalizedAndHashedPII()。
  • SDK 會傳回各種值，例如 fbc、fbp、client_ip_address、email 和手機號碼。
  • 透過轉換 API 將這些擷取的值傳回給 Meta。
// Example Controller which processes all requests to example.com
// Start process
ParamBuilder paramBuilder = new ParamBuilder(Arrays.asList('example.com', 'yourDomain.com'));
// Input the request's full URL, such as: example.com?fbclid=xxxxx
// Process and get recommended updated cookie
List<CookieSetting> updatedCookieList =
        paramBuilder.processRequest(
            request.getHeader("host"),  // example.com
            request.getParameterMap(), // {'fbclid':['xxxxx']}
            cookieMap, 
            request.getHeader("referer"),
request.getHeader("X-Forwarded-For"),
request.getRemoteAddr(),
); // optional: referer full url


// Save cookie from server side
for (CookieSetting updatedCookie : updatedCookieList) {
      Cookie cookie = new Cookie(updatedCookie.getName(), updatedCookie.getValue());
      cookie.setMaxAge(updatedCookie.getMaxAge());
      cookie.setDomain(updatedCookie.getDomain());
      response.addCookie(cookie);
 }

// Get fbc, fbp, client_ip_address
String fbc = paramBuilder.getFbc();
String fbp = paramBuilder.getFbp();
String client_ip_address = paramBuilder.getClientIpAddress();

// Get Normalized and Hashed PII like email and phone number
String normalizedAndHashedEmail = paramBuilder.getNormalizedAndHashedPII(‘John_Smith@gmail.com’,’email’);
String normalizedAndHashedPhone = paramBuilder.getNormalizedAndHashedPII(‘(650)555-1212’,’phone’);

// Call CAPI endpoint
.....
.setFbc(fbc)
.setFbp(fbp)
.setClientIpAddress(client_ip_address)
.setEmail(normalizedAndHashedEmail)
.setPhone(normalizedAndHashedPhone)
....

僅限伺服器端 ParamBuilder

如需詳細範例，請參閱伺服器端參數建立工具新手指南或其中連結的 README 檔案。

工作流程範例

  • 在伺服器的端點中，根據相關的語言和架構匯入 ParamBuilder 資料庫。
  • 呼叫 paramBuilder.processRequest，取得建議更新的 Cookie 清單。
  • 將 Cookie 設定為您的回應。
  • 透過個別使用 paramBuilder.getFbc()、paramBuilder.getFbp()、paramBuilder.getClientIpAddress() 和 paramBuilder.getNormalizedAndHashedPII()，來將 fbc、fbp、client_ip_address 和其他 PII（例如電子郵件地址和電話號碼）設定至轉換 API 的呼叫

僅限用戶端 ParamBuilder

如需詳細範例，請參閱用戶端參數建立工具新手指南或其中連結的 README 檔案。

工作流程範例

  • 載入連結頁面時，呼叫 clientParamBuilder.processAndCollectAllParams(url, getIpFnl)。
  • 然後系統便會將要求傳送到伺服器端。接著，伺服器可以使用金鑰 _fbc、_fbp 和 _fbi，分別從 Cookie 讀取 fbc、fbp 和 client_ip_address。
    • 注意：如果連結網址不包含 fbclid，則可能缺少 fbc。這是預期的行為。

實用連結

主要 Github 連結

請確認您使用的是最新版本。

最佳作法

  • 請務必在網頁的顧客歷程中及早儲存 _fbp 和 _fbc Cookie。理想的做法是在載入連結頁面時擷取 _fbp 和 _fbc Cookie。不建議您只從下層漏斗事件或在觸發特定事件時才擷取 Cookie。
  • 請不要覆寫或調整 _fbc 或 _fbp Cookie。_fbc 區分大小寫，請不要將 _fbc 標準化或格式化為小寫。
  • 請務必將資料庫套用至所有介面（例如行動裝置、桌上型電腦和瀏覽器），以及您要追蹤的網域。
  • 伺服器端資料庫用於後端，而用戶端資料庫則用於前端瀏覽器端。開發人員可直接在網頁中整合用戶端資料庫，而伺服器端資料庫則是在後端伺服器端呼叫。請注意，用戶端僅適用於 JavaScript，而伺服器端資料庫提供對不同語言（PHP、Java、Python、NodeJS 和 Ruby）的支援。
  • 當您實作 getIpFn 功能時，如果無法從用戶的用戶端使用 IPv6 位址擷取功能，建議您先擷取 IPv6 位址，然後再遞補到 IPv4 位址。
  • 建議您整合用戶端和伺服器參數建立工具，以達到最佳效能。您可以使用用戶端參數建立工具來擷取 client_ip_address 並儲存至 Cookie。您稍後可以使用伺服器端參數建立工具，來從 Cookie 和要求中取得最佳可用 client_ip_address，並要求使用轉換 API 傳送至 Meta。
  • 建議您在透過轉換 API 將顧客資料參數傳送至 Meta 之前，僅在用戶端或伺服器端對參數進行一次正規化和雜湊處理。
  • 參數建立工具傳回的所有顧客資訊參數欄位的值皆區分大小寫。您可以透過轉換 API 將這些值以原樣傳回給 Meta，而無需進行任何標準化處理（例如轉換為小寫），因為 parambuilder SDK 已在程序中自動完成這些處理作業。

另請參閱