Introduction

Convrs is a lightweight website analytics platform built for modern SaaS products.

Add a single script to your website and start tracking visitors, pageviews, conversions, custom events, and revenue attribution in real time.

Quick Start

Get started with Convrs in under two minutes.

1. Create a Website

Create a website in your Convrs dashboard and copy your Website ID.

2. Add the Script

Paste the script into your website's <head> or before the closing </body> tag.

<script
  async
  src="https://cdn.convrs.dev/script.js"
  data-website-id="YOUR_WEBSITE_ID">
</script>

3. Open Your Dashboard

Visit your Convrs dashboard and start exploring your analytics.

Data typically appears within a few seconds of the first pageview.

Replace YOUR_WEBSITE_ID with the Website ID from your Convrs dashboard.

HTML & Vanilla JS

The simplest installation — add the Convrs tracking script anywhere in your HTML.

<!DOCTYPE html>
<html>
  <head>
    <title>My Site</title>

    <!-- Convrs Analytics -->
    <script
      async
      src="https://cdn.convrs.dev/script.js"
      data-website-id="YOUR_WEBSITE_ID">
    </script>
  </head>

  <body>
    <!-- Your content -->
  </body>
</html>

Using async ensures the script never blocks page rendering.

Next.js

Use the built-in Next.js Script component so Convrs loads with the correct strategy.

App Router (Next.js 13+)

Add this to your app/layout.tsx:

import Script from 'next/script';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}

        <Script
          src="https://cdn.convrs.dev/script.js"
          data-website-id="YOUR_WEBSITE_ID"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

Pages Router

Add this to pages/_app.tsx:

import Script from 'next/script';
import type { AppProps } from 'next/app';

export default function App({
  Component,
  pageProps,
}: AppProps) {
  return (
    <>
      <Component {...pageProps} />

      <Script
        src="https://cdn.convrs.dev/script.js"
        data-website-id="YOUR_WEBSITE_ID"
        strategy="afterInteractive"
      />
    </>
  );
}

Convrs automatically tracks client-side route changes in Next.js.

React (Vite / CRA)

Install Convrs in your React application to start tracking pageviews, visitors, and custom events automatically.

Option A — index.html (Recommended)

The simplest approach is to add the Convrs script directly to your index.html file.

Vite

<!-- index.html -->

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>My App</title>
  </head>

  <body>
    <div id="root"></div>

    <script
      async
      src="https://cdn.convrs.dev/script.js"
      data-website-id="YOUR_WEBSITE_ID">
    </script>

    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

Create React App

<!-- public/index.html -->

<body>
  <div id="root"></div>

  <script
    async
    src="https://cdn.convrs.dev/script.js"
    data-website-id="YOUR_WEBSITE_ID">
  </script>
</body>

Option B — Load via useEffect

If you prefer to load Convrs dynamically, add the script once when your application mounts.

import { useEffect } from 'react';

export default function App() {
  useEffect(() => {
    const script = document.createElement('script');

    script.src = 'https://cdn.convrs.dev/script.js';
    script.async = true;

    script.setAttribute(
      'data-website-id',
      'YOUR_WEBSITE_ID'
    );

    document.head.appendChild(script);

    return () => {
      document.head.removeChild(script);
    };
  }, []);

  return <div>Your App</div>;
}

Vue.js

index.html (Recommended)

<body>
  <div id="app"></div>

  <script
    async
    src="https://cdn.convrs.dev/script.js"
    data-website-id="YOUR_WEBSITE_ID">
  </script>

  <script type="module" src="/src/main.ts"></script>
</body>

App.vue

<script setup>
import { onMounted } from 'vue';

onMounted(() => {
  const script = document.createElement('script');

  script.src = 'https://cdn.convrs.dev/script.js';
  script.async = true;

  script.setAttribute(
    'data-website-id',
    'YOUR_WEBSITE_ID'
  );

  document.head.appendChild(script);
});
</script>

<template>
  <RouterView />
</template>

Convrs automatically tracks Vue Router navigation.

Nuxt.js

Use Nuxt's built-in head management to load Convrs on every page.

nuxt.config.ts (Recommended)

export default defineNuxtConfig({
  app: {
    head: {
      script: [
        {
          src: 'https://cdn.convrs.dev/script.js',
          'data-website-id': 'YOUR_WEBSITE_ID',
          async: true,
        },
      ],
    },
  },
});

app.vue

<script setup>
useHead({
  script: [
    {
      src: 'https://cdn.convrs.dev/script.js',
      'data-website-id': 'YOUR_WEBSITE_ID',
      async: true,
    },
  ],
});
</script>

<template>
  <NuxtPage />
</template>

