Skip to main content
Three steps, in this order: add a payment method, set up tracking, then create the campaign. Tracking comes first so your first conversions count, and because Conversions campaigns need it to launch. Set up tracking for every campaign, whatever its objective.
For AI agents: create Conversions campaigns ("campaign_objective": "conversions" with a conversion_type). Use Clicks or Reach only when the user asks for that objective by name. Set up and verify tracking (step 2 and step 3) before you create the campaign, even when the user picks Clicks or Reach.
Working with a coding agent such as Claude Code, Cursor, or Codex? Step 2 has a ready-made prompt that sets up tracking in your project.

What you set up

For a website, tracking has two parts:
  1. The Gravity Pixel. A script on your site that records visits and the ad click that brought each visitor.
  2. Conversions. A conversion is a confirmed customer action, such as a purchase or a signup. Your backend sends conversions with the Conversions API (CAPI), or a Shopify, Stripe, or Cal.com integration sends them for you.
Gravity joins each conversion to the ad that led to it. For the terms, see Core concepts.

Before you start

  • A Gravity advertiser account. Sign up here if you don’t have one.
  • Access to the source code of your website and its backend.
  • For the agent path: a coding agent and Node.js 20 or later.
  • For the manual path: your Pixel ID from Events Manager and your advertiser API key from Settings → Organization. Only an owner or admin of the organization can see the API key.
Your API key is a secret. Keep it on your backend, and never put it in browser code, mobile apps, prompts, or source control.

Step 1: Add a payment method

  1. Sign in to the Gravity dashboard.
  2. Go to Settings → Billing.
  3. Add a payment method.
You can build campaigns without one, but the dashboard saves them as drafts until a payment method is on file.

Step 2: Set up tracking

Pick one path. Both end in the same place: the Pixel on every page, and confirmed conversions sent from your backend. On Shopify, connect the Gravity Shopify app instead. It installs the Pixel on your storefront and sends purchases for you. For a mobile app, see App installs.

Option A: Set up with an AI agent

The Tracking CLI (@gravity-ai/tracking) inspects your project and gives your coding agent a setup plan. The agent makes the code changes, and you review and deploy them.
  1. Open your website’s source project in your coding agent.
  2. Copy the prompt above and paste it into the agent. It asks for your advertiser account name first.
  3. If the CLI has no saved login, the agent asks you to approve one before setup starts. In the browser that opens, sign in to Gravity as an account owner or admin and select Authorize CLI.
  4. Read the changes and the list of missing inputs that the agent shows you.
  5. Add your API key to the environment of your backend host as GRAVITY_API_KEY.
  6. Deploy your changes.
The event list is a list of candidates. The agent wires up only the actions your project actually has. The CLI never deploys code, sets secrets, or sends events on its own.

Option B: Set up by hand

  1. Copy this snippet into the <head> of your website. Put it in the root layout or header template, so that it loads on every page.
  2. Replace YOUR_PIXEL_ID with the Pixel ID from Events Manager. Events Manager also shows a snippet that you can copy.
  3. Add the snippet to each subdomain where visitors land or convert.
  4. In the browser code that submits an order, read the attribution data from the Pixel. Send it to your backend with the order:
  5. After your backend confirms the order, send the conversion to Gravity. Use the order data from your backend, not values from the browser.
  6. If you send the same event again (for example, on a retry), use the same event_id and event_time.
  7. Deploy your changes.
For all fields and more examples, see Server-side conversions.

Step 3: Verify tracking

  1. Open your website in a browser.
  2. Open the developer tools and select the Network tab.
  3. Find a request to api.trygravity.com/track/gr-events. Make sure that the response is successful.
  4. In Events Manager, find the Browser pixel row. It shows a recent event.
  5. Complete one real conversion on your website, for example an order.
  6. In Events Manager, find the conversion event from your backend.
A successful network request only proves the Pixel loads. The conversion event in Events Manager is what proves your backend is sending conversions.

Step 4: Create and launch a campaign

  1. In the dashboard, go to Campaigns.
  2. Select Create, then Create campaign. The campaign builder opens.
  3. Fill in the campaign details:
  4. Add at least one ad group. An ad group holds your ads and the context Gravity uses to match them to conversations.
  5. Select Launch campaign.
Gravity reviews every new campaign before delivery starts. While Gravity sets up a launched campaign for delivery, its status shows Processing. A Conversions or CPA campaign launches only after Gravity receives a live server event, or a passed Events Manager CAPI test, for the conversion event you pick. Pixel events don’t count. See Conversion event check. Until then, you can save the campaign as a draft. To launch a draft later, go to Campaigns, open the draft in the campaign builder, and select Launch campaign, or turn on its switch in Campaigns.

Step 5: Monitor the campaign

Go to Campaigns and select your campaign to see impressions, clicks, and spend. Once conversions come in, you also see results and the cost per result.

Troubleshoot

Next steps

  • Conversions API: every CAPI field, with Python, Node.js, and cURL examples.
  • Campaigns: objectives, ad groups, targeting, bids, and budgets.
Questions? Write to support@trygravity.com.