@d-cat/tag-template-google-analytics-ecommerce v5.1.0

Tag Template: Google Analytics Ecommerce

Tag template to initiate Google Analytics Enhanced Ecommerce. It's designed to use together with @d-cat/tag-manager.

Install

npm i @d-cat/tag-template-google-analytics-ecommerce

Usage

The Ecommerce class returns the main functionality of the template.

• It handles a given object to send data to Google Analytics, including product / user scoped dimensions.
• You can create 1 Ecommerce-object per Tracker, since it's likely that each tracker has a specific configuration.
• It is assumed that the Google Analytics Main Tag already has ga(TRACKERNAME.ec:require) activated when using the ecommerce tag.
• It is also assumed that the ecommerce-data is according to the JSON-schemas DCAT provides via Confluence.

Configuration

import Ecommerce from '@d-cat/tag-template-google-analytics-ecommerce';

// Default setup without Custom Dimensions/Metrics
const ecommerce = new Ecommerce({
  optionsToSet: {},
  trackername: 'main',
});

// Personalized setup with Custom Dimensions
const config: models.IConfig = {
  optionsToSet: {
    // hit scoped dimensions/metrics linked to only 1 event, taken from the event-data-payload
    setHit: async payload => {
      return {
        dimension47: payload.payment_method,
      };
    },
    // dimensions/metrics that you wish to set once for all hits to come on this page.
    // these are set on initialization, so don't work with ecommerce-data-payloads.
    setOnce: async () => {
      return {};
    },
    // dimensions/metrics that you wish to set on product-level. These are generated on item/product-level.
    // preferably these are in the details-object on product level.
    setProduct: async item => {
      return {
        dimension36: item.details?.binding_period,
      };
    },
  },
  // trackername
  trackername: 'myTrackerName',
};

Activation

This is done via the render-method, where the data-payload is passed to the ecommerce-tag, like this:

subscribe({
  event: 'ecommerce.*',
  handler: ({ data }: any) => {
    ecommerce.render(data);
  },
  id: 'tdn2010: tag - google analytics - ecommerce tag',
});

• In the ecommerce-tag is the switch-statement below that fires an ecommerce based on the action in the data-payload. So you don't have to worry about this part.

switch (data.action) {
        case 'detail':
          return this.detail(data as models.IDetail, ecommerceObj, setProduct, setHit);

        case 'listing':
          return this.listing(data as models.IListing, ecommerceObj, setProduct, setHit);

        case 'add_to_cart':
          return this.addToCart(data as models.IAddToCart, ecommerceObj, setProduct, setHit);

        case 'remove_from_cart':
          return this.removeFromCart(data as models.IRemoveFromCart, ecommerceObj, setProduct, setHit);

        case 'checkout':
          return this.checkout(data as models.ICheckout, ecommerceObj, setProduct, setHit);

        case 'purchase':
          return this.purchase(data as models.IPurchase, ecommerceObj, setProduct, setHit);

        default:
          throw new Error('Given ecommerce-action does not validate.');
      }
    } catch (err) {
      throw new Error(`Error during rendering Google Analytics Ecommerce: ${err}`);
    }

Advanced Setup

When the Ecommerce class doesn't satisfy your needs, you can inherit certain logic and override it with your own.

• Below is a decription of all the functional methods in the ecommerce-tag, that could you could override.
• All method return an async function that adds the products to the action, sets the action and sends the hit.
• These functions are async, since we want to make sure Custom Dimensions are sending the latest value of a variable.

import EnhancedEcommerce from '@d-cat/tag-template-google-analytics-ecommerce';

export default class MyClass extends EnhancedEcommerce {
  constructor(...args: any[]) {
    super(...args);
  }

  listing(...args: any[]) {
    super.listing(...args);
    // here you can add your own logic.
  }
}

detail(data:IDetail): Promise<T>

Builds and sends a hit to Google Analytics based specific for detail events.

import { IData, IDetail, IFieldsToSet, IVodafoneProduct, IZiggoProduct} from '@d-cat/tag-template-google-analytics-ecommerce';
ecommerce.detail<T>(
    data: models.IDetail,
    ecommerceObj: models.IData,
    setProduct: (item: Partial<models.IZiggoProduct | models.IVodafoneProduct>) => Promise<models.IFieldsToSet>,
    setHit: (data: Partial<models.IData>) => Promise<models.IFieldsToSet>,
  )

listing(data:IListing): Promise<T>

Builds and sends a hit to Google Analytics based specific for listing events.

import { Data, IFieldsToSet, IListing, IVodafoneProduct, IZiggoProduct } from '@d-cat/tag-template-google-analytics-ecommerce';
ecommerce.listing<T>(
    data: models.IListing,
    ecommerceObj: models.IData,
    setProduct: (data: Partial<models.IData>) => Promise<models.IFieldsToSet>,
    setHit: (data: Partial<models.IData>) => Promise<models.IFieldsToSet>,
  )

addToCart(data:IAddToCart): Promise<T>

Builds and sends a hit to Google Analytics based specific for add to cart events.

import { IAddToCart,IData, IFieldsToSet, IVodafoneProduct, IZiggoProduct } from '@d-cat/tag-template-google-analytics-ecommerce';
ecommerce.addToCart<T>(
    data: models.IAddToCart,
    ecommerceObj: models.IData,
    setProduct: (data: Partial<models.IData>) => Promise<models.IFieldsToSet>,
    setHit: (data: Partial<models.IData>) => Promise<models.IFieldsToSet>,
  )

removeFromCart(data:IRemoveFromCart): Promise<T>

Builds and sends a hit to Google Analytics based specific for remove from cart events.

import { IRemoveFromCart, IData, IFieldsToSet, IVodafoneProduct, IZiggoProduct} from '@d-cat/tag-template-google-analytics-ecommerce';

ecommerce.removeFromCart<T>(
    data: models.IRemoveFromCart,
    ecommerceObj: models.IData,
    setProduct: (data: Partial<models.IData>) => Promise<models.IFieldsToSet>,
    setHit: (data: Partial<models.IData>) => Promise<models.IFieldsToSet>,
  )

checkout(data:ICheckout): Promise<T>

Builds and sends a hit to Google Analytics based specific for checkout events.

import { ICheckout, IData, IFieldsToSet, IVodafoneProduct, IZiggoProduct } from '@d-cat/tag-template-google-analytics-ecommerce';
ecommerce.checkout<T>(
    data: models.ICheckout,
    ecommerceObj: models.IData,
    setProduct: (data: Partial<models.IData>) => Promise<models.IFieldsToSet>,
    setHit: (data: Partial<models.IData>) => Promise<models.IFieldsToSet>,
  )

purchase(data:IPurchase): Promise<T>

Builds and sends a hit to Google Analytics based specific for checkout events.

import { IPurchase } from '@d-cat/tag-template-google-analytics-ecommerce';

// when using typescript the Purchase type is needed.
ecommerce.purchase<T>(
    data: models.IPurchase,
    ecommerceObj: models.IData,
    setProduct: (data: Partial<models.IData>) => Promise<models.IFieldsToSet>,
    setHit: (data: Partial<models.IData>) => Promise<models.IFieldsToSet>,
  )