Skip to content

Latest commit

 

History

History
237 lines (181 loc) · 7.13 KB

README.md

File metadata and controls

237 lines (181 loc) · 7.13 KB
Raw

react-tag-commander

Integrate CommandersAct's tag container with your React applications seamlessly using the react-tag-commander wrapper.

Table of Contents

Features

  • Automatic page tracking
  • Event triggering
  • Supports multiple containers

Installation and Quick Start

Installation

  1. Using NPM:

    npm i react-tag-commander

  2. Direct Include: Fetch dist/index.es5.min.js or index.es6.min.js and include it in your project.

    <script src="react-tag-commander/dist/index.es5.min.js"></script>

Import

  1. For ES6:

    import TC_Wrapper from 'react-tag-commander';

  2. For ES5:

     const TC_Wrapper = require('react-tag-commander');

  3. Direct Include:

    const TC_Wrapper = window.TC_Wrapper;

Setup

  1. Initialize your Data Layer: Set up your data layer early in your web application, preferably in a <script> block in the head.

    tc_vars = [];

  2. Add a Container: You can either include your container with a <script> tag or utilize the addContainer method from the wrapper.

  • For the latter, be aware it's asynchronous. Ensure your application renders asynchronously too.
import React from "react";
import TC_Wrapper from "react-tag-commander";

function App() {
    const [tcReady, setTcReady] = useState(false);
    
    useEffect(() => {
        const wrapper = TC_Wrapper.getInstance();
        Promise.all([
            wrapper.addContainer('container_head', '/tag-commander-head.js', 'head'), 
            wrapper.addContainer('container_body', '/tag-commander-body.js', 'body')
        ]).then(() => {
            setIsReady(true);
        });
    }, []);
    
    return ( tcReady ? <div>Containers loaded</div> : <div>Now loading</div> );
}

Methods

Many methods are asynchronous. If you want to ensure that a method has been executed before continuing, you can use the await keyword. Please check the function definition to see if it is asynchronous.

Container Management 

// Adding a container
await wrapper.addContainer('my-custom-id', '/url/to/container.js', 'head');

// Removing a container
wrapper.removeContainer('my-custom-id');

Variable Management 

// Set variables
await wrapper.setTcVars({ env_template : "shop", ... });

// Update a single variable
await wrapper.setTcVar('env_template', 'super_shop');

// Get a variable
const myVar = wrapper.getTcVar('VarKey');

// Remove a variable
wrapper.removeTcVar('VarKey');

Events

  • Refer to the base documentation on events for an understanding of events in general.
  • The method "triggerEvent" is the new name of the old method "captureEvent"; an alias has been added to ensure backward compatibility.
// Triggering an event
// eventLabel: Name of the event as defined in the container
// htmlElement: Calling context. Usually the HTML element on which the event is triggered, but it can be the component.
// data: event variables
await wrapper.triggerEvent(eventLabel, htmlElement, data);

Reloading Containers

Manual Reload

Update your container after any variable change.

await wrapper.reloadContainer(siteId, containerId, options);

Exclusions

You can state an exclusion array to your options object like below.

const options = {
        exclusions: [
            'datastorage',
            'deduplication',
            'internalvars',
            'privacy'
        ]
    };
await wrapper.reloadContainer(siteId, containerId, options);

Please see the container's documentation for other options.

On Route Change

Utilize the trackPageLoad function for updating on route changes.

function SampleView() {
  
  /* States and other effects */
  
  useEffect(() => {
    const wrapper = TC_Wrapper.getInstance();
    wrapper.trackPageLoad({ tcVars: { page: 'home' }})
  }, []);

  /* Render & other custom code */
}

Server-side Rendering (SSR)

react-tag-commander works seamlessly with frameworks utilizing Server-side Rendering (SSR) (for example Next.js). However, the wrapper is interacting with the DOM objects document and window, which are not available on the server. Therefore, you have to make sure that wrapper methods are only executed on the client-side. This can be achieved by using hooks like useEffect, useCallback or useState or, executing it in a callback function that doesn't run on the server, for example the submit function of a form.

Examples:

// Throws an 'window is not defined' error, as the code is executed on the server and trackPageLoad interacts with the window object.
function SampleView() {
    const wrapper = TC_Wrapper.getInstance();
    wrapper.trackPageLoad({tcVars: {page: 'home'}})
}
// Works as the code is executed on the client only
function SampleView() {
    useEffect(() => {
        const wrapper = TC_Wrapper.getInstance();
        wrapper.trackPageLoad({tcVars: {page: 'home'}})
    }, []);
}

Another option is to check whether window is defined before executing a method.

function SampleView() {
    if (typeof window !== 'undefined') {
        // client-side-only code
        const wrapper = TC_Wrapper.getInstance();
        wrapper.trackPageLoad({tcVars: {page: 'home'}})
    }
}

Sample App

To help you with your implementation we provided a sample application. To run it clone the repo then run:

cd tag-commander-sample-app
yarn start

Then, visit http://localhost:3000.

Development

After forking, set up your environment:

npm install

Commands available:

gulp

Contribute

To contribute to this project, please read the CONTRIBUTE.md file.

License

This module uses the MIT License. Contributions are welcome.