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.
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
- Copy the snippet below. You can also copy it from Settings > Tracking, where it already has your pixel ID.
- Replace
YOUR_PIXEL_IDwith your pixel ID. - Paste the snippet in the
<head>of every page. Put it in your base template or layout, so that each page has it.
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
- Open a page that has the pixel.
- Open the browser developer tools, and go to the Network tab.
- Find a request to
code.trygravity.com/gr-pix.js. This is the pixel script. - Find a
POSTrequest toapi.trygravity.com/track/gr-events. This request sends the pixel events.
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 theinAppBrowser: true setting. Then Gravity keeps the attribution when a user clicks an ad and opens the advertiser’s page in your app.
For each platform, add two scripts to the WebView:
- A configuration script that runs at document start. It sets
window.GRAVITY_PIXEL_CONFIGwithinAppBrowser: trueand your pixel ID. - The pixel script that runs at document end.
Swift (iOS / iPadOS)
Add both scripts to theWKUserContentController 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 usesreact-native-webview.
Flutter
This example uses theflutter_inappwebview package.
Open App Store links outside the WebView
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.
Swift
url_launcher package.
Troubleshoot
The pixel does not load on a web page
The pixel does not load on a web page
- 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.
The pixel loads, but no events show in the dashboard
The pixel loads, but no events show in the dashboard
- 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
POSTrequests toapi.trygravity.com/track/gr-events. A200response tells you that Gravity received the events. The dashboard can take some minutes to show them.
App Store links show an error in the WebView
App Store links show an error in the WebView
- The App Store link redirects to
itms-appss://, which a WebView cannot load. Add the handler in Open App Store links outside the WebView.
No events from the WebView
No events from the WebView
- 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.logto the injected script, and read it withWKScriptMessageHandler(Swift) oronMessage(React Native).
Next steps
Going live
The checklist to do before you set
production: true.