Installation

Add Ripples.sh 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.
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>

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.