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ínhbannerSlotIds
, 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",
"dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
"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",
"dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
"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",
"dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
"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",
"dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
"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",
"dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
"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",
"dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
"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",
"dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
"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.