JavaScript client for popular frameworks

Updated

If you want to install our client-side library as a package—rather than using our JavaScript snippet—you’ll use our @customerio/cdp-analytics-browser package. This guide covers installation for popular JavaScript frameworks.

Client-side vs. server-side

The instructions on this page are for client-side implementations. In general, we prefer the client-side library to support things like in-app messaging and automatic page tracking. But, if you need to use a server-side implementation, see our Node.js library.

FeatureBrowser LibraryNode.js Library
Package@customerio/cdp-analytics-browser@customerio/cdp-analytics-node
Page contextAutomatic: captured from DOMManual: you must provide URL, path, etc.
Identity persistenceAutomatic: stored in cookies/localStorageManual: you must pass userId or anonymousId on every call
In-app message support
Use forClient-side tracking, single page applications (SPAs), in-app messagesServer-side tracking, API routes, background jobs

React

For React-based applications, you’ll want to create a singleton instance of the analytics client that you can import throughout your app. This prevents you from initializing the library multiple times and ensures consistent tracking.

  1. Go to Data & Integrations > Integrations. In the Connections tab, pick the JavaScript integration to get your Write Key.

  2. Install the package:

    npm install @customerio/cdp-analytics-browser

  3. Create an analytics module (for example, src/analytics.js):

    import { AnalyticsBrowser } from '@customerio/cdp-analytics-browser';

export const cioanalytics = AnalyticsBrowser.load({
  // cdnURL: 'https://cdp-eu.customer.io', // Set if you're in our EU data center
  writeKey: '<YOUR_WRITE_KEY>'
});

  4. Import and use the analytics instance in your components:

    import { cioanalytics } from './analytics';

function SignupButton() {
  const handleClick = () => {
    cioanalytics.track('Signup Started');
  };

  return <button onClick={handleClick}>Sign Up</button>;
}

Track page views in React

If you use client-side routing (like React Router), you’ll need to track page views manually when routes change. For example, here’s how you might track page views in React Router:

import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';
import { cioanalytics } from './analytics';

function usePageTracking() {
  const location = useLocation();

  useEffect(() => {
    cioanalytics.page();
  }, [location]);
}

// Use in your App component
function App() {
  usePageTracking();

  return (
    // your app content
  );
}

Next.js

Next.js supports both client-side and server-side rendering. For client-side tracking, you’ll use the browser library with the 'use client' directive.

If you want to use the server-side library, see our Node.js library instructions.

  1. Go to Data & Integrations > Integrations. In the Connections tab, pick the JavaScript integration to get your Write Key.

  2. Install the package:

    npm install @customerio/cdp-analytics-browser

  3. Create an analytics component in ./components/analytics.js (or .tsx for TypeScript):

    'use client';

import { AnalyticsBrowser } from '@customerio/cdp-analytics-browser';

export const cioanalytics = AnalyticsBrowser.load({
  // cdnURL: 'https://cdp-eu.customer.io', // Set if you're in our EU data center
  writeKey: '<YOUR_WRITE_KEY>'
});

export default function Analytics() { return null; }

  4. Load this component in your ./app/layout.tsx file so it initializes on every page:

    import Analytics from '../components/analytics'

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

  5. Use the analytics instance in your pages:

    import { cioanalytics } from '../components/analytics'

export default function Home() {
  return (
    <main>
      <button onClick={() => cioanalytics.track('Button Clicked')}>
        Track Event
      </button>
    </main>
  )
}

Track page views in Next.js

Next.js uses client-side routing. To track page views on route changes, you can use usePathname and useSearchParams. You might create a component like this and add it to your layout alongside the Analytics component.

'use client';

import { usePathname, useSearchParams } from 'next/navigation';
import { useEffect } from 'react';
import { cioanalytics } from './analytics';

export function PageTracker() {
  const pathname = usePathname();
  const searchParams = useSearchParams();

  useEffect(() => {
    cioanalytics.page();
  }, [pathname, searchParams]);

  return null;
}

Vue.js

In Vue.js, you can expose the analytics instance as a global property so it’s available in all components.

  1. Go to Data & Integrations > Integrations. In the Connections tab, pick the JavaScript integration to get your Write Key.

  2. Install the package:

    npm install @customerio/cdp-analytics-browser

  3. Add the following code to your main.js file (or your application’s entry point):

    import { createApp } from 'vue'
import App from './App.vue'
import { AnalyticsBrowser } from '@customerio/cdp-analytics-browser'

const app = createApp(App)

app.config.globalProperties.$cioanalytics = AnalyticsBrowser.load({
  // cdnURL: 'https://cdp-eu.customer.io', // Set if you're in our EU data center
  writeKey: '<YOUR_WRITE_KEY>'
});

app.mount('#app')

  4. Use $cioanalytics in your components:

    <template>
  <button @click="$cioanalytics.track('Button Clicked')">Track Event</button>
</template>

Track page views in Vue.js

If you use Vue Router for client-side navigation, track page views using navigation guards:

import { createRouter, createWebHistory } from 'vue-router'

const router = createRouter({
  history: createWebHistory(),
  routes: [/* your routes */]
})

router.afterEach((to) => {
  // Access the global property from the app instance
  app.config.globalProperties.$cioanalytics.page({
    name: to.name,
    path: to.path
  });
})

Listening for in-app message events

If you want to send in-app messages and respond to user interactions, add the integrations object when initializing the library. You can find the Site ID in > Workspace Settings > API and Webhooks Credentials > Tracking API Keys.

import { AnalyticsBrowser } from '@customerio/cdp-analytics-browser'

const cioanalytics = AnalyticsBrowser.load(
  {
    writeKey: '<YOUR_WRITE_KEY>',
  },
  { 
    integrations: {
      'Customer.io In-App Plugin': {
        siteId: '<YOUR_SITE_ID>',
        events: (e) => {
          switch (e.type) {
            case "in-app:message-opened":
              // do something when a message is opened
              break;
            case "in-app:message-dismissed":
              // do something when a message is dismissed
              break;
            case "in-app:message-action":
              // do something when a message is interacted with
              break;
            case "in-app:message-error":
              // do something when a message errors
              break;
            case "in-app:message-changed":
              // do something when a user moves to the next step
              break;
          }
        }
      }
    }
  }
);

Tracking page views

When you use the JavaScript snippet, we automatically send a page() call on every page load. If you use client-side routing, as many of the frameworks on this page do, you’ll need to send your own page() calls when routes change.

The browser library automatically enriches page() calls with:

  • path: The URL path
  • referrer: The previous page URL
  • search: Query string parameters
  • title: The page title
  • url: The full page URL

You can override any of these values by passing them explicitly.

cioanalytics.page('Category', 'Page Name', {
  title: 'Custom Title',
  url: 'https://example.com/custom-path'
});

Set the cdnURL if you’re in our EU data center

If you’re in our EU data center, set the cdnURL parameter to use our EU regional endpoint.

import { AnalyticsBrowser } from '@customerio/cdp-analytics-browser'

const cioanalytics = AnalyticsBrowser.load({
  cdnURL: 'https://cdp-eu.customer.io',
  writeKey: '<YOUR_WRITE_KEY>'
});
Copied to clipboard!
  Contents