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.What you set up
For a website, tracking has two parts:- The Gravity Pixel. A script on your site that records visits and the ad click that brought each visitor.
- 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.
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.
Step 1: Add a payment method
- Sign in to the Gravity dashboard.
- Go to Settings → Billing.
- Add a payment method.
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.
- Open your website’s source project in your coding agent.
- Copy the prompt above and paste it into the agent. It asks for your advertiser account name first.
- 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.
- Read the changes and the list of missing inputs that the agent shows you.
- Add your API key to the environment of your backend host as
GRAVITY_API_KEY. - Deploy your changes.
Option B: Set up by hand
-
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. -
Replace
YOUR_PIXEL_IDwith the Pixel ID from Events Manager. Events Manager also shows a snippet that you can copy. - Add the snippet to each subdomain where visitors land or convert.
-
In the browser code that submits an order, read the attribution data from the Pixel. Send it to your backend with the order:
-
After your backend confirms the order, send the conversion to Gravity. Use the order data from your backend, not values from the browser.
-
If you send the same event again (for example, on a retry), use the same
event_idandevent_time. - Deploy your changes.
Step 3: Verify tracking
- Open your website in a browser.
- Open the developer tools and select the Network tab.
- Find a request to
api.trygravity.com/track/gr-events. Make sure that the response is successful. - In Events Manager, find the Browser pixel row. It shows a recent event.
- Complete one real conversion on your website, for example an order.
- In Events Manager, find the conversion event from your backend.
Step 4: Create and launch a campaign
- In the dashboard, go to Campaigns.
- Select Create, then Create campaign. The campaign builder opens.
-
Fill in the campaign details:
- Add at least one ad group. An ad group holds your ads and the context Gravity uses to match them to conversations.
- Select Launch campaign.
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.