React Web SDK Integration

The Kochava React Web SDK is a javascript-based solution that provides marketers with Web Tracking capabilities. It can be integrated with a variety of web-based frameworks; this document describes how to integrated with the React framework, as well as the derivative Gatsby. If you have already integrated the SDK and started it, please visit Using the SDK support document and choose a topic.

NOTE: If you are planning on using Next.js, please visit the Next.js integration support documentation.

NOTE: If migrating from a previous Kochava SDK javascript snippet, be sure to remove that integration snippet and migrate any Kochava SDK function calls as described below.

Integrating the SDK

Integration:

Estimated Time to Complete
5 Minutes

(Release Notes)

The Kochava Web SDK is available for React projects as a normal npm package. It provides a class called Kochava, which contains all necessary Kochava SDK functions and behavior.

1. Install the Kochava SDK via NPM by running npm install -D kochava@latest in the root of your project directory (where package.json is located). For more installation options, see our NPM Installation page.
2. After running the command above, confirm that kochava version 3.0.1 or later was added in your package json. At this point the SDK has been installed and is ready to use.

Starting the SDK

Estimated Time to Complete
1 Minute

In order for the SDK to start operating, the Kochava class must be instantiated one time with a valid configuration. However, React is a very open-ended framework full of derivatives, and so this can be accomplished many ways. Below is one example of how this can be done, but your implementation may vary depending on your architecture.

Once you have added the Kochava SDK to your project, the next step is to create and start the SDK class in code. Only your App GUID is required to start the SDK with the default settings, which is the case for typical integrations.

We recommend starting the SDK as soon as the application starts, although this can be done later if needed. Starting the tracker as early as possible will ensure it’s started before use, resulting in more accurate data/behavior.

Within your root component which calls ReactDOM.Render (usually a main or index file):

1. Import the Kochava class.
2. Create an instance of the Kochava class (we recommend calling it lower-case ‘kochava’).
3. (Optional) Make any desired pre-start configuration calls (registerIdentityLink, disableAutoPage, useCookies, etc).
4. Call startWithAppGuid using a valid Kochava App GUID.

Example (Start Kochava in the Root Component) —

import React from 'react';
import ReactDOM from 'react-dom';
import './index.css'
import App from './App';

// Import Kochava
import { Kochava } from 'kochava';

const KochavaSetup = () => {
  const kochava = Kochava.createForReact();

  // Optional pre-start calls would go here
  kochava.startWithAppGuid("YOUR_APP_GUID");

  return kochava;
};

ReactDOM.render(
  
    
  ,
  document.getElementById('root')
);

Replace YOUR_APP_GUID with your Kochava App GUID. For more information on locating your App GUID, refer to our Locating your App GUID support documentation.

Optional Configuration

From here on, the SDK is integrated and ready, the following configuration calls are optional, and are only for special desired SDK behavior. The following code snippets should be placed at in the above snippet, at the comment labeled Optional pre-start calls will go here.

import React from 'react';
import ReactDOM from 'react-dom';
import './index.css'
import App from './App';
 
// Import Kochava
import { Kochava } from 'kochava';
 
const KochavaSetup = () => {
  const kochava = Kochava.createForReact();
 
  // Auto pages will be sent (default)
  kochava.disableAutoPage(false);
 
  // Auto pages will not be sent
  kochava.disableAutoPage(true);
 
  kochava.startWithAppGuid("YOUR_APP_GUID");
 
  return kochava;
};
 
ReactDOM.render(
  <React.StrictMode>
    <App kochava={KochavaSetup()} />
  </React.StrictMode>,
  document.getElementById('root')
);

import React from 'react';
import ReactDOM from 'react-dom';
import './index.css'
import App from './App';
// Import Kochava
import { Kochava } from 'kochava';
 
const KochavaSetup = () => {
  const kochava = Kochava.createForReact();
 
  // Will not use cookies (default)
  kochava.useCookies(false);
 
  // Will use cookies
  kochava.useCookies(true);
 
  kochava.startWithAppGuid("YOUR_APP_GUID");
 
  return kochava;
};
 
ReactDOM.render(
  <React.StrictMode>
    <App kochava={KochavaSetup()} />
  </React.StrictMode>,
  document.getElementById('root')
);

React Examples

Example (Access Kochava from a Class Component) —

// App.js
import logo from './logo.svg';
import './App.css';
import React from 'react';
 
class App extends React.Component {
  render() {
    const kochava = props.kochava;
   
    // Example - access the kochava object to send a page event
    kochava.sendPageEvent();
    // Example - register and Identity Link
    kochava.registerIdentityLink("standalone", "idLink");
   
    return (
      <div className="App">
        <header className="App-header">
          <img src={logo} className="App-logo" alt="logo" />
          <p>
            Edit src/App.js and save to reload.
          </p>
          <a className="App-link" href="https://reactjs.org" target="_blank" rel="noopener noreferrer">
            Learn React
          </a>
        </header>
      </div>
    );
  }
}
 
export default App;

Example (Access Kochava from a Functional Component) —

// App.js
import logo from './logo.svg';
import './App.css';
 
function App(props) {
  const kochava = props.kochava;
 
  // Example - access the kochava object to send a page event
  kochava.sendPageEvent();
  // Example - register and Identity Link
  kochava.registerIdentityLink("standalone", "idLink");
 
  return (
    <div className="App">
      <header className="App-header">
        <img src={logo} className="App-logo" alt="logo" />
        <p>
          Edit src/App.js and save to reload.
        </p>
        <a className="App-link" href="https://reactjs.org" target="_blank" rel="noopener noreferrer">
          Learn React
        </a>
      </header>
    </div>
  );
}
 
export default App;

Confirm the Integration

After integrating the SDK and adding the code to start the measurement client, launch and run the app for at least 10 seconds or more. During this time the client will start and send an install payload to Kochava. To confirm integration was successful, visit the app’s Install Feed Validation page Apps & Assets > Install Feed Validation. On this page you should see one of two integration messages, indicating integration success or failure.

Integration Successful

Along with this message you will also see a variety of data points associated with the device used for testing. At this point your integration is successful and you can proceed to the next step(s).

NOTE: It may take a few minutes for the first install to appear within the Install Feed Validation page. If you do not see this message immediately, you may simply need to wait a few minutes and check again.

Integration Not Complete

If you encounter this message, please review the integration steps, uninstall and reinstall the app, and check again.

SDK WAYPOINT: At this point basic integration is complete and the Kochava SDK will begin reporting session activity and attributing installs.

Where to Go From Here:

Now that you have completed integration you are ready to utilize the many features offered by the Kochava SDK. Continue on to Using the SDK and choose a topic.