API đối tác

Yêu cầu quảng cáo biểu ngữ

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

Vì quảng cáo sản phẩm và biểu ngữ được tạo ra trên cùng một điểm cuối, nên nếu ngữ cảnh của vị trí quảng cáo là giống nhau thì bạn có thể yêu cầu cấp phát quảng cáo sản phẩm trong cùng một yêu cầu giống như của biểu ngữ.

Bạn có thể thiết lập số lượng quảng cáo sản phẩm mà bạn nhận được bằng cách xác định thông số maxNumberOfAds . Bạn có thể thiết lập số lượng quảng cáo biểu ngữ mà bạn nhận được bằng thuộc tính maxNumberOfAds trên số slotID không trùng lặp

Tất cả các yêu cầu quảng cáo biểu ngữ đều cần có contentStandardId và bannerSlots mà bạn đang yêu cầu quảng cáo. Ngoài ra, yêu cầu biểu ngữ của bạn cũng phải có customerId,sessionId,placement và catalogId.

📘

Bạn có thể nhận thấy một số thay đổi ở đây!

Chúng tôi sắp thay đổi một chút trong cách bạn yêu cầu quảng cáo biểu ngữ từ CitrusAd. Nếu đã tích hợp, bạn có thể yêu cầu bằng một thuộc tính có tên là bannerSlotIds. Chúng tôi đã thay thế chức năng này bằng chức năng mới là bannerSlots . Nếu bạn muốn xem lại cách yêu cầu quảng cáo với thuộc tính bannerSlotIds , vui lòng điều hướng đến cuối trang này.

Chức năng bannerSlots khả năng được triển khai vào tháng 9 năm 2022.

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"
 							 },
    "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
    "bannerSlots": [
           {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 1
    },
    {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 2
    }
    ],           
    "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. Sau đây là ví dụ về nơi bạn sẽ gửi các bộ lọc danh mục đế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": "category",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Cupboard/Snacks"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
    "bannerSlots": [
           {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 1
    },
    {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 2
    }
    ],            
    "maxNumberOfAds": 3
}

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

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"
 							 },
    "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
    "bannerSlots": [
           {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 1
    },
    {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 2
    }
    ],            
    "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 để đảm bảo CitrusAd chỉ cấp phát quảng cáo trong phạm vi yêu cầu, như ví dụ 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": "home",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 []
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
    "bannerSlots": [
           {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 1
    },
    {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 2
    }
    ], 
    "maxNumberOfAds": 3
}

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

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.

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"
 							 },
    "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
    "bannerSlots": [
           {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 1
    },
    {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 2
    }
    ], 
    "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, như ví dụ dưới đâ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",
    "productFilters": [
     	 ["category:Cupboard"],["dietary:Gluten-free"],["location:Westenbury"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
    "bannerSlots": [
           {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 1
    },
    {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 2
    }
    ], 
    "maxNumberOfAds": 3
}

Sử dụng thông số bannerSlotIds (kế thừa)

Nếu đã tích hợp, bạn có thể yêu cầu quảng cáo bằng bannerSlotIds thay vì bannerSlots. Đây là một mảng chuỗi trong đó bạn sẽ chỉ định các vùng biểu ngữ mà bạn yêu cầu quảng cáo. Chúng tôi đã cải tiến để bạn có thể yêu cầu nhiều quảng cáo cho một vùng biểu ngữ. Nếu quan tâm, bạn sẽ cần tăng cường tích hợp theo bannerSlots phương pháp được nêu ở trê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",
    "productFilters": [
     	 ["category:Cupboard"],["dietary:Gluten-free"],["location:Westenbury"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
    "bannerSlotIds": [
        "<SLOT_ID>","<SLOT_ID>"
    ], 
    "maxNumberOfAds": 3
}

Phản hồi quảng cáo biểu ngữ

Mọi phản hồi đều tuân theo cùng một định dạng JSON. Khi bạn yêu cầu quảng cáo sản phẩm, mảng ads sẽ được điền nội dung theo ví dụ bên dưới. Các biểu ngữ điền nội dung vào mảng banners , vì vậy nội dung chỉ được trả về cho các vùng biểu ngữ có quảng cáo.

{
    "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
        }
    ],
    "banners": [
				{
            "id": "banner_XeemTeq59HapGSp4vccOYfBq_yvc3zMzNjM2",
            "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
            "slotId": "<SLOT_ID>",
            "imageUrl": "https://cdn.flavedo.io/s/-oW-C3cEViSSO2krWkwOBUXOhvUdhHOySx-YQLGZ1lA=",
            "linkUrl": "https://www.retailer.com/link",
            "altText": "Your local ice cream",
            "text": "",
            "gtins": [
                "7733628",
                "7714107",
                "7163379",
                "7733636",
                "7733657"
            ],
            "expiry": "2021-05-17T01:49:17.75503253Z",
            "tags": {},
            "position": 1
        },
				{
            "id": "banner_A0KA6mNmFs6sZPb_FvwWe5k6x6c3NzMzNjM3",
            "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
            "slotId": "<SLOT_ID>",
            "imageUrl": "https://cdn.flavedo.io/s/-oW-dfsgrerWkwOBUXOhvUdhHOySx-YQLreGZ1lw=",
            "linkUrl": "https://www.retailer.com/link",
            "altText": "Advertisement for pet food.",
            "text": "",
            "gtins": [
                "16309011",
                "57312011",
                "65250011"
            ],
            "expiry": "2021-05-17T01:49:17.75503253Z",
            "tags": {},
            "position": 2
        }
				],
    "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. 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.

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": [
				{
            "id": "banner_XeemTeq59HapGSp4vccOYfBq_yvc3zMzNjM2",
            "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
            "slotId": "<SLOT_ID>",
            "sellerId": "43d-w4-2wcr4",
            "imageUrl": "https://cdn.flavedo.io/s/-oW-C3cEViSSO2krWkwOBUXOhvUdhHOySx-YQLGZ1lA=",
            "linkUrl": "https://www.retailer.com/link",
            "altText": "Your local ice cream",
            "text": "",
            "gtins": [
                "7733628",
                "7714107",
                "7163379",
                "7733636",
                "7733657"
            ],
            "expiry": "2021-05-17T01:49:17.75503253Z",
            "tags": {},
            "position": 1
        },
				{
            "id": "banner_A0KA6mNmFs6sZPb_FvwWe5k6x6c3NzMzNjM3",
            "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
            "slotId": "<SLOT_ID>",
            "imageUrl": "https://cdn.flavedo.io/s/-oW-dfsgrerWkwOBUXOhvUdhHOySx-YQLreGZ1lw=",
            "linkUrl": "https://www.retailer.com/link",
            "altText": "Advertisement for pet food.",
            "text": "",
            "gtins": [
                "16309011",
                "57312011",
                "65250011"
            ],
            "expiry": "2021-05-17T01:49:17.75503253Z",
            "tags": {},
            "position": 2
        }
				],
    "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 chi tiết.

