Skip to main content
This page tells you how to install the Gravity pixel and how to verify it. The Gravity pixel (gr-pix.js) is a script that records visits and sessions on your site. Gravity uses this data to connect ad impressions and clicks to real results.
Clicks are tracked automatically with UTM parameters, so Clicks campaigns need no tracking setup. Conversions and CPA campaigns need the Gravity pixel and a conversion event that passes the conversion event check. AI platforms install the pixel for attribution and payouts. Install it before you go live.
The pixel also creates a visitor ID and a session ID. When the pixel is on the page, gravityContext() in @gravity-ai/api adds these IDs to each ad request. See Request ads.

Before you start

  • You have a Gravity AI platform account.
  • You know your pixel ID. The dashboard shows the full snippet with your pixel ID in Settings > Tracking. The pixel ID is not your API key.

Web install

  1. Copy the snippet below. You can also copy it from Settings > Tracking, where it already has your pixel ID.
  2. Replace YOUR_PIXEL_ID with your pixel ID.
  3. Paste the snippet in the <head> of every page. Put it in your base template or layout, so that each page has it.
Settings > Tracking also has ready snippets for React and Next.js.
If you also advertise with Gravity on the same website, install one Pixel snippet only. See Use one Pixel for advertiser and publisher accounts.

Verify that the pixel works

  1. Open a page that has the pixel.
  2. Open the browser developer tools, and go to the Network tab.
  3. Find a request to code.trygravity.com/gr-pix.js. This is the pixel script.
  4. Find a POST request to api.trygravity.com/track/gr-events. This request sends the pixel events.
A 200 response to /track/gr-events tells you that Gravity received the events. The events can take some minutes to show in your dashboard.

In-app browser (WebView)

Do this install only if your app opens Gravity ad links in a WebView inside your app. Install the pixel in the WebView with the inAppBrowser: true setting. Then Gravity keeps the attribution when a user clicks an ad and opens the advertiser’s page in your app.
If your app opens ad links in the system browser (for example with UIApplication.shared.open(url)), you do not need this install. The web install is sufficient.
For each platform, add two scripts to the WebView:
  1. A configuration script that runs at document start. It sets window.GRAVITY_PIXEL_CONFIG with inAppBrowser: true and your pixel ID.
  2. The pixel script that runs at document end.
Settings > Tracking shows these snippets with your pixel ID.

Swift (iOS / iPadOS)

Add both scripts to the WKUserContentController before you create the WKWebView. A WKWebView copies its configuration when you create it, so scripts that you add after that time do not run.

React Native

This example uses react-native-webview.

Flutter

This example uses the flutter_inappwebview package.
App install ads send users to the App Store, usually through a mobile measurement partner (MMP) link such as Adjust, AppsFlyer, or Branch. On iOS, every App Store web link (https://apps.apple.com/...) redirects to the itms-appss:// scheme. A WebView cannot load that scheme, so the page fails to load and the user cannot install the app. To fix this, hand every URL with a non-web scheme (such as itms-appss://), and every apps.apple.com URL, to the operating system, and cancel the load in the WebView. This also covers server redirects, so MMP links still record the click before the App Store opens.
Without this handler, app install ads show an error page in your in-app browser. Users cannot install the app, and these clicks do not convert.
Swift
React Native
Flutter This example also uses the url_launcher package.

Troubleshoot

  • Make sure that the snippet is on the page, in the <head>.
  • In the Network tab, find the request to code.trygravity.com/gr-pix.js. If it is not there, a script blocker or a Content Security Policy can stop it.
  • Look for errors in the browser console. An error in a different script can stop the scripts that come after it.
  • Make sure that the pixel ID in the snippet is the same as the pixel ID in Settings > Tracking. The pixel ID is not your API key.
  • In the Network tab, find the POST requests to api.trygravity.com/track/gr-events. A 200 response tells you that Gravity received the events. The dashboard can take some minutes to show them.
  • On iOS, use the default WKWebsiteDataStore.default(). A .nonPersistent() data store does not keep cookies.
  • Make sure that you added the scripts before you created the WKWebView.
  • Make sure that the injected scripts run. Add a console.log to the injected script, and read it with WKScriptMessageHandler (Swift) or onMessage (React Native).

Next steps

Going live

The checklist to do before you set production: true.