API Chuyển đổi

Thư viện công cụ tạo thông số

Meta đã cung cấp danh sách SDK thư viện cho cả phía máy khách (JavaScript) và phía máy chủ (PHP, Java, Python, NodeJS, Ruby). Những thư viện SDK này nhằm hỗ trợ nhà phát triển cải thiện chất lượng của thông số sự kiện API Chuyển đổi (ví dụ: fbc, fbp, client_ip_address cũng như các thông số về thông tin khách hàng khác như em và ph), đồng thời hỗ trợ nhà quảng cáo tuân thủ cách làm tốt nhất của Meta khi tạo các thông số này.

Tài liệu này bao gồm tổng quan về cả 2 thư viện, hướng dẫn chọn thư viện phù hợp để sử dụng và các trường hợp sử dụng mẫu.

Tổng quan về thư viện

Phía máy khách: Thư viện và các sự kiện hoạt động ở phần front-end trên trình duyệt. Các thư viện này được triển khai bằng JavaScript. Nhà phát triển có thể tích hợp thư viện trực tiếp vào trang web của mình.

Phía máy chủ: Thư viện và các sự kiện hoạt động ở phần back-end phía máy chủ. Tùy thuộc vào ngôn ngữ mà back-end sử dụng, Meta cung cấp các thư viện bằng nhiều ngôn ngữ khác nhau (PHP, Java, Python, NodeJS và Ruby).

Chọn thư viện

Tất cả thư viện đều có thể hoạt động độc lập. Để khai thác tối đa tiềm năng cho bạn hoặc khách hàng của bạn, hãy xem xét các đề xuất tại đây.

Parambuilder tuân thủ những cách làm tốt nhất trong tài liệu dành cho nhà phát triển của Meta. Thư viện này được triển khai ở phía máy khách (JavaScript) và phía máy chủ (PHP, Java, Python, NodeJS, Ruby).

Ví ụ về trường hợp sử dụng để tham khảo

Bạn nên cân nhắc các trường hợp sử dụng sau đây khi tạo giải pháp.

Đề xuất: Công cụ tạo thông số phía máy chủ + Công cụ tạo thông số phía máy khách

Khi ghép nối công cụ tạo thông số phía máy chủ với công cụ tạo thông số phía máy khách, bạn có thể khai thác tối đa khả năng đạt tỷ lệ khớp IPv6 và fbc cao.

Để thực hiện, bạn cần tích hợp 2 thư viện với nhau: công cụ tạo thông số phía máy chủ và công cụ tạo thông số phía máy khách.




Ví dụ về quy trình

  • Ứng dụng phía máy khách của nhà quảng cáo tải công cụ tạo thông số phía máy khách và gọi API processAndCollectAllParams được cung cấp bằng con trỏ hàm getIpFn.
  • Hệ thống sẽ gọi getIpFn đã cung cấp và tìm nạp IPv6 từ điểm cuối do nhà quảng cáo đặt cấu hình, tùy thuộc vào cách triển khai getIpFn thực tế.
  • IPv6 sẽ được trả về từ điểm cuối do nhà quảng cáo đặt cấu hình và được chuyển lại cho công cụ tạo thông số phía máy khách từ giá trị trả về của getIpFn. IPv6 đã truy xuất sẽ được lưu trữ trong cookie có khóa _fbi để truy xuất sau.
  • Ở phía máy khách, hãy bắt đầu hoạt động giao tiếp thông thường với máy chủ phụ trợ bằng cách sử dụng API tìm nạp (hoặc hoạt động giao tiếp khác giữa máy khách và máy chủ) với cookie của bên thứ nhất.
  • Ở phía máy chủ, hãy tích hợp thư viện phía máy chủ dựa trên ngôn ngữ bạn chọn trong điểm cuối tiếp nhận (ví dụ: ExampleController) và gọi API processRequest được cung cấp để xử lý yêu cầu.
  • API processRequest sẽ trả về danh sách cookie được đề xuất cập nhật ở phía máy khách.
  • Đặt cookie được đề xuất trong tiêu đề phản hồi để hướng dẫn trình duyệt máy khách lưu trữ cookie đó.
  • Gọi nhiều API được cung cấp như getFbc(), getFbp(), getClientIpAddress() và getNormalizedAndHashedPII().
  • SDK trả về nhiều giá trị khác nhau như fbc, fbp, client_ip_address, email và số điện thoại.
  • Gửi các giá trị đã truy xuất này trở lại Meta thông qua API Chuyển đổi.
// 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)
....

Chỉ ParamBuilder phía máy chủ