Thẻ theo dõi của bên thứ ba

Đối với quảng cáo biểu ngữ, CitrusAd hỗ trợ chuyển thẻ theo dõi của bên thứ ba cho nhà bán lẻ. Các thẻ này được nhà quảng cáo sử dụng để xác minh hiệu suất của họ bởi một bên thứ ba đáng tin cậy.

CitrusAd hỗ trợ các thẻ theo dõi dưới đây:

  • DoubleVerify
  • Lượt nhấp DCM
  • Lần hiển thị DCM
  • IAS

Nếu một chiến dịch có thẻ theo dõi đã được cấu hình, thì chiến dịch đó sẽ hiển thị dưới dạng trường có liên quan trong đối tượng tags ở bên dưới. Xin lưu ý, nếu một chiến dịch không có thẻ đã được định cấu hình, thì đối tượng tags sẽ vẫn trống.

{
    "ads": [],
    "banners": [
				{
            "id": "banner_XeemTeq59HapGSp4vccOYfBq_yvc3zMzNjM2",
            "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
            "slotId": "<SLOT_ID>",
            "imageUrl": "https://cdn.flavedo.io/s/-oW-C3cEViSSO2krWkwOBUXOhvUdhHOySx-YQLGZ1lA=",
            "linkUrl": "https://www.retailer.com/link",
            "altText": "Your local ice cream",
            "text": "",
            "gtins": [
                "7733628",
                "7714107",
                "7163379",
                "7733636",
                "7733657"
            ],
            "expiry": "2021-05-17T01:49:17.75503253Z",
            "tags": {
                "dv": "<script src=\"https://cdn.doubleverify.com/dvtp_src.js?ctx=919421&cmp=1074060503&sid=1073907024&plc=1075810393&adsrv=115&btreg=&btadsrv=&crt=&tagtype=&dvtagver=6.1.src\" type=\"text/javascript\"></script>",
                "dcmClick": "<script ..../>",
                "dcmImpression": "<script.... />",
                "ias": "<script.... />"            }
        }
				],
    "products": [],
     "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0="
}

Do CitrusAd là dịch vụ tích hợp máy chủ với máy chủ, nên thẻ theo dõi của bên thứ ba yêu cầu nhà bán lẻ phát triển thêm. Hãy liên hệ với người quản lý tài khoản kỹ thuật của bạn nếu bạn muốn sử dụng tính năng này.