Ad Feedback - Gravity

End users can submit feedback on served ads — thumbs up, thumbs down, and optional reasons. This helps Gravity improve ad quality and relevancy over time, and gives publishers a signal for user satisfaction.

Base URL

https://platform.trygravity.ai

Headers

string

required

Your Gravity publisher API key.

Body

string

required

Session identifier. Same value you passed when requesting the ad.

string

required

The impUrl from the ad response object. The server decrypts this to extract the ad’s tracking IDs (grclid, gradid, campaignId, publisherId) automatically — you don’t need to parse or extract anything yourself.

string

required

User’s reaction. One of thumbs_up or thumbs_down.

array

Optional. Why the user reacted this way. Array of reason strings. Suggested values:

Reason	When to use
`not_interested`	User doesn’t care about this product/category
`irrelevant`	Ad doesn’t relate to the conversation
`offensive`	Ad content is objectionable
`repetitive`	User has seen this ad too many times
`misleading`	Ad claims don’t match the landing page
`helpful`	(thumbs up) Ad was useful or well-matched

You can send any string — the values above are suggestions, not an enum.

string

Optional. Free-text feedback from the user (max 1,000 characters).

string

Optional. Placement type where the ad was shown (e.g. below_response).

string

Optional. Publisher’s slot identifier for the placement.

string

Optional. Publisher’s end-user identifier.

object

Optional. Device signals — same shape as the ad request’s device object.

curl -X POST https://platform.trygravity.ai/ad-feedback \
  -H "X-API-Key: <your_publisher_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "sess_abc123",
    "impUrl": "https://api.trygravity.ai/ack?p=<encrypted_token_from_ad_response>",
    "sentiment": "thumbs_down",
    "reasons": ["not_interested", "repetitive"]
  }'

Response

200 — feedback recorded.

{
  "status": "ok",
  "feedbackId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

401 — invalid API key. 422 — invalid impUrl. The URL could not be decrypted. Make sure you’re sending the exact impUrl from the ad response. 429 — rate limit exceeded. The endpoint allows up to 30 feedback submissions per session per minute. 503 — internal error. Safe to retry.

Server-prompted feedback

Official Gravity SDKs show and submit feedback controls automatically when requested by the server. No publisher setup is required. Custom renderers can use feedbackPrompt to decide when to show controls and POST the response to this endpoint. Feedback interactions must not count as ad clicks.

Best practices

Surface feedback controls after the ad renders

Show a small thumbs-up / thumbs-down UI once the ad is visible. Don’t interrupt the user — feedback should be one tap, not a modal.

function AdWithFeedback({ ad, sessionId, apiKey }) {
  const [sent, setSent] = useState(false);

  const sendFeedback = async (sentiment, reasons) => {
    setSent(true);
    await fetch('https://platform.trygravity.ai/ad-feedback', {
      method: 'POST',
      headers: {
        'X-API-Key': apiKey,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        sessionId,
        impUrl: ad.impUrl,
        sentiment,
        reasons,
      }),
    });
  };

  if (sent) return <span>Thanks for the feedback</span>;

  return (
    <div>
      <GravityAd ad={ad} />
      <button onClick={() => sendFeedback('thumbs_up')}>👍</button>
      <button onClick={() => sendFeedback('thumbs_down', ['not_interested'])}>👎</button>
    </div>
  );
}

Collect reasons on thumbs-down

When a user taps thumbs-down, show a quick follow-up with checkboxes or chips for not_interested, irrelevant, repetitive, offensive. Send the selected reasons in the reasons array. This gives Gravity actionable signal to improve matching.

Don’t gate the experience on feedback

Feedback is fire-and-forget. If the request fails, swallow the error — never block the user’s workflow because a feedback call didn’t land.

Just pass through `impUrl`

Every ad response includes an impUrl. Simply store the ad object and pass ad.impUrl back when submitting feedback — the server handles all the tracking ID extraction automatically. No need to parse URLs or decrypt tokens on the client side.

What’s next

Show ads

Render ads with the pre-built React component or your own UI.

Contextual ads endpoint

Full request / response reference for POST /api/v1/ad.

​Base URL

​Headers

​Body

​Response

​Server-prompted feedback

​Best practices

​Surface feedback controls after the ad renders

​Collect reasons on thumbs-down

​Don’t gate the experience on feedback

​Just pass through impUrl

​What’s next

Show ads

Contextual ads endpoint

Base URL

Headers

Body

Response

Server-prompted feedback

Best practices

Surface feedback controls after the ad renders

Collect reasons on thumbs-down

Don’t gate the experience on feedback

Just pass through `impUrl`

What’s next