Next.js Web SDK Integration

Integrating the SDK

Requirements:

• NodeJs
• NPM

Supported Platforms:

• Next.js

Data Privacy:

• SDK Data Privacy and Safety

Integration:

Estimated Time to Complete

5 Minutes

(Release Notes)

The Kochava SDK is available for Next.js 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 once with a valid configuration. Because Next.js handles rendering on the server, the Kochava SDK must be explicitly called in-browser. Below is the recommended example for how to start the SDK.

Once you have added the Kochava SDK to your project, the next step is to create and start the SDK 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 it 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 App component (_app.js), use the State and Effect hooks to create a variable to hold the kochava instantiation, then import kochava into a temporary variable and call startWithAppGuid using a valid Kochava App GUID. Load the temporary kochava object into the kochava variable, and then pass this object, via props, to the pages you’d like to gather data from.

NOTE: Before accessing the object in subsequent components, be sure to verify that you are in-browser. The SDK will fail if executed on the server.

NOTE: Do not import kochava at the top of the file. This will cause the code to execute on the server.

Example — (Start Kochava in the Root Component)

import { useState, useEffect } from 'react'
 
function MyApp({ Component, pageProps }) {
 const [kochava, setKochava] = useState(null)
 
 useEffect(() => {
  ( async () => {
    if(typeof window !== "undefined" && !kochava){
       const {Kochava} = (await import('kochava'))
       let kochavaLocal = Kochava.createForReact();
 
       // Optional pre-start calls would go here
       kochavaLocal.startWithAppGuid("YOUR_APP_GUID")
       setKochava(kochavaLocal);
   }
   })()
 }, [kochava])
 
 return <Component {...{...pageProps, kochava: kochava}} />
}
 
export default MyApp

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 { useState, useEffect } from 'react'
 
function MyApp({ Component, pageProps }) {
 const [kochava, setKochava] = useState(null)
 
 useEffect(() => {
  ( async () => {
    if(typeof window !== "undefined" && !kochava){
       const {Kochava} = (await import('kochava'))
       let kochavaLocal = Kochava.createForReact();
 
       // Auto pages will be sent (default)
       kochava.disableAutoPage(false);
 
       // Auto pages will not be sent
       kochava.disableAutoPage(true);
       
       kochavaLocal.startWithAppGuid("YOUR_APP_GUID")
       setKochava(kochavaLocal);
   }
   })()
 }, [kochava])
 
 return <Component {...{...pageProps, kochava: kochava}} />
}
 
export default MyApp

import { useState, useEffect } from 'react'
 
function MyApp({ Component, pageProps }) {
 const [kochava, setKochava] = useState(null)
 
 useEffect(() => {
  ( async () => {
    if(typeof window !== "undefined" && !kochava){
       const {Kochava} = (await import('kochava'))
       let kochavaLocal = Kochava.createForReact();
 
       // Will not use cookies (default)
       kochava.useCookies(false);
 
       // Will use cookies
       kochava.useCookies(true);
 
       kochavaLocal.startWithAppGuid("YOUR_APP_GUID")
       setKochava(kochavaLocal);
   }
   })()
 }, [kochava])
 
 return <Component {...{...pageProps, kochava: kochava}} />
}
 
export default MyApp

Next.js Examples

Example — (Access Kochava from a Component):

export default function Home(props) {
  const [kochava, setKochava] = useState(null)
 
 if(typeof window !== "undefined" && !kochava){ //in-browser check and !kochava prevents 'too many re-renders'
     if(props.kochava)
       setKochava(props.kochava)
 }
 
 useEffect(() => {
   ( async () => {
     if(typeof window !== "undefined" && kochava){ //in-browser check
       kochava.sendPageEvent() //example event to run on page load
    }
    })()
  }, [kochava])
 
return (...)
}

Confirm the Integration

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.