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 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 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 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