Convrs automatically tracks Nuxt route changes.

SvelteKit

Add the Convrs script to your root layout.

<!-- src/routes/+layout.svelte -->

<svelte:head>
  <script
    async
    src="https://cdn.convrs.dev/script.js"
    data-website-id="YOUR_WEBSITE_ID">
  </script>
</svelte:head>

<slot />

Convrs automatically tracks client-side navigation and page changes.

Remix

Add Convrs to your root application layout.

import {
  Links,
  Meta,
  Outlet,
  Scripts,
  ScrollRestoration,
} from "@remix-run/react";

export default function App() {
  return (
    <html lang="en">
      <head>
        <Meta />
        <Links />

        <script
          async
          src="https://cdn.convrs.dev/script.js"
          data-website-id="YOUR_WEBSITE_ID"
        />
      </head>

      <body>
        <Outlet />
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  );
}

Convrs automatically tracks route transitions in Remix applications.

Astro

Add Convrs to your base layout.

---
---
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />

    <script
      async
      src="https://cdn.convrs.dev/script.js"
      data-website-id="YOUR_WEBSITE_ID">
    </script>

    <slot name="head" />
  </head>

  <body>
    <slot />
  </body>
</html>

If you're using Astro View Transitions, add transition:persist to the script tag to prevent reinitialization.

Gatsby

Install Convrs globally using Gatsby SSR APIs.

gatsby-ssr.js

import React from "react";

export const onRenderBody = ({
  setHeadComponents,
}) => {
  setHeadComponents([
    <script
      key="convrs"
      async
      src="https://cdn.convrs.dev/script.js"
      data-website-id="YOUR_WEBSITE_ID"
    />,
  ]);
};

gatsby-browser.js

// Convrs automatically tracks route changes.
// No additional setup is required.

Gatsby uses the History API, which Convrs tracks automatically.

WordPress

There are two ways to install Convrs on WordPress.

Option A — functions.php

function convrs_analytics_script() {
    echo '<script async src="https://cdn.convrs.dev/script.js" data-website-id="YOUR_WEBSITE_ID"></script>';
}

add_action('wp_head', 'convrs_analytics_script');

Option B — Plugin

Install a plugin such as:

Insert Headers and Footers
WPCode

Then paste:

<script
  async
  src="https://cdn.convrs.dev/script.js"
  data-website-id="YOUR_WEBSITE_ID">
</script>

into the Header section.

If you're using caching plugins such as WP Rocket or W3 Total Cache, ensure the script remains present in cached pages.

Webflow

Webflow allows custom code to be added globally across your site.

Installation

Open your Webflow project.
Click Project Settings.
Open the Custom Code tab.
Paste the following into Head Code:

<script
  async
  src="https://cdn.convrs.dev/script.js"
  data-website-id="YOUR_WEBSITE_ID">
</script>

Save changes.
Republish your website.

Convrs will immediately begin tracking pageviews once your site is published.

Shopify

Install Convrs across your entire Shopify storefront.

Installation

Open your Shopify Admin.
Navigate to Online Store → Themes.
Select Actions → Edit Code.
Open layout/theme.liquid.
Paste the following before the closing </head> tag:

<script
  async
  src="https://cdn.convrs.dev/script.js"
  data-website-id="YOUR_WEBSITE_ID">
</script>

Save the file.

Convrs automatically tracks storefront pages including product pages, collection pages, cart pages, and landing pages.

Convrs does not track activity inside the Shopify Admin dashboard.

NPM SDK

Install Convrs as an npm package for type-safe analytics tracking in JavaScript and TypeScript applications.

Perfect for React, Next.js, Vue, Nuxt, SvelteKit, Remix, Astro, and other modern web frameworks.

Why use the SDK?

TypeScript support
Framework agnostic
Automatic pageview tracking
User identification
Offline-ready

Installation

npm install @convrs/sdk

Quick Start

import { initConvrs } from "@convrs/sdk";

const convrs = await initConvrs({
  websiteId: "YOUR_WEBSITE_ID",
});

Track Events

convrs.track("signup", {
  source: "homepage",
});

Identify Users

convrs.identify("user_123", {
  email: "user@example.com",
  plan: "pro",
});

React / Next.js Example

lib/analytics.ts

import { initConvrs } from "@convrs/sdk";

let convrs: any = null;

export async function getAnalytics() {
  if (!convrs) {
    convrs = await initConvrs({
      websiteId:
        process.env.NEXT_PUBLIC_CONVRS_WEBSITE_ID!,
      autoCapturePageviews: true,
    });
  }

  return convrs;
}

Automatic Pageview Tracking

const convrs = await initConvrs({
  websiteId: "YOUR_WEBSITE_ID",
  autoCapturePageviews: true,
});

