API đối tác

Yêu cầu về tích hợp

Tổng quan cấp cao

Là một phần của quá trình tích hợp này, bạn sẽ cần thực hiện những việc dưới đây

  1. Triển khai yêu cầu quảng cáo bổ sung cho vị trí danh mục bán kèm.
    1. Điều này bao gồm công việc định vị và hiển thị quảng cáo trên trang web của bạn, cũng như báo cáo số lần hiển thị và nhấp chuột
    2. Đơn đặt hàng cần được cung cấp cho CitrusAd như một phần của quá trình tích hợp tiêu chuẩn của bạn
  2. Nếu đồng bộ hóa ID danh mục với CitrusAd, bạn sẽ cần sử dụng API filterMapping để cung cấp các giá trị mà con người có thể đọc được cho lựa chọn danh mục giao diện người dùng
    1. Điều này chỉ áp dụng nếu bạn được tích hợp với ID danh mục thay vì tên. (chẳng hạn như khi bạn yêu cầu quảng cáo, bộ lọc của bạn sẽ category:123j-dsef-er thay vì category:Milk
  3. (Được khuyến nghị) - đồng bộ hóa ánh xạ bán kèm danh mục, để tự động phê duyệt và giảm tải quản lý chiến dịch.

Yêu cầu quảng cáo và tích hợp trang web

Yêu cầu quảng cáo

Vì bán kèm danh mục yêu cầu vị trí độc lập nên bạn sẽ cần tích hợp yêu cầu quảng cáo bổ sung cho mỗi loại quảng cáo mà bạn đang tích hợp bán kèm danh mục.

Định dạng yêu cầu của bạn phải khớp với yêu cầu quảng cáo danh mục bán kèm như được liệt kê bên dưới

Báo cáo số lần hiển thị và nhấp chuột

Khi đã tích hợp yêu cầu quảng cáo của mình, bạn cũng cần đảm bảo rằng bạn đang báo cáo chính xác số lần hiển thị và nhấp chuột cho từng quảng cáo được hiển thị. Đảm bảo bạn đọc Báo cáo số lần hiển thị và nhấp chuột.

Báo cáo đơn hàng

Nói chung, hầu hết các tích hợp đều báo cáo tất cả thông tin đặt hàng cho CitrusAd theo tích hợp tiêu chuẩn. Bạn cần đảm bảo rằng bạn đang báo cáo tất cả các đơn đặt hàng một cách chính xác cho CitrusAd theo Dữ liệu đơn hàng.

Ánh xạ bộ lọc

Điểm cuối ánh xạ bộ lọc có thể được sử dụng để ánh xạ ID danh mục của bạn tới các giá trị con người có thể đọc được. Điều này là bắt buộc nếu bạn đồng bộ hóa ID danh mục vì giao diện người dùng hiển thị các giá trị cho người dùng của bạn.

📘

Nếu bạn đồng bộ hóa các danh mục con người có thể đọc được trong danh mục sản phẩm của mình với CitrusAd thì bước này sẽ không bắt buộc.

Người dùng sẽ không hiểu category:12345-abcde là gì. API filterMapping có thể được sử dụng để ánh xạ giá trị tới tên danh mục có liên quan trên trang web của bạn, chẳng hạn như category:Pantry.

Không có phương pháp dựa trên tệp tin nào để đồng bộ hóa thông tin này, việc này phải được thực hiện thông qua API filterMapping.

🚧

Khi tạo các danh mục bổ sung trên trang web của mình, bạn sẽ cần đảm bảo API filterMapping được sử dụng để cập nhật các danh mục.

Ánh xạ bán kèm danh mục (khuyên dùng)

Chúng tôi đặc biệt khuyên bạn khi tích hợp loại vị trí này để cung cấp ánh xạ về những danh mục nào được phép nhắm mục tiêu lẫn nhau. Điều này có thể hợp lý hóa hoạt động của bạn sau công việc tích hợp ban đầu. Trải nghiệm của nhà quảng cáo được sắp xếp hợp lý để chỉ cho phép chọn những danh mục đã được phép chọn.

Ngoài ra, cũng có thể định cấu hình phê duyệt tự động cho các chiến dịch danh mục bán kèm khi ánh xạ bán kèm được cung cấp.

Phương pháp tích hợp

  • Bạn có thể sử dụng API crossSellCategory để tạo và quản lý ánh xạ theo yêu cầu.
  • Ngoài ra, bạn có thể cung cấp tệp TSV cho nhóm GCS do CitrusAd lưu trữ với định dạng được liệt kê bên dưới.

Tích hợp API

Bạn có thể xem tất cả thông tin bắt buộc trong danh sách API crossSellCategory.

Tích hợp tệp tin

Nếu tích hợp theo tệp tin, CitrusAd yêu cầu tệp tin cho mỗi danh mục, trong đó các danh mục được phép nhắm mục tiêu lẫn nhau.

Mỗi hàng trong tệp tin thể hiện một ánh xạ duy nhất của một danh mục và danh mục mà nó có thể nhắm mục tiêu. Mỗi ánh xạ là một hướng (nếu bạn đồng bộ hóa sô cô la -> sữa, các sản phẩm sô cô la có thể xuất hiện trên danh mục sữa. Nếu các sản phẩm sữa cần có khả năng xuất hiện trên danh mục sô cô la thì cần phải có hàng bổ sung).

Chúng tôi cần nguồn cấp dữ liệu ở định dạng TSV phù hợp với các thông số kỹ thuật dưới đây:

Tên cộtBắt buộcLoại dữ liệuMô tảVí dụ
categoryBắt buộcVăn bảnĐây là ID danh mục duy nhất xác định danh mục sản phẩm được quảng cáo.category:cookies
cross_category_idBắt buộcVăn bảnĐây là ID danh mục duy nhất xác định danh mục đủ điều kiện mà các sản phẩm thuộc category_id có thể được bán kèm.category:milk

Thông số kỹ thuật tập tin bổ sung như sau:

  • Chỉ các tệp tin TSV được hỗ trợ
  • TSV phải ở định dạng LF chứ không phải CRLF
  • TSV phải được mã hóa UTF-8, bất kỳ loại nào cũng sẽ khiến nguồn cấp dữ liệu không thành công
  • Quy ước đặt tên bắt buộc: ^cross_sell_category.*.tsv$

Một đoạn ví dụ trông giống như dưới đây:

Danh mụccross_category_id
category:cookiescategory:milk
category:cookiescategory:chocolate
category:milkcategory:cookies

Đoạn mã này ở trên cho phép danh mục bánh quy bán kèm vào danh mục sữa và sô cô la. Danh mục sữa có thể bán kèm vào danh mục bánh quy. Danh mục sô cô la có thể được nhắm mục tiêu, nhưng không thể nhắm mục tiêu bất kỳ danh mục nào khác.

❗️

Mỗi hàng là một sự kết hợp ánh xạ duy nhất

Bạn cần đồng bộ hóa các hàng duy nhất cho từng ánh xạ danh mục bán kèm duy nhất. Nếu cố gắng đồng bộ hóa nhiều cross_category_id trong một hàng, quá trình nhập dữ liệu tệp tin sẽ không thành công.

Quy trình kích hoạt tính năng

Khi bạn đã sẵn sàng bắt đầu đồng bộ hóa nguồn cấp dữ liệu cụm từ tìm kiếm được đề xuất của mình, CitrusAd sẽ định cấu hình cho bạn nhóm GCS để thả tệp của bạn vào.

Tính năng này chỉ được hỗ trợ trên nhóm GCS. Các nhóm bên ngoài như AWS/Azure/khác không được hỗ trợ.

Người quản lý Tài khoản Kỹ thuật của bạn sẽ có thể hướng dẫn bạn cách kích hoạt tính năng này. Vì nhóm vận hành nền tảng của CitrusAd bắt buộc phải thực hiện định cấu hình nên bạn vui lòng lưu ý rằng sẽ có thêm thời gian xử lý cho việc kích hoạt.