Capacitor

Capacitor wraps a normal web app in a native WebView, so the snippet goes in the <head> of that web app's index.html and ships to iOS and Android with npx cap sync. If the app is built with Ionic Angular, React or Vue, follow the Angular, React or Vue guide for where the tag lives, then come back here for the WebView origin settings.

Get your tracking snippet

In your Rybbit dashboard, open Site Settings → Tracking Script and copy your snippet. It looks like this:

<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>

YOUR_SITE_ID is the numeric ID of your site. If you self-host Rybbit, app.rybbit.io is the domain of your own instance.

Add the snippet to Capacitor

Paste the snippet into the <head> of your web app's index.html (the file in the webDir folder from capacitor.config, after your framework's build):

index.html

<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>

Enable CapacitorHttp, which routes window.fetch through native HTTP. The iOS WebView runs on capacitor://localhost, and Rybbit's tracking endpoints answer CORS preflights for http:// and https:// origins only, so without this the browser blocks the requests on iOS:

capacitor.config.ts

import type { CapacitorConfig } from "@capacitor/cli";

const config: CapacitorConfig = {
  appId: "com.example.app",
  appName: "My App",
  webDir: "dist",
  plugins: {
    CapacitorHttp: {
      enabled: true,
    },
  },
};

export default config;

Build the web app, then copy it into the native projects:

npm run build
npx cap sync

Android serves the app from https://localhost (server.androidScheme defaults to https), which is a regular origin, so tracking works there with or without CapacitorHttp. In-app route changes are tracked automatically: the tracker wraps history.pushState and history.replaceState and listens for popstate and hashchange.

Use the script tag rather than the @rybbit/js npm package on Capacitor. The package sends events with navigator.sendBeacon, which CapacitorHttp does not patch, so its requests from capacitor://localhost are still blocked on iOS.

Verify installation

Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

If nothing shows up:

View the page source and search for script.js?siteId= to confirm the snippet is on the page.
Open the browser Network tab and check that script.js returns 200 and that POST requests go to /api/track.
Disable ad blockers, or set up a proxy so the script loads from your own domain.
See the script troubleshooting guide for other common causes.

Troubleshooting

Works on Android and in the browser, silent on iOS: CapacitorHttp is not enabled, or the native projects were not re-synced after changing the config. Run npx cap sync and rebuild in Xcode.
Changes do not appear on device: npx cap sync copies the built web bundle; edit the source, rebuild the web app, then sync again.
Live reload during development: with server.url pointing at your dev server the WebView loads an http:// origin, so requests succeed even without CapacitorHttp. Do not read a working dev build as proof that the production build is configured.
Every pageview shows localhost as hostname: expected. server.hostname defaults to localhost on both platforms; filter by site, not hostname.

Next steps

Track custom events such as signups, purchases and button clicks.
Identify users to connect sessions to accounts.
Proxy the script through your own domain to bypass ad blockers.
Script attributes let you skip or mask URLs and tag events.

Get your tracking snippet

Add the snippet to Capacitor

Verify installation

Troubleshooting

Next steps

On this page