Yêu cầu quảng cáo
Quảng cáo biểu ngữ x được tạo trên điểm cuối /bannerx . Tất cả các yêu cầu biểu ngữ x đều cần có contentStandardId và bannerSlotIds 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.
Khi yêu cầu quảng cáo biểu ngữ x, bạn có thể chỉ định số lượng biểu ngữ tối đa bạn muốn nhận được trên mỗi vùng biểu ngữ. Bạn có thể kiểm soát số lượng này bằng maxNumberOfAds .
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/bannerx 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": "c61941e2-1435-460b-9d2b-5d838e3dba9c",
"bannerSlotIds": [
{
"slotId": "<SLOT_ID>",
"maxNumberOfAds": 1
},
{
"slotId": "<SLOT_ID>",
"maxNumberOfAds": 2
}
]
}
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/bannerx 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",
"bannerSlotIds": [
{
"slotId": "<SLOT_ID>",
"maxNumberOfAds": 1
},
{
"slotId": "<SLOT_ID>",
"maxNumberOfAds": 2
}
}
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/bannerx 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",
"bannerSlotIds": [
{
"slotId": "<SLOT_ID>",
"maxNumberOfAds": 1
},
{
"slotId": "<SLOT_ID>",
"maxNumberOfAds": 2
}
}
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/bannerx 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",
"bannerSlotIds": [
{
"slotId": "<SLOT_ID>",
"maxNumberOfAds": 1
},
{
"slotId": "<SLOT_ID>",
"maxNumberOfAds": 2
}
}
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/bannerx 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": [
{
"slotId": "<SLOT_ID>",
"maxNumberOfAds": 1
},
{
"slotId": "<SLOT_ID>",
"maxNumberOfAds": 2
}
}
Phản hồi biểu ngữ x
Mọi phản hồi đều tuân theo cùng một định dạng JSON. Tất cả nội dung cần thiết để hiển thị biểu ngữ đều được cung cấp trong phản hồi. Nếu biểu ngữ không có thành phần được cấu hình (chẳng hạn như không có hình ảnh trung tâm phụ), CitrusAd sẽ không phân phát thuộc tính.
{
"ads": [
{
"contentStandardId": "c619d1e2-1435-460b-9d2b-5d838e3dba9c",
"slotId": "<SLOT_ID>",
"banners": [
{
"citrusAdId": "shotgun__vW5pOojxDfN7T9VwaXWQLF2wKw3NzE0MTA3",
"citrusCampaignName": "CitrusAd-Example-Category-Banner-X-Ad-52793b405f1347b22e72a38c5a08699b",
"citrusContentStandardId": "c619d1e2-1435-460b-9d2b-5d838e3dba9c",
"citrusSlotId": "<SLOT_ID>",
"citrusExpiry": "2021-05-17T02:47:52.849995214Z",
"headingText": "Banner Advertisement for Magnum Double Ice Cream with a product image and shop now button",
"bannerText": "<strong>Magnum Double Ice Cream</strong>",
"bannerTextColour": "6e6c6c",
"ctaFlag": true,
"ctaText": "Shop now",
"ctaTextAccessibility": "for Magnum products",
"ctaLink": "https://www.tesco.com/groceries/en-GB/search?query=magnums",
"backgroundColour": "e1d6ac",
"heroImage": "https://cdn.flavedo.io/s/9b93e7f9-d747-4c8b-bcba-2357b280a3b3",
"heroImageAltText": "Magnums",
"tags": {},
"gtins": [
"7714107",
"7733636",
"7733657",
"7163379",
"7733628"
],
"position": 1
}
]
},
{
"contentStandardId": "c619d1e2-1435-460b-9d2b-5d838e3dba9c",
"slotId": "<SLOT_ID>",
"banners": [
{
"citrusAdId": "shotgun_kZp9yTCMm71vTo7iyQaK9I_YB09FUFYzNzBTQ0FO",
"citrusCampaignName": "milo-campaign-lakjsdf09kj",
"citrusContentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
"citrusSlotId": "<SLOT_ID>",
"citrusExpiry": "2021-05-17T02:47:52.849995214Z",
"headingText": "A banner for Milo with a product image and a shop now button",
"bannerText": "<strong>Try Milo Cereal</strong>",
"bannerTextColour": "48a94c",
"heroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8851d59f0574",
"heroImageAltText": "Milo product image",
"ctaFlag": true,
"ctaText": "Shop now",
"ctaTextAccessibility": "for Milo products",
"ctaLink": "retailer.com/everything/search/heritage%20mill?pageNumber=1",
"secondaryHeroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8m435c34r",
"secondaryHeroImageAltText": "Milo Logo",
"secondaryHeroMode": "landscape",
"backgroundColour": "895b5b",
"backgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
"backgroundImagePosition": "FILL",
"secondaryBackgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
"tags": {},
"gtins": [
"16309011",
"57312011",
"65250011"
],
"position": 1
}
]
}
]
}
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.
Thẻ theo dõi của bên thứ ba
Đối với quảng cáo biểu ngữ x, 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 (Javascript và Hình ảnh)
- Lượt nhấp DCM
- Lần hiển thị DCM
- IAS
- Lần hiển thị Adform
- Số lần nhấp chuột Adform
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 trackingTags ở 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 tagsvà trackingTags sẽ vẫn trống.
{
"ads": [
{
"contentStandardId": "c619d1e2-1435-460b-9d2b-5d838e3dba9c",
"slotId": "<SLOT_ID>",
"banners": [
{
"citrusAdId": "shotgun__vW5pOojxDfN7T9VwaXWQLF2wKw3NzE0MTA3",
"citrusCampaignName": "CitrusAd-Example-Category-Banner-X-Ad-52793b405f1347b22e72a38c5a08699b",
"citrusContentStandardId": "c619d1e2-1435-460b-9d2b-5d838e3dba9c",
"citrusSlotId": "<SLOT_ID>",
"citrusExpiry": "2021-05-17T02:47:52.849995214Z",
"headingText": "Banner Advertisement for Magnum Double Ice Cream with a product image and shop now button",
"bannerText": "<strong>Magnum Double Ice Cream</strong>",
"bannerTextColour": "6e6c6c",
"ctaFlag": true,
"ctaText": "Shop now",
"ctaTextAccessibility": "for Magnum products",
"ctaLink": "https://www.tesco.com/groceries/en-GB/search?query=magnums",
"backgroundColour": "e1d6ac",
"heroImage": "https://cdn.flavedo.io/s/9b93e7f9-d747-4c8b-bcba-2357b280a3b3",
"heroImageAltText": "Magnums",
"tags": {},
"trackingTags": {
"ADFORM_CLICK": "https://track.adform.net...",
"ADFORM_IMPRESSION": "<img src=\"https://track.adform.net...",
"DCM_CLICK": "https://ad.doubleclick.net/ddm/trackclk/...",
"DCM_IMPRESSION": "<IMG SRC=\"https://ad.doubleclick.net/ddm/trackimp/...",
"DV": "<script src=\"https://cdn.doubleverify.com/dvtp_src.js?ctx=...",
"DV_IMAGE": "<img src=\"https://tps.doubleverify.com/visit.jpg?ctx=..."
},
"gtins": [
"7714107",
"7733636",
"7733657",
"7163379",
"7733628"
],
"position": 1
}
]
}
]
}
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.
tagsđối tượngĐối với thẻ DoubleVerify (Javascript) và DCM, bạn có thể thấy
tagsđối tượng cũng được điền. Thực hành tốt nhất là sử dụngtrackingTags.
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": [
{
"contentStandardId": "c619d1e2-1435-460b-9d2b-5d838e3dba9c",
"slotId": "<SLOT_ID>",
"banners": [
{
"citrusAdId": "shotgun__vW5pOojxDfN7T9VwaXWQLF2wKw3NzE0MTA3",
"citrusCampaignName": "CitrusAd-Example-Category-Banner-X-Ad-52793b405f1347b22e72a38c5a08699b",
"citrusContentStandardId": "c619d1e2-1435-460b-9d2b-5d838e3dba9c",
"citrusSlotId": "<SLOT_ID>",
"citrusExpiry": "2021-05-17T02:47:52.849995214Z",
"headingText": "Banner Advertisement for Magnum Double Ice Cream with a product image and shop now button",
"bannerText": "<strong>Magnum Double Ice Cream</strong>",
"bannerTextColour": "6e6c6c",
"ctaFlag": true,
"ctaText": "Shop now",
"ctaTextAccessibility": "for Magnum products",
"ctaLink": "https://www.tesco.com/groceries/en-GB/search?query=magnums",
"backgroundColour": "e1d6ac",
"heroImage": "https://cdn.flavedo.io/s/9b93e7f9-d747-4c8b-bcba-2357b280a3b3",
"heroImageAltText": "Magnums",
"tags": {},
"gtins": [
"7714107",
"7733636",
"7733657",
"7163379",
"7733628"
],
"position": 1,
"sellerId": "1ben32-ss3d43-amea"
}
]
},
{
"contentStandardId": "c619d1e2-1435-460b-9d2b-5d838e3dba9c",
"slotId": "<SLOT_ID>",
"banners": [
{
"citrusAdId": "shotgun_kZp9yTCMm71vTo7iyQaK9I_YB09FUFYzNzBTQ0FO",
"citrusCampaignName": "milo-campaign-lakjsdf09kj",
"citrusContentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
"citrusSlotId": "<SLOT_ID>",
"citrusExpiry": "2021-05-17T02:47:52.849995214Z",
"headingText": "A banner for Milo with a product image and a shop now button",
"bannerText": "<strong>Try Milo Cereal</strong>",
"bannerTextColour": "48a94c",
"heroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8851d59f0574",
"heroImageAltText": "Milo product image",
"ctaFlag": true,
"ctaText": "Shop now",
"ctaTextAccessibility": "for Milo products",
"ctaLink": "retailer.com/everything/search/heritage%20mill?pageNumber=1",
"secondaryHeroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8m435c34r",
"secondaryHeroImageAltText": "Milo Logo",
"secondaryHeroMode": "landscape",
"backgroundColour": "895b5b",
"backgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
"backgroundImagePosition": "FILL",
"secondaryBackgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
"tags": {},
"gtins": [
"16309011",
"57312011",
"65250011"
],
"position": 1
}
]
}
]
}
Thẻ theo dõi của bên thứ ba
Sắp ra mắt trong bản phát hành 44
Khả năng này dự kiến sẽ được phát hành trong phiên bản 44.0. Mảng
tagsđã được cung cấp trong phản hồi.
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.