vue-tag-commander

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

• Note: Familiarize yourself with CommandersAct's tag container's primary documentation before proceeding.

Table of Contents

• Features
• Installation and Quick Start
• Methods
  • Container Management
  • Variable Management
  • Events
  • Reloading Containers
• Server-side Rendering (SSR)
• Sample App
• License
• Development
• Contribute

Features

• Automatic page tracking
• Event triggering
• Supports multiple containers

Installation and Quick Start

Installation

1. Using NPM:

   npm i vue-tag-commander

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

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

Import

1. For ES6:

   import TC_Wrapper from 'vue-tag-commander';

2. For ES5:

    const TC_Wrapper = require('vue-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.

   • Vue 3 with Composition API:

     <template>
       <div v-if="isReady">Containers loaded</div>
       <div v-else>Now loading</div>
     </template>
              
     <script setup>
     import { RouterLink, RouterView } from 'vue-router'
     import TC_Wrapper from 'vue-tag-commander'
     import { onMounted, ref } from 'vue'
              
     const wrapper = TC_Wrapper.getInstance();
     wrapper.setDebug(true);
              
     const isReady = ref(false);
              
     onMounted(async () => {
       await wrapper.addContainer('container_head', '/tag-commander-head.js', 'head');
       await wrapper.addContainer('container_body', '/tag-commander-body.js', 'body');
       isReady.value = true;
     });
     </script>

   • Vue 2:

     <template>
       <div v-if="isReady">Containers loaded</div>
       <div v-else>Now loading</div>
     </template>
            
     <script>
     import TC_Wrapper from "vue-tag-commander";
            
     const wrapper = TC_Wrapper.getInstance();
     wrapper.setDebug(true);
            
     export default {
       name: "App",
       data() {
         return { isReady: false };
       },
       async mounted() {
         await wrapper.addContainer(
           "container_head",
           "/tag-commander-head.js",
           "head"
         );
         await wrapper.addContainer(
           "container_body",
           "/tag-commander-body.js",
           "body"
         );
         this.isReady = true;
       },
     };
     </script>

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.

• Vue 3 with Composition API:

  <script setup>
  import TC_Wrapper from "vue-tag-commander";
  import { onMounted } from 'vue'
        
  const wrapper = TC_Wrapper.getInstance();
        
  onMounted(() => {
    wrapper.trackPageLoad();
  })
  </script>

• Vue 2:

  <script>
  import TC_Wrapper from "vue-tag-commander";
       
  const wrapper = TC_Wrapper.getInstance();
       
  export default {
    name: "sampleView",
    mounted() {
      wrapper.trackPageLoad();
    },
  };
  </script>

Server-side Rendering (SSR)

vue-tag-commander works seamlessly with frameworks utilizing Server-side Rendering (SSR) (for example Nuxt / Nuxt 2). 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 onMounted (mounted() for Vue 2) or executing it in a callback function that doesn't run on the server.

Vue 3 / Nuxt examples:

// Don't do it like that, code is executed on the server
<script setup>
import TC_Wrapper from 'vue-tag-commander'
    
const wrapper = TC_Wrapper.getInstance();
wrapper.trackPageLoad({tcVars: {page: 'home'}});
</script>

// Works as the code is executed on the client only
<script setup>
import TC_Wrapper from 'vue-tag-commander'
import { onMounted } from 'vue'

onMounted(() => {
    const wrapper = TC_Wrapper.getInstance();
    wrapper.trackPageLoad({tcVars: {page: 'home'}});
});
</script>

Other options are checking whether window is defined, or checking the process before executing a method.

<script setup>
import TC_Wrapper from 'vue-tag-commander'

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

<script setup>
import TC_Wrapper from 'vue-tag-commander'

if (process.client) {
    // client-side-only code
    const wrapper = TC_Wrapper.getInstance();
    wrapper.trackPageLoad({tcVars: {page: 'home'}});
}
</script>

Vue 2 / Nuxt 2:

• When using Nuxt 2, you have to add vue-tag-commander to the transpile array in the build options in nuxt.config.js in order to make it work:

export default {
    // ...
    build: {
        transpile: [
            'vue-tag-commander'
        ]
    }
    // ...
}

Example usage:

// Don't do it like that, code is executed on the server
<script>
import TC_Wrapper from 'vue-tag-commander'
    
const wrapper = TC_Wrapper.getInstance();
wrapper.trackPageLoad({tcVars: {page: 'home'}});

export default {
    name: "sampleView"
};    
</script>

// Works as the code is executed on the client only
<script>
import TC_Wrapper from "vue-tag-commander";
    
export default {
    name: "sampleView",
    mounted() {
        const wrapper = TC_Wrapper.getInstance();
        wrapper.trackPageLoad();
    },
};
</script>

Other options are checking whether window is defined, or checking the process before executing a method.

<script>
import TC_Wrapper from 'vue-tag-commander'

export default {
    name: "sampleView"
};
    
if (typeof window !== 'undefined') {
    // client-side-only code
    const wrapper = TC_Wrapper.getInstance();
    wrapper.trackPageLoad({tcVars: {page: 'home'}});
}
</script>

<script>
import TC_Wrapper from 'vue-tag-commander'

export default {
    name: "sampleView"
};

if (process.client) {
    // client-side-only code
    const wrapper = TC_Wrapper.getInstance();
    wrapper.trackPageLoad({tcVars: {page: 'home'}});
}
</script>

Sample App

To help you with your implementation we provide two sample applications, one for Vue 3, one for Vue 2. To run them, clone the repo then run:

• For the Vue 3 Sample App

  cd tag-commander-sample-app-vue3
  npm install
  npm run dev

• For the Vue 2 Sample App

  cd tag-commander-sample-app-vue2
  npm install
  npm run dev

Then, visit http://localhost:5173.

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.