Support Home > Web SDK Integration > React Web SDK Integration

React Web SDK Integration


Feature Summary: The Kochava 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 integrate with the React framework, as well as derivatives (i.e., Next.js and Gatsby).

 

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

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 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 1.0.6 or later was added in your package json. At this point the SDK has been installed and is ready to use.

Starting the SDK

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. The only requirement is that the Kochava class be instantiated only once with a valid configuration.

Within your root component which calls ReactDOM.Render (usually index.js), import the Kochava class and instantiate the Kochava class using your configuration.

 

Example — (Instantiate Kochava in the Root Component)

  • 'app_id' — 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
  • 'verbose' — Set to true for verbose logging to the console. Set to false to suppress all logging.
  • 'use_cookie' — Set to true to drop Cookie on the website to track a device across sub-domains. Set to false to not drop the Cookie and rely only on local storage for tracking.
  • 'disable_auto_install' — Set this value to true to stop the SDK from automatically signaling an install when the SDK is initialized for the first time.
  • 'identity_link' — Set to an object of key-value pairs that provides a means for linking different identities with Kochava devices. E.g., {“User ID”: “123456789”, “Login”: “username”}.

 

At this point basic integration is complete! Optional functionality is discussed below. Note that because a kochava object has been created but not used elsewhere in this example, you may see a warning related to kochava being declared but not used, which can be safely ignored.


Using the SDK

Once you have completed integration, the following optional functionality is available.

NOTE: These code examples assume you have instantiated the Kochava class as an object named kochava.

  1. For any child components which may need to call Kochava SDK functions, add the kochava object as a prop on your child components, which will allow you to call Kochava SDK functions.
  2.  

    Example — (Add kochava to a Child Component)

     

  3. After adding the prop, within your child component you can access the kochava object via this.props.kochava or props.kochava depending on whether it is a Class or Functional component respectively.

     

    Example — (Access kochava from a Class Component)

     

    Example — (Access kochava from a Functional Component)


    Page:

    The page function allows you to record page views on your website, along with optional metadata information about the page being viewed. If you do not specify a page name, Kochava will dynamically collect the page from the URL. Optional metadata must be provided as an object of key value pairs. The callback parameter is optional and may be safely omitted if not desired.

     

    Example — (Record a Page View Manually)

     

    Example — (Record a Page View Manually with Event Data)

     

    Autopage —

    If you would like to record page views automatically whenever the user loads a new page, this can be accomplished by calling the props.kochava.page() function in the component which best represents a unique page view on your site. Be sure props.kochava.page() is not called from multiple components during a single page view, as multiple page views would be recorded.

     

    Example — (Send an Autopage from a Class Component)

     

    Example — (Send an Autopage from a Functional Component)


    Identify (Identity Link):

    The identify function tells Kochava who the current user is. This method provides Kochava with a unique user ID and any other user specific data available. Calls to kochava.identify() will send the user data to the Kochava Identify API, allowing the data to be used for attribution. The “callback” parameter is optional and may be safely omitted if not desired.

     

    BEST PRACTICES: If an identity link is known early on, when instantiating Kochava, the identity link should be passed into the Kochava configuration as the identity_link parameter, rather than using this identify() function.

     

    NOTE: If a string is passed instead of an object, that value will be associated with the key custom_id.

     

    Example — (Identify with only a String Value)

     

    Example — (Identify with a Key Value Pair)


    Activity (Event):

    The Activity function allows you to record custom actions or events which your users are performing or completing throughout your site. Every integrated action or event that is triggered can include optional metadata properties which can be exposed via reporting and analytics. These integrated activities can also act as engagement/conversion events through the tracking URL creation process. The callback parameter is optional and may be safely omitted if not desired.

     

    Example — (Track an Activity)

     

    NOTE: The SDK collects the time on page which is sent with any custom events implemented. The time that is returned is in seconds and starts once the page is loaded until the custom event is sent/completed. The event_name parameter is required but all other parameters are optional and may be safely omitted if not desired.

    NOTE: For more information on standard events within Kochava, refer to our Post-Install Event Examples support documentation.


    Install:

    The install is automatically sent for you and you do not need to perform this activity unless you have set Disable Auto Install to true. If you have set this value to true, you must manually send the install only once, and do so before sending any other activities or events. It is your responsibility to ensure this function is called only once per user.

     

    BEST PRACTICES: It is highly recommended that if sending the install, autopage not be used. This is because Kochava will automatically send an event when landing on a page, which will in turn auto-generate an install defeating the purpose. In this case no page views should be tracked until after the install is manually sent.

     

    Example — (Install)

     

    Alternatively, if you have an identity link in scope at the moment you wish to send the install, call installWithIdentity() with an object containing identity key and value pairs as the first parameter. This will ensure the identity link is included directly within the manually triggered install payload.

     

    Example — (Install with an Identity Key Value Pair)