How to show ads
- Show one ad at a time. Never show multiple ads at once.
- Do not rotate ads. Do not cycle banners or refresh ads on a timer. Request ads when the user sends a new message, not repeatedly while you wait for the next one. Without new context, extra ads create fatigue rather than better recommendations.
- Keep ads in the conversation. Show ads within the chat, alongside the conversation they relate to. Do not put them outside the chat.
- Show only visible ads. Do not render hidden ads or count an impression for an ad the user cannot see. Requesting an ad is not the same as displaying it. Follow Show ads for rendering and impression tracking.
- Show the complete ad. Never truncate the copy or clip the unit. Users need to understand what they are clicking.
- Make the design good. Do not show ugly or broken-looking ads. Make text readable, keep the layout consistent with your product, and give the ad enough space to display properly. Design quality affects both user experience and advertiser performance.
What to send us
Uncertainty is never rewarded: the less Gravity knows, the less advertisers pay. Maximizing your revenue means maximizing the data you share with Gravity. Better tracking connects ads to advertiser results and gives advertisers more confidence to pay for your traffic.Send every user request and the original text
Send Gravity every user request in the conversation, including turns where you do not want to show an ad. If you omit turns, Gravity loses the conversation flow, which can worsen matching and performance. Sending a request does not mean you must display an ad on that turn. Only record an impression when you actually show one. Send the raw user text inmessages. Do not replace it with your own custom context, rewritten query, or summary. Gravity needs what the user actually said to understand their intent. Respect user consent and redact secrets and credentials; do not send a full chat archive. Follow Request ads for the request structure and supported conversation context.
Send hashed email and real device signals
- Hashed email is required: send
user.hashed_emailon every request. Skip it only when privacy rules prevent sharing identifiers: GDPR applies without a validtcfString, ausPrivacyopt-out, or GPC. Without it, your CPMs are significantly lower. Send the SHA-256 hash of the normalized email; never send raw email. Follow Hash user data. - End-user device signals: send
device.ip,device.ua,device.device_type, anddevice.oson every request. These must describe the real user, not your server, proxy, or a hardcoded browser. Native apps and server integrations must forward the real signals. Follow Device signals.
Install the Gravity pixel
Install the Gravity pixel before you go live. Copy your pixel snippet from Settings → Tracking and add it to the<head> of every page on your website. The pixel records visits and sessions and creates visitor and session IDs that gravityContext() adds to ad requests. Gravity uses these signals to connect ad impressions and clicks to real results. Better tracking reduces uncertainty and supports higher revenue.
If your app opens ad links in an in-app browser, also follow the WebView installation to preserve attribution. Verify that the pixel sends events, not just that its script loads.
Test with the SDK
Run split tests with the Gravity SDK and its standard ad components. Gravity can change supported designs remotely, so you can test without changing your code or shipping an app release. Your own custom renderer does not take part in Gravity’s design experiments. This is controlled testing, not permission to rotate ads during a conversation. KeepsessionId stable for the conversation so the session keeps its assigned design.
Change one thing at a time and fix rendering or layout bugs before judging results. A clipped ad or broken layout is not a fair test of a design. Use separate registered placements for distinct surfaces or new placement tests, and keep IDs stable for unchanged slots so you can compare their performance.
Measuring success
Make revenue per user your main indicator
Use ARPU: average revenue per user as your main indicator. Compare revenue and users over the same period and population. It tells you more about the value of your ad-supported product than the price of an isolated impression. Do not over-index on CPM, the revenue per thousand impressions. You can show fewer ads and have the same CPM. That does not tell you whether total earnings or revenue per user improved. Read CPM alongside ARPU and total revenue, not as the goal by itself. See user earnings and segments for user-level analysis and Payouts for metric definitions.Fill rate is not a success metric on its own
A high or low fill rate alone tells you nothing about whether you are succeeding. Changing relevancy changes which requests can receive ads, so fill rate is not an independent measure of traffic quality or revenue. Keep the relevancy tradeoff in mind: stricter matching can reduce fill, while looser matching can admit less relevant ads. Do not turn relevancy down just to make fill look better. Judge a change by revenue per user and advertiser performance, not fill alone.Do not overreact to dips
Performance can be volatile. Engine changes, advertiser demand, and advertisers’ reactions to the quality of your traffic can change network economics quickly. Demand may also take time to catch up when your traffic grows. Do not redesign your ad experience or scale acquisition based on a short-lived CPM dip. Compare consistent periods and look at ARPU, total revenue, and changes in your traffic mix before deciding what to change.Grow the right traffic
Prioritize high-intent, tier-1 users
Focus on high-intent users in tier-1 markets for the highest-quality traffic. Do not scale non-tier-1 traffic aggressively just to grow impression volume: it tends to bring the least advertiser value and the hardest monetization economics. More traffic does not mean proportionally more earnings. Use geography and user segments to compare revenue per user before scaling acquisition. This is a growth decision, not a reason to stop sending requests from your existing users.Build a free plan that works as its own product
Have an ad-supported free plan. Optimize it around free or inexpensive models so the cost of serving users fits its revenue. Treat the free plan as a separate product, not merely a funnel to paid. Optimize its usefulness, retention, costs, and revenue per user together. If you are worried about scaling a free plan, talk to Gravity. We can help you get started with one.Common mistakes
- Stacking ads, mixing providers, or adding house promotions beside Gravity.
- Rotating ads without a new user message.
- Putting ads outside the conversation, hiding them, or truncating their copy.
- Sending only the turns you intend to monetize, or replacing user text with summaries.
- Sending server IPs, made-up UAs, or incomplete device signals.
- Omitting
user.hashed_emailwhen you’re allowed to share it, or going live without the Gravity pixel. - Optimizing CPM or fill in isolation instead of revenue per user.
- Scaling low-value traffic before the free plan’s economics work.