API đối tác

Danh mục và sản phẩm

Để tích hợp với CitrusAd, bạn sẽ cần ít nhất một danh mục sản phẩm.

Danh mục là gì?

Danh mục là một nhóm các sản phẩm và các thuộc tính của chúng, thường dùng để nhóm tất cả các sản phẩm trên trang web của nhà tích hợp thành một danh mục duy nhất.

Danh mục được nhà quảng cáo chọn trong quá trình tạo chiến dịch và chiến dịch của họ sẽ chỉ chạy trong danh mục sản phẩm đã chọn của họ. Thông thường, tất cả các sản phẩm được nhóm lại thành một danh mục duy nhất cho một nhà tích hợp, giúp việc lựa chọn trở nên đơn giản cho các nhà quảng cáo.

Bạn có thể sử dụng việc tạo nhiều danh mục để phân đoạn tình trạng còn hàng của sản phẩm ở các nhà bán lẻ hoặc quốc gia khác nhau cho mục đích nhắm mục tiêu theo chiến dịch.

📘

Nếu bạn muốn tạo nhiều danh mục, hãy liên hệ với người quản lý tài khoản kỹ thuật của bạn để thảo luận về các phương pháp tốt nhất, vì có thể có những cách thức triển khai chức năng nhắm mục tiêu tốt hơn.

🚧

Nếu bạn đang tích hợp vào một không gian tên mạng, bạn nên tạo một danh mục đơn.

Sản phẩm là gì?

Sản phẩm là GTIN lẻ trên trang web của nhà tích hợp. Các sản phẩm đồng bộ hóa với CitrusAd được đồng bộ hóa với các giá trị và thuộc tính nhận dạng riêng. Sản phẩm phải đại diện cho từng GTIN/SKU trong danh mục sản phẩm hiện tại của bạn.

Sản phẩm được các nhà quảng cáo lựa chọn trong quá trình tạo chiến dịch, chỉ các sản phẩm có liên quan đến danh mục mà nhà quảng cáo đã chọn được hiển thị để lựa chọn. Không nên dùng sản phẩm để đại diện cho bất kỳ GTIN sản phẩm đơn nào. Các biến thể của cùng một sản phẩm nên được niêm yết dưới dạng các sản phẩm khác nhau, ví dụ: Các biến thể 200ml, 600ml và 2L của cùng một sản phẩm đồ uống sẽ được coi là ba sản phẩm khác nhau trong CitrusAd, phù hợp với các phương pháp tốt nhất của nhà tích hợp hiện có.

Giải thích bộ lọc sản phẩm

Các bộ lọc sản phẩm chủ yếu được dùng để tạo quảng cáo, bên cạnh việc chứa các thuộc tính như imageUrl và tên. Khi yêu cầu quảng cáo từ CitrusAd, bạn sẽ gửi ngữ cảnh chứa thông tin trang có liên quan để đảm bảo quảng cáo có liên quan được cấp phát đến từng trang.

Cấu trúc của các bộ lọc phụ thuộc vào nhà tích hợp, nhưng điều quan trọng nhất cần xem xét là các bộ lọc sản phẩm này sẽ được gửi trong ngữ cảnh tạo quảng cáo của bạn. Bộ lọc sản phẩm phải khớp chính xác với những gì được yêu cầu trong quá trình tạo quảng cáo.

Một ngữ cảnh mẫu có chứa productFilters được mô tả bên dưới:

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": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "productFilters": [
         ["category:Cupboard"],["dietary:Gluten-free"]
    ],
    "options": {
                             "filterMode": "AndOr"
                             },
    "maxNumberOfAds": 3
}

Ngữ cảnh này sẽ chỉ trả lại quảng cáo cho các sản phẩm có chứa tất cả các bộ lọc trong mảng có liên quan.

📘

Nếu bạn muốn sử dụng các giá trị giá thầu tối thiểu trong danh mục, hãy đảm bảo các danh mục của bạn thân thiện với người dùng và dễ dàng cho các nhà quảng cáo tạo chiến dịch, ví dụ: danh mục:Bàn phím sẽ dễ hiểu hơn danh mục:12.

Cung cấp hình ảnh và tên sản phẩm

CitrusAd cần thông tin về hình ảnh và tên sản phẩm để làm cho chúng có thể tìm kiếm được khi tạo chiến dịch trong cổng thông tin CitrusAd. Các giá trị này có thể được gửi đến thẻ bên trong CitrusAd được định dạng như ví dụ sau:

POST $BASE_URL/v1/catalog-products?teamId=<YOUR_TEAM_ID> HTTP/1.1 
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "catalogProducts": [
        {
            "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
            "gtin": "23556578965543",
            "inventory": 50,
            "price": "19.99",
            "tags": [
                 ""imageurl:https://your.image.host.com/image.jpg","name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
            ],
            "filters": [
                 "category:Health&Beauty","category:Grocery","Brand:Covergirl","Special_Flag:0"
            ]
        }
    ]
}

Chúng được nhìn thấy trong các khu vực khác nhau của cổng CitrusAd bao gồm lựa chọn sản phẩm, như ví dụ bên dưới:

1581

Hình ảnh tham khảo