This document explains how to report impressions and clicks using Epsilon Retail Media APIs, with steps for integration and improved ad ID validation.
To effectively report impressions and clicks, use /resource/ endpoint. Impressions should be directed to the first-i resource, while clicks should be reported to the second-c resource.
Prerequisite
Obtain your Base URL from your Technical Account Manager before reporting impressions and clicks.
Integrating Endpoint Calls
Endpoint calls must be executed within your app or website. In CitrusAd, the integration process is similar for both mobile apps and websites due to its 'backend to backend' integration approach. This approach ensures that ad requests are consistent across both desktop and mobile platforms. However, since mobile apps do not support JS libraries, you must make backend requests to our click and impression endpoints.
Reporting Impressions
To report an impression, send a GET request in the following format:
https://$BASE_URL.citrusad.com/v1/resource/first-i/AD_ID
Replace AD_ID with the adId provided for the ad you are reporting.
For example, the following GET request reports an impression for the adId, display_xw3ybbrymHT_D3VwU3Ic5ThUkbhFNkY4NVNIODU4NEVGRkdT.
https://$BASE_URL.citrusad.com/v1/resource/first-i/display_xw3ybbrymHT_D3VwU3Ic5ThUkbhFNkY4NVNIODU4NEVGRkdT
Reporting Clicks
To report a click, send a GET request in the format below:
https://$BASE_URL.citrusad.com/v1/resource/second-c/AD_ID
Replace AD_ID with the adId provided for the ad you are reporting.
For example, the following GET request reports an impression for the adId, display_xw3ybbrymHT_D3VwU3Ic5ThUkbhFNkY4NVNIODU4NEVGRkdT.
https://$BASE_URL.citrusad.com/v1/resource/second-c/display_xw3ybbrymHT_D3VwU3Ic5ThUkbhFNkY4NVNIODU4NEVGRkdT
API Validation for Realized Ad IDs
This feature is not turned on by default and is controlled by a feature toggle. It will be available to everyone by March 30th, 2025. To use it sooner, please contact your CitrusAd representative.
The API includes validation for ad IDs to ensure accurate data and reduce errors. Requests with improperly encoded or prefixed ad IDs return a 400 error and a detailed error message.
Key Benefits
- Faster Issue Resolution: Quick feedback helps retailers fix problems faster.
- Better Accuracy: Fewer errors mean more accurate reports and data.
Example Error Message
"Invalid ad ID. Must be properly encoded and prefixed with 'display', 'banner', or 'shotgun_'."