API đối tác
Hướng dẫn

Tạo quảng cáo sản phẩm sử dụng vị trí danh mục

Tài liệu này cung cấp hướng dẫn toàn diện về cách tạo quảng cáo sản phẩm dựa trên các danh mục được chỉ định. Mỗi yêu cầu API phải bao gồm thông tin chi tiết về ngữ cảnh, ví dụ:

  • customerId
  • sessionId
  • placement
  • catalogId
  • productFilters
  • Số lượng quảng cáo tối đa được hiển thị

Điều kiện tiên quyết

Bạn phải hoàn tất các bước sau trước khi bắt đầu yêu cầu quảng cáo sản phẩm cho vị trí tìm kiếm.

Thêm Danh mục Sản phẩm

Thêm sản phẩm của bạn vào catalogue và đồng bộ hóa các sản phẩm này với nền tảng Epsilon Retail Media.

Tạo Chiến dịch và Định cấu hình Danh mục

Đảm bảo rằng bạn đã tạo chiến dịch và định cấu hình các danh mục. Để biết thêm chi tiết, hãy tham khảo Bước 4: Định cấu hình Tiêu chí Mục tiêu.

Tìm nạp Khóa API và URL Cơ sở

  1. Bạn phải có mã khóa API hợp lệ. Để tìm nạp khóa API, hãy làm như sau:

    1. Đăng nhập vào tài khoản nhóm Phương tiện Bán lẻ của Epsilon của bạn.

    2. Điều hướng đến phía trên bên phải của trang và nhấp vào menu thả xuống.

    3. Chọn Cài đặt tích hợp, từ menu thả xuống.

    4. Nhấp vào tab Mã khóa API. Mã khóa API bí mật của bạn ban đầu bị ẩn. Để xem mã khóa, nhấp vào nút Hiển thị. Khi mã khóa hiển thị, hãy sao chép mã khóa API bí mật của bạn. Sử dụng mã khóa này để thực hiện lệnh gọi API.

  2. Bạn phải có URL cơ sở cho điểm cuối API. Ví dụ: https://staging-test.citrusad.com/v1/ads/generate HTTP/1.1. Kiểm tra với Người quản lý Tài khoản Kỹ thuật của bạn để biết URL cơ sở.

Tạo quảng cáo cho Vị trí Danh mục

Thực hiện các bước sau để tạo quảng cáo sản phẩm.

Yêu cầu HTTP

Điểm cuối: /v1/ads/generate

Phương pháp: POST

Tiêu đề:

  • chấp nhận: application/json
  • nội dung-loại: application/json
  • Ủy quyền: Cơ bản <API_KEY>

Yêu cầu Thông số

Nội dung yêu cầu phải là một đối tượng JSON chứa các trường sau. Để chỉ định vị trí danh mục, productFilters phải được đưa vào nội dung yêu cầu.

đối tượngtypeMô tả
customerIdchuỗi, bắt buộcMã nhận dạng duy nhất cho khách hàng. Mã này được cung cấp bởi nhà bán lẻ của bạn.
sessionIdchuỗi, bắt buộcMã nhận dạng duy nhất cho phiên. Mã này là bắt buộc để phân bổ và được cung cấp bởi nhà bán lẻ.
placementchuỗi, bắt buộcNgữ cảnh trong đó quảng cáo được hiển thị (ví dụ: "danh mục"). Đặt thành "danh mục" cho các vị trí danh mục.
catalogIdchuỗi, bắt buộcMã nhận dạng duy nhất cho catalogue sản phẩm mà sản phẩm đang được lọc. Bạn có thể tải ID catalogue từ giao diện người dùng Retail Media của Epsilon hoặc từ nhà bán lẻ.
productFiltersmảng, bắt buộcMột mảng chứa các bộ lọc danh mục.
maxNumberOfAdssố nguyên, bắt buộcSố lượng quảng cáo tối đa được hiển thị.
optionsđối tượng, tùy chọnCác tùy chọn bổ sung như chế độ lọc AndOr. Nếu được chỉ định, hệ thống sẽ sử dụng cả điều kiện "AND" và "OR" để thu hẹp kết quả tìm kiếm

