Skip to main content
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.

Base URL

Headers

string
required
Your Gravity API key. Use the same key that you use for ad requests.
Do not put your API key in browser code. Send feedback from your server. See Send feedback from your server.

Body

string
required
The session ID. Use the same value that you sent in the ad request.
string
required
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.
string
required
The reaction of the user. One of thumbs_up or thumbs_down.
array
Optional. An array of strings that tell why the user reacted. You can send any string. These values are suggestions:
string
Optional. Free text from the user, at most 1,000 characters.
string
Optional. The placement type where the ad showed, for example below_response. If you do not send it, the server gets it from impUrl.
string
Optional. Your slot ID for the placement. If you do not send it, the server gets it from impUrl.
string
Optional. Your ID for the end user.
object
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.
  1. Keep the ad object that your server returned, and keep the sessionId.
  2. Show a thumbs-up and a thumbs-down button after the ad becomes visible.
  3. When the user taps a button, send the reaction to your route.
  4. In your route, forward the body to Gravity with your API key.
Client:
Server (Express):

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 example not_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.