Configuration Options

Option	Type	Description
`websiteId`	string	Your Convrs website ID
`domain`	string	Override the current hostname
`apiUrl`	string	Custom ingestion endpoint
`debug`	boolean	Enable debug logging
`allowLocalhost`	boolean	Enable localhost tracking
`allowIframe`	boolean	Enable tracking inside iframes
`allowedHostnames`	string[]	Domains used for cross-domain tracking

Example Configuration

const convrs = await initConvrs({
  websiteId: "YOUR_WEBSITE_ID",
  debug: true,
  allowLocalhost: true,

  autoCapturePageviews: {
    trackHashChanges: true,
  },
});

See the API Reference for track(), identify(), trackPageview(), flush(), reset(), and cross-domain tracking.

Script Options

The Convrs tracking script accepts several optional data-* attributes to customize its behavior.

Attribute	Required	Description
`data-website-id`	Yes	Your unique Website ID from the Convrs dashboard.
`data-api`	No	Override the default tracking endpoint. Useful for custom domains, proxies, or self-hosted ingestion.
`data-debug`	No	Enable debug logging in the browser console.
`data-allow-localhost`	No	Enable tracking while running on localhost.

Example

<script
  async
  src="https://cdn.convrs.dev/script.js"
  data-website-id="YOUR_WEBSITE_ID"
  data-api="https://analytics.yourdomain.com/api/track"
  data-debug="true"
  data-allow-localhost="true"
  data-allow-file-protocol="true">
</script>

Only data-website-id is required. All other attributes are optional and should only be used when needed.

API Reference

The Convrs SDK exposes a simple API for tracking events, pageviews, and user identification.

track()

Track a custom event.

Syntax

convrs.track(eventName, properties?)

Parameters

Parameter	Type	Description
`eventName`	string	Name of the event.
`properties`	object	Optional event metadata.

Examples

convrs.track("signup");

convrs.track("purchase", {
  amount: 99,
  currency: "USD",
  plan: "Pro",
});

identify()

Associate events with a user.

Syntax

convrs.identify(userId, traits?)

Parameters

Parameter	Type	Description
`userId`	string	Unique identifier for the user.
`traits`	object	Optional user attributes.

Examples

convrs.identify("user_123");

convrs.identify("user_123", {
  email: "user@example.com",
  name: "John Doe",
  plan: "Pro",
});

trackPageview()

Manually track a pageview.

Most applications do not need this because pageviews are tracked automatically when autoCapturePageviews is enabled.

Track Current Page

convrs.trackPageview();

Track Custom Path

convrs.trackPageview("/pricing");

flush()

Immediately send all queued events.

Syntax

await convrs.flush();

Example

await convrs.flush();

Useful before:

Page unloads
Checkout redirects
Critical conversion events

reset()

Reset the current visitor and session.

Syntax

convrs.reset();

Example

function logout() {
  convrs.reset();
}

Useful when a user logs out.

getConvrsClient()

Access the initialized Convrs client anywhere in your application.

Syntax

import { getConvrsClient } from "@convrs/sdk";

const convrs = getConvrsClient();

Example

import { getConvrsClient } from "@convrs/sdk";

const convrs = getConvrsClient();

convrs.track("feature_used");

buildCrossDomainUrl()

Generate a URL containing Convrs tracking parameters.

Syntax

convrs.buildCrossDomainUrl(url);

Example

const url = convrs.buildCrossDomainUrl(
  "https://app.example.com/signup"
);

Result:

https://app.example.com/signup?_cv_vid=xxx&_cv_sid=xxx

getTrackingParams()

Retrieve the current visitor and session identifiers.

Syntax

const params = convrs.getTrackingParams();

Example

const params = convrs.getTrackingParams();

console.log(params);

Result:

{
  visitorId: "visitor_123",
  sessionId: "session_456"
}

Complete Example

import { initConvrs } from "@convrs/sdk";

const convrs = await initConvrs({
  websiteId: "YOUR_WEBSITE_ID",
});

convrs.identify("user_123", {
  plan: "Pro",
});

convrs.track("signup");

convrs.track("purchase", {
  amount: 99,
  currency: "USD",
});

await convrs.flush();

Tracking Events

Beyond automatic pageview tracking, Convrs lets you send custom events to measure important user actions throughout your application.

Custom events can be used to track:

Signups
Purchases
Feature usage
Form submissions
Button clicks
Checkout flow events
Marketing conversions

All custom events appear in your Convrs dashboard and can be used for funnels, conversion tracking, and revenue attribution.

Syntax

window.convrs(eventName, properties)

Parameter	Type	Description
`eventName`	string	Name of the event to track.
`properties`	object	Optional metadata associated with the event.