Yêu cầu Ví dụ

Yêu cầu JSON được sử dụng để chỉ định vị trí danh mục cho các quảng cáo liên quan đến danh mục "Tủ ly/Đồ ăn nhẹ". Yêu cầu bao gồm ID khách hàng, ID phiên, ID danh mục, tùy chọn lọc và đặt số lượng quảng cáo tối đa thành 3.

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "placement": "category",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Cupboard/Snacks"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

Tạo quảng cáo cho các vị trí danh mục bán kèm

Vị trí danh mục bán kèm tương tự như vị trí danh mục thông thường nhưng được sử dụng cụ thể để nhắm mục tiêu quảng cáo cho các sản phẩm bán kèm. Trong kịch bản bán kèm, mục tiêu của bạn là đề xuất các sản phẩm bổ sung dựa trên danh mục hiện tại mà người dùng đang duyệt.

Bạn nên chỉ định chính xác danh mục bạn muốn tạo quảng cáo. Danh mục này thường là danh mục được hiển thị trên trang hiện tại mà người dùng đang duyệt.

Yêu cầu Ví dụ

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9", 
    "placement": "category-cross-sell",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Cupboard/Snacks"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

Hợp nhất nhắm mục tiêu theo danh mục không phải trả tiền và bán kèm

Nếu bạn muốn kết hợp quảng cáo miễn phí (quảng cáo phù hợp với danh mục đang xem) và quảng cáo bán kèm (quảng cáo cho danh mục hoặc sản phẩm có liên quan) vào một vị trí quảng cáo duy nhất, bạn sẽ cần tự mình quản lý sự kết hợp này. Để làm được, bạn phải viết logic sao cho có thể hợp nhất và hiển thị cả hai hình thức quảng cáo cùng nhau.

Phương pháp tốt nhất:

  • Quảng cáo không phải trả tiền trước tiên: Hiển thị quảng cáo có liên quan đến danh mục hiện tại (quảng cáo không phải trả tiền) trước tiên.
  • Quảng cáo bán kèm thứ hai: Sau đó, hiển thị quảng cáo cho các danh mục hoặc sản phẩm có liên quan (quảng cáo bán kèm) sau quảng cáo không phải trả tiền.

Các phương pháp tốt nhất để nhắm mục tiêu quảng cáo dựa trên danh mục

Khi người dùng điều hướng qua các danh mục khác nhau, điều quan trọng là phải cập nhật các lệnh gọi API của bạn để phản ánh danh mục hiện tại đang được xem. Điều này đảm bảo rằng quảng cáo được hiển thị vẫn phù hợp với ngữ cảnh duyệt web của người dùng.

Bạn nên gửi danh mục cụ thể nhất (cấp thấp nhất) trong yêu cầu quảng cáo của mình tới nền tảng Phương tiện truyền thông Bán lẻ Epsilon. Nhắm mục tiêu cấp danh mục sâu nhất sẽ cung cấp quảng cáo được nhắm mục tiêu chính xác và phù hợp hơn cho người dùng.

Tình huống ví dụ

Người dùng bắt đầu duyệt trong một danh mục chung và sau đó điều hướng đến một danh mục con cụ thể hơn.

Lệnh gọi API ban đầu

Khi người dùng đang duyệt danh mục "Nhà":

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "placement": "category",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Home"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

Cập nhật lệnh gọi API

Khi người dùng điều hướng đến danh mục con "Nhà > Nội thất":

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "placement": "category",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Home/Furniture"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

Lệnh gọi API cuối cùng

Khi người dùng điều hướng thêm đến danh mục phụ "Nhà > Nội thất > Ghế”:

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "placement": "category",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Home/Furniture/Chairs"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

Bằng cách cập nhật lệnh gọi API để phản ánh danh mục cụ thể nhất mà người dùng đang duyệt, bạn đảm bảo rằng quảng cáo được cấp phát có mức độ liên quan cao. Thay vì chỉ định một yêu cầu được xâu chuỗi trên nhiều cấp danh mục (L1 + L2 + L3), bạn nên chỉ định cấp danh mục sâu nhất (L3).

Các bước tiếp theo

Cập nhật 5 tháng trước