Vui lòng xem hướng dẫn làm quen với công cụ tạo thông số phía máy chủ hoặc các file README được liên kết trong đó để xem một số ví dụ chi tiết.

Ví dụ về quy trình

  • Tại điểm cuối của máy chủ, nhập thư viện ParamBuilder dựa trên ngôn ngữ và khung triển khai tương ứng.
  • Gọi hàm paramBuilder.processRequest để nhận danh sách các cookie được cập nhật theo đề xuất.
  • Thiết lập cookie cho phản hồi của bạn.
  • Thiết lập fbc, fbp, client_ip_address và thông tin cá nhân khác như email và số điện thoại cho lệnh gọi API Chuyển đổi bằng cách sử dụng paramBuilder.getFbc(), paramBuilder.getFbp(), paramBuilder.getClientIpAddress() và paramBuilder.getNormalizedAndHashedPII() tương ứng

Chỉ ParamBuilder phía máy khách

Vui lòng xem hướng dẫn làm quen với công cụ tạo thông số phía máy khách hoặc các file README được liên kết trong đó để xem một số ví dụ chi tiết.

Ví dụ về quy trình

  • Khi tải trang đích, hãy gọi clientParamBuilder.processAndCollectAllParams(url, getIpFnl).
  • Sau đó, yêu cầu được gửi đến phía máy chủ. Sau đó, máy chủ có thể đọc fbc, fbp và client_ip_address từ cookie bằng cách dùng khóa _fbc, _fbp và _fbi tương ứng.
    • Lưu ý: Nếu URL trang đích không chứa fbclid, thông số fbc có thể bị thiếu. Điều này là bình thường.

Liên kết hữu ích

Liên kết Github chính

Hãy đảm bảo bạn đang sử dụng phiên bản mới nhất.

Cách làm tốt nhất

  • Đảm bảo bạn lưu cookie _fbp và _fbc càng sớm càng tốt trong hành trình của khách hàng trên trang web của bạn. Tốt nhất là bạn nên truy xuất cookie _fbp và _fbc khi tải trang đích. Bạn không nên chỉ truy xuất các cookie này từ sự kiện ở phần dưới phễu hoặc khi một số sự kiện nhất định được kích hoạt.
  • Không ghi đè hoặc điều chỉnh cookie _fbc hoặc _fbp. Cookie _fbc phân biệt chữ hoa chữ thường; đừng chuẩn hóa hoặc định dạng lại _fbc thành chữ thường.
  • Đảm bảo các thư viện áp dụng trên tất cả các nền tảng, chẳng hạn như thiết bị di động, máy tính để bàn, trình duyệt và các tên miền mà bạn muốn theo dõi.
  • Thư viện phía máy chủ dành cho phía máy chủ và thư viện phía máy khách dành cho phía trình duyệt máy khách. Nhà phát triển có thể tích hợp trực tiếp thư viện phía máy khách vào trang web của họ, còn thư viện phía máy chủ được gọi ở phía máy chủ phụ trợ. Lưu ý rằng thư viện phía máy khách chỉ hỗ trợ trong JavaScript, còn thư viện phía máy chủ hỗ trợ nhiều ngôn ngữ khác nhau (PHP, Java, Python, NodeJS và Ruby).
  • Khi triển khai chức năng getIpFn, bạn nên truy xuất địa chỉ IPv6 trước, sau đó chuyển về địa chỉ IPv4 nếu không thể truy xuất địa chỉ IPv6 từ phía máy khách của người dùng.
  • Bạn nên tích hợp cả công cụ tạo thông số phía máy khách và phía máy chủ để đạt hiệu quả tối ưu. Bạn có thể sử dụng công cụ tạo thông số phía máy khách để truy xuất client_ip_address và lưu vào cookie. Sau này, bạn có thể sử dụng công cụ tạo thông số phía máy chủ để lấy client_ip_address tốt nhất hiện có từ cả cookie và yêu cầu để gửi đến Meta bằng API Chuyển đổi.
  • Bạn chỉ nên chuẩn hóa và mã hóa dạng băm cho các thông số về thông tin khách hàng một lần ở phía máy khách hoặc phía máy chủ trước khi gửi cho Meta thông qua API Chuyển đổi.
  • Tất cả các giá trị của trường thông số thông tin về khách hàng do công cụ tạo thông số trả về đều phân biệt chữ hoa chữ thường. Bạn có thể gửi các giá trị này trở lại Meta thông qua API Chuyển đổi mà không cần chuẩn hóa (ví dụ: chữ thường) vì SDK công cụ tạo thông số đã tự động thực hiện việc này trong quy trình.

Xem thêm