Event names should be descriptive and consistent. Examples: signup, purchase, invite_sent, checkout_started.

Event Examples

Button Click

<button onclick="window.convrs('cta_clicked', { location: 'hero' })">
  Get Started
</button>

Form Submission

document
  .querySelector('#signup-form')
  .addEventListener('submit', () => {
    window.convrs('signup_submitted');
  });

React — Button Click

function UpgradeButton() {
  function handleClick() {
    window.convrs('upgrade_clicked', {
      plan: 'pro',
      source: 'pricing_page',
    });

    // Open checkout
  }

  return (
    <button onClick={handleClick}>
      Upgrade to Pro
    </button>
  );
}

E-commerce — Add to Cart

window.convrs('add_to_cart', {
  product_id: 'sku_1234',
  product_name: 'Wireless Headphones',
  price: 79.99,
  currency: 'USD',
});

Purchase Completed

window.convrs('purchase', {
  order_id: 'order_123',
  amount: 99,
  currency: 'USD',
  plan: 'pro',
});

Video Played

document
  .querySelector('#hero-video')
  .addEventListener('play', () => {
    window.convrs('video_played', {
      video: 'hero_demo',
    });
  });

Checkout Started

window.convrs('checkout_started', {
  plan: 'pro',
  billing_cycle: 'monthly',
});

Invite Sent

window.convrs('invite_sent', {
  team_size: 5,
});

Event Properties

Properties provide additional context for an event.

window.convrs('signup', {
  plan: 'pro',
  source: 'pricing_page',
  campaign: 'summer_launch',
});

These properties can be used to better understand user behavior and conversion patterns.

Best Practices

Use lowercase event names.
Use snake_case for event names.
Keep event names consistent across your application.
Attach meaningful properties to important events.
Avoid sending sensitive user information.

Good examples:

window.convrs('signup');
window.convrs('checkout_started');
window.convrs('purchase');
window.convrs('invite_sent');

Avoid:

window.convrs('Clicked Button');
window.convrs('Event 1');
window.convrs('test');

Convrs automatically tracks pageviews and route changes. Custom events should be used for actions that represent meaningful user behavior.

Stripe Revenue Attribution

Connect Stripe with Convrs to attribute revenue back to the campaigns, traffic sources, and visitors that generated it.

Once connected, Convrs automatically links successful payments to the original visitor and session, allowing you to see which channels, campaigns, and pages generate revenue.

How It Works

A visitor lands on your website.
Convrs assigns a unique visitor and session ID.
You pass those IDs to Stripe when creating a checkout session or payment intent.
Stripe sends the payment data to Convrs.
Convrs attributes revenue to the original visitor, campaign, and traffic source.

Required Metadata

When creating a payment, include the following metadata:

Key	Description
`convrs_visitor_id`	Unique visitor identifier assigned by Convrs.
`convrs_session_id`	Session identifier assigned by Convrs.

These values allow Convrs to connect a Stripe payment to the visitor who originally started the journey.

Stripe Checkout

If you're using Stripe Checkout, include the Convrs identifiers in the checkout session metadata.

const session = await stripe.checkout.sessions.create({
  line_items: [
    {
      price: "price_123",
      quantity: 1,
    },
  ],

  mode: "payment",

  success_url: "https://yourapp.com/success",
  cancel_url: "https://yourapp.com/cancel",

  metadata: {
    convrs_visitor_id: visitorId,
    convrs_session_id: sessionId,
  },
});

Payment Intents

For custom checkout flows, pass the identifiers when creating the payment intent.

const paymentIntent =
  await stripe.paymentIntents.create({
    amount: 5000,
    currency: "usd",

    metadata: {
      convrs_visitor_id: visitorId,
      convrs_session_id: sessionId,
    },
  });

Getting Visitor Information

If you're using the Convrs SDK, retrieve the tracking identifiers before creating the checkout session.

const tracking =
  convrs.getTrackingParams();

console.log(tracking);

Example response:

{
  visitorId: "visitor_123",
  sessionId: "session_456"
}

Recommended Flow

Visitor arrives
       ↓
Convrs creates visitor + session
       ↓
User starts checkout
       ↓
Pass IDs to Stripe metadata
       ↓
Payment succeeds
       ↓
Revenue appears in Convrs

Verify Revenue Attribution

After a successful payment, open your Convrs dashboard and navigate to:

Revenue Attribution → Payments

You should see:

Revenue amount
Customer information
Original traffic source
Campaign attribution
Landing page
Visitor journey

Revenue attribution works for one-time payments, subscriptions, upgrades, and renewals as long as the Convrs identifiers are included in the Stripe metadata.