Skip to main content

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.

​
Why you need this

Without the pixel, Gravity can measure impressions and clicks — but not what happens after the user lands on your site. Install the pixel on your landing + conversion pages and we can attribute purchases, signups, and demo requests back to the specific ad that drove them. This unlocks:
  • Per-campaign conversion rate and ROAS in your dashboard
  • Conversion reporting tied back to specific campaigns and ads
  • Retargeting audience segmentation (upcoming feature)

​
Install — web

Drop this into every page of your site (or at minimum: landing page, checkout, signup): 
<!-- Just before </body> -->
<script>
  !function(w,d,t,u,n,a,m){w['GravityPixelObject']=n;w[n]=w[n]||function(){
  (w[n].q=w[n].q||[]).push(arguments)},w[n].l=1*new Date();a=d.createElement(t),
  m=d.getElementsByTagName(t)[0];a.async=1;a.src=u;m.parentNode.insertBefore(a,m)
  }(window,document,'script','https://code.trygravity.ai/gr-pix.js','gravity');
  gravity('init', 'YOUR_ADVERTISER_ID');
</script>
YOUR_ADVERTISER_ID lives in your dashboard under Settings → Organization. It’s a UUID.

​
Verify it’s firing

  1. Load your landing page with the pixel installed.
  2. Open your browser DevTools → Network tab and look for a request to api.trygravity.ai/track/gr-events.
  3. A 200 response means the pixel is firing correctly. Events typically appear in your dashboard within ~10 minutes.

​
How conversions are tracked

The pixel captures page views and prepares attribution context. Conversions themselves are posted server-to-server from your backend to Gravity — this is more reliable than client-side tracking and allows you to attach richer data (emails, order details, line items). Four supported paths, pick the one that fits your stack: The Gravity Conversions API (CAPI) gives you the most control and the richest data. The pixel captures attribution context on the frontend; your backend sends the conversion with full order details. On your checkout page: 
// The pixel is already running — read the attribution data
var capiData = window.gravityPixel.getCAPIData();

// Pass it to your backend with the order
fetch('/api/complete-order', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    order_id: 'order-123',
    total: 99.99,
    email: 'customer@example.com',
    gravity: capiData
  })
});
On your backend: 
gravity_data = request.json.get("gravity", {})

requests.post(
    "https://api.trygravity.ai/gateway/events",
    params={"api_key": "YOUR_API_KEY"},
    json={
        "data": [{
            "event_name": "Purchase",
            "event_time": int(time.time()),
            "event_id": f"order-{order_id}",
            "action_source": "website",
            "event_source_url": gravity_data.get("event_source_url", ""),
            "user_data": {
                **gravity_data.get("user_data", {}),
                "em": [customer_email],
            },
            "custom_data": {
                "value": order_total,
                "currency": "USD",
                "order_id": order_id,
            },
        }],
    },
)
See the full Server-side conversions guide for complete examples in Python, Node.js, and cURL.

​
Shopify — one-click OAuth

If your store runs on Shopify, connect via OAuth in the dashboard under Settings → Organization. This automatically:
  • Installs the pixel on every storefront page.
  • Subscribes to Shopify’s checkout_completed event and posts conversions to POST /shopify/conversions on your behalf.
  • Pulls customer emails for attribution (hashed before ingest).
No theme-editing or copy-paste required. This is the fastest path for e-commerce advertisers.

​
Direct API (legacy)

A simpler endpoint for basic conversion tracking: 
curl -X POST https://api.trygravity.ai/generic/conversions \
  -H "Authorization: Bearer $GRAVITY_ADVERTISER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversion_type": "purchase",
    "timestamp": "2026-04-22T15:04:05Z",
    "value": 49.99,
    "visitor_id": "<visitor_id from pixel>",
    "customer_email": "user@example.com",
    "metadata": { "order_id": "order_12345" }
  }'
For new integrations, we recommend the Conversions API instead — it supports richer data, batch events, and deduplication.

​
Cal.com bookings

For consultative / demo-based flows, Gravity can receive Cal.com booking webhooks at POST /caldotcom/booking. Configure in Cal.com’s webhook settings; we attribute bookings back to the originating ad automatically.

​
App installs (iOS / Android)

Track mobile app installs as conversions — either from your app backend (S2S) or via MMP postback (AppsFlyer, Adjust, Kochava, Branch, Singular). Full guide: App install tracking.

​
Not currently supported

Segment, GTM, and Stripe webhooks aren’t supported integrations today. Use the Conversions API from your backend if you’re on one of those stacks.

​
Customer email

Sending customer_email on the Direct API request materially improves attribution (survives device switches, incomplete page loads, etc.). Gravity hashes it server-side (SHA-256 over lowercased+trimmed) before it lands in the warehouse — the raw value never persists. Send over TLS only, which is already the case if you’re hitting https://api.trygravity.ai. If your data-handling policy requires hashing before the value leaves your server, do your own SHA-256 (lowercased + trimmed email) and put the digest under metadata.customer_email_hash for forensic correlation — but note the attribution pipeline only joins on the hash produced by our server from customer_email, so pre-hashing currently reduces match rate. Don’t fire the pixel or send conversions before the user accepts your cookie/consent banner (where one applies in your jurisdiction). Standard integration patterns — conditional script load behind a consent manager — work as expected.

​
Next

Analytics

Reports, attribution windows, and ROAS.