Integration with React

No doubt that, React is one of the most famous frontend frameworks nowadays. As Metricalp, we are happy to have an official integration library for React and NextJS. If you are using NextJS, please check NextJS integration docs. If you are using React, you are in the right place. Let's start!

Our integration library in NPM, which name is @metricalp/react

Installation

You can install it as:

yarn add @metricalp/react

or

npm install @metricalp/react

Integration

In your app's top level src/index.js | src/main.tsx(Vite) | App.js, wrap your app with MetricalpReactProvider. Then give your tid (a.k.a TrackerID) as prop to provider. Basically this is all, Metricalp will start to collect all visit events and route change events automatically. But you can customize behaviours with props. We will explain all.

Example (Vite bootstrapped React project)

In src/main.tsx import library import { MetricalpReactProvider } from '@metricalp/react';. Then wrap your app with <MetricalpReactProvider allowLocalhost tid="YOUR_TID">

DON'T FORGET to replace tid prop with your tid.

We added allowLocalhost because defaultly Metricalp does not work in localhost to protect your quota limits. We allowed localhost for testing purposes. You would want to remove it after testing it once to save your quota. For detailed info check allow localhost & exclude me docs.

Code example

        import React from 'react';
        import ReactDOM from 'react-dom/client';
        import { MetricalpReactProvider } from '@metricalp/react';
        import './index.css';
        import { App } from './App.tsx';
        
        ReactDOM.createRoot(document.getElementById('root')!).render(
          <React.StrictMode>
            <MetricalpReactProvider allowLocalhost tid="YOUR_TID">
              <App />
            </MetricalpReactProvider>
          </React.StrictMode>
        );

USAGE

If you integrated library with your app, it automatically starts to tracking screen_view events. Metricalp listens for window.history changes and creates screen_view event on every path change defaultly. So, if you want to track only screen views then your app is ready just after integration. You do not need to do anything extra. But if you want to produce custom events or disable auto route tracking and you will create screen_view events manually then follow this section.

Produce Events

You have two options to produce Metricalp events with this library. A hook or direct function call.

Event produce with Hook

        import { useMetricalp } from '@metricalp/react';

        export default function MyComponent() {
          // Call hook to get the metricalp event function
          const metricalpEvent = useMetricalp();
        
          return (
            <div>
              <button
                onClick={() => {
                  metricalpEvent({ type: 'click_test_button', custom_prop1: 'hook' });
                }}>
                Click me
              </button>
            </div>
          );
        }

Event produce with Direct function call

Sometimes (outside of components) you can not call hooks in React. Then you can import direct event trigger function from Metricalp.

        import { metricalpEvent } from "@metricalp/react";

        export default function MyComponent() {
        
          return (
            <div>
              <button
                onClick={() => {
                  metricalpEvent({ type: 'click_test_button', custom_prop1: 'direct' });
                }}
              >
                Click me
              </button>
            </div>
          );
        }

It is totally up to you prefer hook or direct function call in your whole app. You can decide about usage of only one or you can use both depending usage place. In above examples we produce custom events with custom props. In your metricalp dashboard you can set custom_prop aliases then you can use directly that key in events. Like: metricalpEvent({ type: 'click_test_button', user_role: 'admin' }); here we defined user_role as alias of custom_prop1 in Tracker Settings and now we are producing it in events directly.

Customize behaviours with Props

<MetricalpReactProvider
    allowLocalhost
    tid="mam123456"
    initialSharedCustomProps={{
      _global: { custom_prop3: "v1.0" },
      screen_view: { color: 'red', custom_prop2: 'Test' } 
  }}>