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

# Experiments

> Gravity tests ad variants for you — managed from our dashboard, no code changes required.

## What experiments do

Not every ad format converts the same across every audience. A `card` might outperform a `minimal` variant on your traffic — or vice versa. Rather than asking you to build an A/B harness, **Gravity runs experiments on your behalf**: we split traffic across multiple ad variants, measure which one performs best, and gradually shift toward the winner.

<Note>
  Experiments are currently **managed by the Gravity team** — configured and monitored by us against your live traffic. Self-serve authoring isn't live yet. Email [support@trygravity.ai](mailto:support@trygravity.ai) if you want an experiment set up, or you'll see results show up in your dashboard as we run them.
</Note>

## How it affects your integration

<Steps>
  <Step title="SDK publishers — automatic">
    The engine assigns a variant per session and returns `ad.variant` on the response. The `<GravityAd />` component picks it up:

    ```tsx theme={null}
    import { GravityAd } from '@gravity-ai/react';

    // When an experiment is active, ad.variant is the engine's pick.
    // When no experiment is running, fall back to your default.
    <GravityAd ad={ad} variant={ad.variant ?? 'card'} />
    ```

    No other code changes needed.
  </Step>

  <Step title="Direct-API integrations">
    If you call `/api/v1/ad` and render yourself, you'll still receive `ad.variant`, `ad.experiment_id`, and `ad.composition_id` on each response. You can participate in experiments by handling different variants in your renderer — or stick with your existing single-variant render and the experiment metadata just flows through for reporting.
  </Step>
</Steps>

## Experiment metadata on the response

When an experiment is active on traffic that matches your requests, these fields appear on each `Ad`:

| Field            | Description                                                     |
| ---------------- | --------------------------------------------------------------- |
| `variant`        | Human-readable arm label (e.g. `"card-minimal"`).               |
| `experiment_id`  | Canonical experiment ID.                                        |
| `composition_id` | Per-render composition ID (unique per impression).              |
| `renderer_key`   | Which renderer the engine wants (e.g. `"card"`, `"spotlight"`). |

When no experiment is active, these fields are absent — code that doesn't read them keeps working.

## Tracking

The engine bakes `experiment_id` and `composition_id` into the encrypted payload on both `impUrl` and `clickUrl`. No extra instrumentation — impressions attribute to the right arm automatically, and you'll see per-arm results in your dashboard.

## FAQ

<AccordionGroup>
  <Accordion title="Do I need to do anything for experiments to start working?">
    Not today. Gravity configures experiments on your traffic. If you're on the SDK, you get automatic variant rendering via `ad.variant`. If you're on the direct API, you still get the experiment metadata — how much you act on it is up to you.
  </Accordion>

  <Accordion title="Can I run my own experiments?">
    Self-serve experiment authoring isn't live yet. Email us and we'll spin one up for you.
  </Accordion>

  <Accordion title="Where do I see results?">
    Your dashboard **Overview** page. Per-arm impressions, clicks, CTR, and conversion rate updated in near-real-time. The Gravity team can also share detailed experiment reports.
  </Accordion>

  <Accordion title="Will my ad flicker between variants mid-session?">
    No. Assignment is session-stable via your `sessionId`. Same session = same arm.
  </Accordion>
</AccordionGroup>