README.md

Vue-Tag-Commander Documentation

Integrate Tag Commander with your Vue applications seamlessly using the vue-tag-commander wrapper.

• Official Tag Commander website
• Note: Familiarize yourself with Tag Commander's primary documentation before proceeding.

Table of Contents

• Features
• Installation and Quick Start
• Methods
  • Container Management
  • Variable Management
  • Events
• Reloading Containers
• 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

1. Manual Reload: Update your container after any variable change.

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

2. 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>

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.