Installation

Add Ripples Metrics to your site in under a minute. Works with any framework or static site.

Script tag

The simplest way to install. Add this to your HTML <head>:

<script
    defer
    data-token="YOUR_TOKEN"
    src="https://cdn.ripples.sh/v.js"
></script>

Script attributes

Attribute	Description
`data-token` required	Your project token. Found in your dashboard under the install snippet.
`data-endpoint` optional	Override the default collection endpoint. Useful for self-hosted setups or proxying through your own domain.
`data-platform` optional	Override the detected platform (e.g. `ios`, `android`). Used when loading the script inside a native webview. The script auto-detects Capacitor, React Native, Flutter, Electron, and Tauri — use this attribute only for custom containers.
`data-sdk-name` optional	Override the detected SDK name (e.g. `capacitor`, `react-native`). Auto-detected for most popular frameworks — use this attribute only for custom integrations.
`data-app-name` optional	Native app name to display instead of the WebView browser name. Read it from the native bundle at runtime; for Capacitor, use `App.getInfo().name`.
`data-app-version` optional	Bundled native app version to display instead of the WebView browser version. For Capacitor, use `App.getInfo().version`.
`defer` optional	Recommended. Loads the script without blocking page render.

Next.js

Add the script in your root layout:

import Script from 'next/script'

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <Script
          src="https://cdn.ripples.sh/v.js"
          data-token="YOUR_TOKEN"
          strategy="afterInteractive"
        />
      </head>
      <body>{children}</body>
    </html>
  )
}

React (Vite / CRA)

Add to your index.html:

<!DOCTYPE html>
<html>
  <head>
    <!-- other tags -->
    <script defer data-token="YOUR_TOKEN" src="https://cdn.ripples.sh/v.js"></script>
  </head>
  <body>
    <div id="root"></div>
  </body>
</html>

SPA routing is handled automatically. The script listens to history.pushState and popstate events, so pageviews are tracked on every route change. No extra setup needed.

Vue / Nuxt

For Nuxt 3, add to your nuxt.config.ts:

export default defineNuxtConfig({
  app: {
    head: {
      script: [
        {
          src: 'https://cdn.ripples.sh/v.js',
          defer: true,
          'data-token': 'YOUR_TOKEN',
        },
      ],
    },
  },
})

Astro

Add to your base layout component:

<html>
  <head>
    <script
      defer
      data-token="YOUR_TOKEN"
      src="https://cdn.ripples.sh/v.js"
    ></script>
  </head>
  <body>
    <slot />
  </body>
</html>

Laravel / Blade

Add to your main layout file:

<head>
    <!-- other tags -->
    <script defer data-token="YOUR_TOKEN" src="https://cdn.ripples.sh/v.js"></script>
</head>

Native webview (Capacitor, React Native, etc.)

When your web app runs inside a native webview, the script auto-detects the SDK and platform for the most popular frameworks:

Framework	SDK name	Platform
Capacitor	`capacitor`	`ios` or `android` (from Capacitor API)
React Native WebView	`react-native`	—
Flutter InAppWebView	`flutter`	—
Electron	`electron`	—
Tauri	`tauri`	—

If the platform can’t be auto-detected (e.g. React Native only exposes the bridge, not the OS), set it explicitly:

<script defer
  data-token="YOUR_TOKEN"
  data-platform="ios"
  data-sdk-name="react-native"
  src="https://cdn.ripples.sh/v.js"
></script>

Or when injecting the script programmatically in Capacitor, read the app name and bundled version before appending the tag. Ripples maps them to the same browser / browser_version fields used by the native iOS SDK:

import { App } from '@capacitor/app';
import { Capacitor } from '@capacitor/core';

const app = await App.getInfo();
const script = document.createElement('script');
script.defer = true;
script.src = 'https://cdn.ripples.sh/v.js';
script.dataset.token = 'YOUR_TOKEN';
script.dataset.platform = Capacitor.getPlatform(); // 'ios' or 'android'
script.dataset.sdkName = 'capacitor';
script.dataset.appName = app.name;
script.dataset.appVersion = app.version;
document.head.appendChild(script);

Bot detection is adapted automatically. Browser-specific signals (plugins, Chrome API, Notification API) are skipped when a native container is detected, preventing false positives.

Verify installation

After adding the script, open your site and check the browser’s Network tab. You should see a POST request to api.ripples.sh/collect. Your dashboard will start showing data within seconds.

Loading before the script is ready

If you need to call SDK methods (like ripples.track()) before the script has loaded, use the queue pattern:

<script>
  // Queue commands before the SDK loads
  window.ripples = window.ripples || function() {
    (window.ripples.q = window.ripples.q || []).push(arguments);
  };
</script>
<script defer data-token="YOUR_TOKEN" src="https://cdn.ripples.sh/v.js"></script>

Any calls made before the SDK loads will be replayed automatically once it initializes.