API đối tác

Yêu cầu quảng cáo sản phẩm

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

Tất cả các yêu cầu quảng cáo sản phẩm đều cần có placement và catalogIdcủa ngữ cảnh, cũng như maxNumberOfAds mà bạn muốn hiển thị cho khách hàng. Ngoài ra, yêu cầu của bạn nên bao gồm customerId và sessionId.

Vị trí tìm kiếm

Dễ đưa ra yêu cầu nhất thường là các vị trí tìm kiếm. Các vị trí này bắt buộc phải ghi rõ searchTerm trong yêu cầu, như trong ví dụ sau đây:

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",
    "options": {
   						 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3    
}

Vị trí danh mục

Các vị trí danh mục bắt buộc phải ghi rõ productFilters trong yêu cầu. Ví dụ dưới đây cho thấy nơi bạn sẽ gửi các bộ lọc danh mục:

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

Khi sử dụng danh mục bổ sung, bạn cần cập nhật lệnh gọi API của mình cho phù hợp.

📘

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

Cách tốt nhất là gửi cấp danh mục thấp nhất trong yêu cầu quảng cáo đến CitruSad khi khách hàng duyệt xem ở các danh mục sâu hơn.

Thay vì chỉ định yêu cầu theo chuỗi ở cấp 3 của L1 + L2 + L3, bạn chỉ cần chỉ định danh mục L3.

Vị trí danh mục bán kèm

Các vị trí danh mục bán kèm có yêu cầu rất giống với các vị trí danh mục. Bạn nên xác định danh mục chính xác mà bạn đang yêu cầu cấp phát quảng cáo. Đây thường là trang mà bạn đang truy cập. Xác định danh mục trong productFilters của yêu cầu. Ví dụ dưới đây cho thấy nơi bạn sẽ gửi các bộ lọc danh mục:

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

Khi sử dụng danh mục bổ sung, bạn cần cập nhật lệnh gọi API của mình cho phù hợp.

📘

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 đang tìm cách hợp nhất yêu cầu quảng cáo danh mục không phải trả tiền và bán chéo vào một vị trí duy nhất, bạn sẽ cần triển khai logic hợp nhất và phân phối cho khách hàng của mình. Đây là trách nhiệm của bên tích hợp, mặc dù CitrusAd sẵn lòng tư vấn.

Tóm lại, chúng tôi khuyên bạn nên hiển thị quảng cáo danh mục không phải trả tiền cũng như quảng cáo bán kèm vị trí và danh mục sau các vị trí không phải trả tiền.

Vị trí đối sánh rộng

Các vị trí rộng như trang chủ hoặc trang thanh toán không yêu cầu phải ghi rõ bất kỳ productFilters nào trong yêu cầu. Bất kỳ bộ lọc nào mà nhà bán lẻ muốn ghi rõ (về ưu đãi, mới v.v.) đều có thể được ghi rõ trong productFilters của ngữ cảnh để đảm bảo CitruSad chỉ phân phối quảng cáo trong yêu cầu.

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": "home",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 []
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

Các tính năng nâng cao đối với yêu cầu

Đối với vị trí tìm kiếm, danh mục và vị trí đối sánh rộng, bạn nên xem xét các tính năng nâng cao bên dưới để tối ưu trải nghiệm người dùng.

Yêu cầu phân trang

Khi tạo quảng cáo sản phẩm, bạn sẽ nhận được memoryToken có thể gửi trong các yêu cầu theo sau để loại trừ các quảng cáo đã được cấp phát. Sau đó, bạn có thể gửi cái này memoryToken trong yêu cầu quảng cáo tiếp theo và CitrusAd sẽ loại trừ mọi quảng cáo đã phân phát trước đó cho cùng một ngữ cảnh khỏi phản hồi quảng cáo của chúng tôi.

Vui lòng xem phần Phân trang trước khi thực hiện.

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",
    "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0=",
    "options": {
                         "filterMode": "AndOr"
                             },
    "maxNumberOfAds": 3    
}

Tìm kiếm đã lọc

Nếu khách hàng của bạn lọc tìm kiếm của họ, bạn có thể mở rộng ngữ cảnh của mình để cung cấp productFilters. Sau đây là ví dụ về trường hợp khách hàng đang lọc theo danh mục "Tủ" và hạn chế trong chế độ ăn uống là "Không có gluten". Có thể áp dụng cùng nguyên tắc này cho bất kỳ danh mục hoặc vị trí trùng khớp rộng nào.

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
}

Lọc theo vị trí

Nếu bạn đang đồng bộ hóa các bộ lọc vị trí trong danh mục của mình, bạn có thể mở rộng ngữ cảnh để cung cấp vị trí cửa hàng của khách hàng trong productFilters:

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"],["location:Westenbury"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

Phản hồi quảng cáo sản phẩm

Mọi phản hồi quảng cáo sản phẩm đều tuân theo cùng một định dạng JSON. Quảng cáo sản phẩm được trả lại trong mảng ads , như ví dụ dưới đây:

{
    "ads": [
        {
            "id": "display_QqHaKRrKlFm1Wxr9c_DXJN4HSE3NzMzNjM2",
            "gtin": "7733636",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400902957Z",
            "position": 1
        },
        {
            "id": "display_NzsHqP0_iQedlo9VnrO2vqkwi_k3NzMzNjI4",
            "gtin": "7733628",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400908257Z",
            "position": 2
        },
        {
            "id": "display_xNeShqidaMuEqiJ0zNdt-Gzygjs3NzE0MTA3",
            "gtin": "7714107",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400912929Z",
            "position": 3
        },
        {
            "id": "display_3rGiryPskhQusmsf43nghbQwnqo3NzMzNjU3",
            "gtin": "7733657",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400917769Z",
            "position": 4
        }
    ],
    "banners": [],
    "products": [],
    "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0="
}

Mã id trường là ID quảng cáo của bạn dùng trong các báo cáo số lượt hiển thị và nhấp chuột. Mã position trường xác định vị trí trong tải trọng CitrusAd. Vui lòng xem danh sách tham chiếu chi tiết để biết thêm thông tin về từng chuỗi.

📘

Bạn nên đọc và chú ý đến trường position để đảm bảo vị trí thuê cố định hiển thị đúng cách.

sellerId cho sàn thương mại

Nếu đang hỗ trợ người bán trên thị trường trong những bước đầu tiên, bạn có thể thấy thêm sellerId cho mỗi quảng cáo trong phản hồi. Trường hợp này sẽ chỉ xảy ra nếu nhóm sở hữu chiến dịch đang được phân phát có ID người bán được định cấu hình trong giao diện người dùng. Dưới đây là ví dụ của một quảng cáo có sellerId và một quảng cáo không có.

{
    "ads": [
        {
            "id": "display_QqHaKRrKlFm1Wxr9c_DXJN4HSE3NzMzNjM2",
            "gtin": "7733636",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400902957Z",
            "position": 1
        },
        {
            "id": "display_NzsHqP0_iQedlo9VnrO2vqkwi_k3NzMzNjI4",
            "gtin": "7733628",
            "sellerId": "2834-ascre-2wcr4",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400908257Z",
            "position": 2
        }
    ],
    "banners": [],
    "products": [],
    "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0="
}

📘

Nếu bạn cần biết thông tin về các chuỗi trong phần này, vui lòng truy cập trang Danh sách tham chiếu cho quảng cáo sản phẩm.