> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trygravity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Best practices

> Show ads well, send the right signals, and measure the performance that sustains your earnings.

Your earnings are tightly linked to advertiser performance. Gravity is a network economy: advertisers adjust their bids and budgets based on the results your traffic delivers. Show ads that help users, not as many ads as you can fit. Spamming ads may earn a little more in the short term, but it creates fatigue, lowers CPMs, and hurts long-term performance.

## 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](https://docs.trygravity.com/ai-platforms/show-ads.md) 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.

**Never show another provider's ads alongside or in combination with Gravity.** A second provider serves different ads, adds ad fatigue, and worsens performance. Gravity is optimizing the ad experience for the user; it cannot do that effectively if another system is also serving ads to them.

The same principle applies to mixing Gravity ads with a different unit, house promotion, or direct campaign. Do not combine them into an ad stack or show them together. See [Guidelines](https://docs.trygravity.com/ai-platforms/publisher-requirements.md) for the rules.

## 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** in `messages`. 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](https://docs.trygravity.com/ai-platforms/request-ads.md) for the request structure and supported conversation context.

### Send hashed email and real device signals

* **Hashed email is required:** send `user.hashed_email` on every request. Skip it only when [privacy rules](https://docs.trygravity.com/engine/contextual-ads.md#consent) prevent sharing identifiers: GDPR applies without a valid `tcfString`, a `usPrivacy` opt-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](https://docs.trygravity.com/ai-platforms/request-ads.md#hash-user-data).
* **End-user device signals:** send `device.ip`, `device.ua`, `device.device_type`, and `device.os` on 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](https://docs.trygravity.com/ai-platforms/request-ads.md#device-signals).

### Install the Gravity pixel

Install the [Gravity pixel](https://docs.trygravity.com/ai-platforms/pixel.md) 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](https://docs.trygravity.com/ai-platforms/pixel.md#in-app-browser-webview) 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](https://docs.trygravity.com/ai-platforms/experiments.md) 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. Keep `sessionId` 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](https://docs.trygravity.com/ai-platforms/placements.md) 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](https://docs.trygravity.com/ai-platforms/user-earnings.md) for user-level analysis and [Payouts](https://docs.trygravity.com/ai-platforms/payouts.md) 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](https://docs.trygravity.com/ai-platforms/request-ads.md#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](https://docs.trygravity.com/ai-platforms/user-earnings.md) 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_email` when 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.

For launch steps, use [Going live](https://docs.trygravity.com/ai-platforms/going-live.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.