Before you start
- Your Pixel ID. Find it in Events Manager. The Pixel ID is a UUID. It is not your account ID or your API key.
- Access to the shared layout or header template of your website.
- If your website is a Shopify store, connect the Shopify app instead. It installs a Pixel on your storefront.
Install the pixel
-
Copy this snippet. Events Manager also shows a copy of it with your Pixel ID.
-
Replace
YOUR_PIXEL_IDwith your Pixel ID. -
Paste the snippet into the
<head>of the root layout or header template of your website. The Pixel must load on every page where visitors land or convert. - Install the snippet on each subdomain where visitors land or convert, including your login, signup, onboarding, and checkout entry points. A subdomain does not get the Pixel from the main domain.
- Deploy your website.
Use one Pixel for advertiser and publisher accounts
Do this step only if your company is a Gravity advertiser and also a Gravity publisher (AI platform) on the same website. Each account has a different Pixel ID. Do not install two Pixel snippets on the same page. Install one snippet, and add the publisher Pixel ID as thepublisherId option:
YOUR_ADVERTISER_PIXEL_IDis the Pixel ID from Events Manager in your advertiser account.YOUR_PUBLISHER_PIXEL_IDis the pixel ID from Settings > Tracking in your publisher account.
window.GRAVITY_PIXEL_CONFIG with publisherId: "YOUR_PUBLISHER_PIXEL_ID".
For server-side conversions, use the API key of your advertiser account. You do not need to change anything else. getCAPIData() reads the data from the single Pixel.
Verify the pixel
- Open a page of 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 the most recent event that Gravity received.
code.trygravity.com and sends events to api.trygravity.com. If you use a first-party proxy, the requests go to your own domain.
A successful Pixel request does not verify your server-side conversions. Verify them separately in Events Manager.
Track conversions
The Pixel records page views and attribution context. To record a conversion (a purchase or a signup, for example), do these steps:- In the browser, read the attribution data with
window.gravityPixel.getCAPIData(). - Send that data to your backend with the business request, for example the order.
- After your backend confirms the action, send the conversion to Gravity with CAPI.
Respect consent
Connect the Pixel and your backend sender to your current consent rules:- Where the law requires consent, load the Pixel only after the visitor gives consent.
- If the visitor withdraws consent, stop all future sends from the Pixel and your backend.
Optional: Improve attribution with a first-party proxy
A first-party proxy sends Pixel requests through your own domain. It can help when a browser or extension blocks requests to third-party domains. By default, the script loads fromcode.trygravity.com and sends events, sessions, and configuration requests to api.trygravity.com. Old script URLs on the .ai domain continue to work.
Add a forwarding rule
Select your platform. Each rule forwards/gr/ on your domain to https://api.trygravity.com/proxy/.
Vercel / Next.js
Vercel / Next.js
Add this to your Deploy your project. Vercel applies the rewrite at the edge.
next.config.js (or next.config.ts):Cloudflare Worker
Cloudflare Worker
Make a Worker that receives In the Cloudflare dashboard, attach the Worker to a route on your domain.
/gr/ requests:Nginx
Nginx
Add this to your server block:
Caddy
Caddy
Apache
Apache
Turn on
mod_proxy and mod_proxy_http. Then add:Express / Node.js
Express / Node.js
This example uses the
http-proxy-middleware package:Configure the pixel
Add this script before the Pixel snippet:/gr/ with the path of your forwarding rule.
Verify the proxy
- Open a page of your website in a browser.
- Open the developer tools and select the Network tab.
- Find requests to your domain at
/gr/init,/gr/events, and/gr/session. Make sure that the responses are successful. - In Events Manager, find a recent event in the Browser pixel row.
Troubleshoot
Next steps
Conversions API
Send confirmed conversions from your backend.
App installs
Track iOS and Android installs as conversions.