Developers
NAV Navbar
javascript
  • Kameleoon React API
  • Kameleoon React API

    The Kameleoon React API is a package that contains all the functionalities needed to modify React based websites to conduct experiments or implement personalization. You can use this package to modify UI and behaviour of React based components without modifying the basecode of your application. Our React API allows you to query components and change their states and props.

    You can refer to the API reference documentation to check out all possible features of the React API. If you are using this package for the first time or have little knowledge on how to use it, we have prepared a Getting started tutorial to walk you through the installation and use of the API.

    Getting started

    Installing the Kameleoon React API

    You need to install the Kameleoon React package to get started. You can do so by running:

    npm install --registry https://customers.kameleoon.com/modules/ kameleoon-react

    Integrating the package into the website

    import React from "react";
    import KameleoonReact from "kameleoon-react";
    
    KameleoonReact(React);
    
    class App extends Component {
        //some code...
    }
    

    Once installed you need to integrate the package by importing it into the main app (entry point).

    This will wrap your app inside our React API so you can easily use our library. If you have multiple entry points, you will need to integrate the API the same way for each point.

    Modifying state

    const headerComponent = kameleoonReact.Utils.querySelector("h1.header");
    
    headerComponent.setState('header', 'This API is cool');
    

    Once we have the component we want to change, we can, for example, change the page header by modifying one of the component's states. All we need to do is change the state as shown on the right by calling the setState method of the instance we selected. As a result the state of the component will be changed and a new text will be rendered

    Now that we have installed the React package into the app we can successfully change the states and props of the components. In our example we decided that we wanted to change the header of the webpage, which is currently displayed using the state.

    You can start by finding the DOM element(node) where the component is mounted. We can query the component by the node's tag or class name. In this example we get the component instance which has a h1 tag with a .header class to manipulate the props and states of that component.

    Modifying props

    const Input = (props) => {
      return (
        <input defaultValue={props.defaultValue} type="text" />
      );
    }
    
    <Input defaultValue="Username" />
    

    Some components may require you to change props instead of state. Our API supports that as well, so you can pass the required value as a prop to the component.

    Let's take a look at the component which takes a defaultValue prop as input as shown in the example:

    const inputComponent = kameleoonReact.Utils.querySelector("input");
    
    inputComponent.setProps("defaultValue", "your username");
    

    If you want to change the default value of the input from username to your username, you will have to call our setProps method as shown in the example:

    Following these simple steps you will be able to change the logic of your application and you won't need to query physical DOM elements and change them, which is known to cause a lot of unpredictable bugs if your application is written in React.

    Further reading

    To check out other features of our ReactAPI see the reference.

    React API Reference

    This is the full reference documentation of the Kameleoon React API. You will find all available methods that can be used inside your React based application.

    If this is the first time you are using our React API, we strongly recommend you take the time to read the getting started guide we have put in place for you.

    Query component

    To query the instance of the React component you want to use for modification you can use the querySelector method which can be accessed from the Utils package.

    Syntax

    const someComponent = kameleoonReact.Utils.querySelector(SELECTOR);

    This method returns an instance of the React component wrapped inside our API. Once you query the required component you can use the methods available from the API to modify the component's UI and logic.

    If you want to query multiple elements simultaneously you can use the querySelectorAll method. The only difference from the querySelector is that it returns an array of elements instead.

    Syntax

    const arrayOfComponents = kameleoonReact.Utils.querySelectorAll(SELECTOR);

    Get state

    To get the current state of certain components you can use the getState method which is available in our API.

    Syntax

    const titleState = kameleoonReact.Utils.querySelector(SELECTOR).getState(KEY);

    Arguments
    NameTypeDescription
    keystringKey of the state
    Return value
    NameTypeDescription
    valuestringValue of the state

    This method returns the value of the specified state from the queried component.

    Set state

    To change the state of a given component use the setState method of our API.

    Syntax

    kameleoonReact.Utils.querySelector(SELECTOR).setState(KEY, VALUE);

    Arguments
    NameTypeDescription
    keystringKey of the state
    valuestringValue to be stored in the state

    This method has no return value

    Get props

    To get the props passed to the component you can use the getProps method.

    Syntax

    const titleValue = kameleoonReact.Utils.querySelector(SELECTOR).getProps(KEY);

    Arguments
    NameTypeDescription
    keystringKey of the property passed to the component
    Return value
    NameTypeDescription
    valuestringValue of the property passed

    This method returns the value of the specified property from the queried component.

    Set props

    You can change the property of the component by calling the setProp method using our API.

    Syntax

    kameleoonReact.Utils.querySelector(SELECTOR).setProp(KEY, VALUE);

    Arguments
    NameTypeDescription
    keystringKey of the poreprty passed to the component
    valuestringNew value of the property that should be passed

    This method has no return value