Ad serving
Ad Feedback
Let users react to ads with a thumbs up or a thumbs down.
POST
Send the reaction of a user to an ad: a thumbs up or a thumbs down, with optional reasons. Gravity uses this feedback to make ads more relevant. You can use it to measure user satisfaction.
Server (Express):
Base URL
Headers
Body
The
impUrl of the ad, as the ad response gave it. The server gets the tracking IDs of the ad from this URL. You do not need to parse it.Optional. An array of strings that tell why the user reacted. You can send any string. These values are suggestions:
Optional. The placement type where the ad showed, for example
below_response. If you do not send it, the server gets it from impUrl.Optional. Your slot ID for the placement. If you do not send it, the server gets it from
impUrl.Optional. Data about the device. The fields are
ip, ua, lang, os, osv, make, model, and type. All are strings.Response
200: Gravity recorded the feedback.
Errors
Use the status code and the
Retry-After header in your code. Do not use the detail text, because it can change.
Official SDKs
The iOS components (SpecAdView, GravityAdView) and the Android Compose components (SpecAd, GravityAd) show thumbs-up and thumbs-down buttons under each ad. A tap sends the feedback and hides the buttons. A thumbs down sends the reason not_interested. To hide the buttons, set showFeedback to false. See iOS SDK and Android SDK.
The iOS and Android SDKs also have a sendFeedback() method for custom UIs.
Send feedback from your server
Your API key must stay on your server. For a web app, make a small route on your server that forwards feedback to Gravity.- Keep the ad object that your server returned, and keep the
sessionId. - Show a thumbs-up and a thumbs-down button after the ad becomes visible.
- When the user taps a button, send the reaction to your route.
- In your route, forward the body to Gravity with your API key.
Recommendations
Make feedback one tap. Show small buttons after the ad becomes visible. Do not use a modal dialog. Ask for reasons after a thumbs down. Show a short list of chips or checkboxes, for examplenot_interested, irrelevant, repetitive, and offensive. Send the reasons that the user selects in the reasons array.
Do not block the user. Send feedback in the background. If the request fails, ignore the error. A feedback tap must not count as an ad click.
Send impUrl as it is. Keep the ad object, and send ad.impUrl with the feedback. The server reads the tracking IDs from it. Do not parse or decode it in your client.
Next steps
Show ads
Show ads with the ready-made React component or with your own UI.
Contextual ads endpoint
The full request and response reference for
POST /api/v1/ad.