Feature/new ecommerce methods v2 (#27)

* adds new ecommerce event constants

* new ecommerce interfaces

* adds new ecommerce methods, adds deprecated to all of the old ecomeerce methods

* tag manager script update

* include types in tsconfig

* ecommerce example updated

* dosc update

* init test bugfix - remove deprecated .../containers... in path

* changelog update, package.json version update

* docs - minor version update

* limited array type bugfix

* limited array fix

CHANGELOG.md

@@ -1,8 +1,14 @@
 # CHANGELOG
 
-* [1.0.0](#0.0.1)
+* [1.0.1](#1.1.0)
+* [1.0.0](#1.0.0)
 * [0.0.1](#0.0.1)
 
+## 1.1.0
+
+* adds new ecommerce methods (v2)
+* deprecates old ecommerce methods (v1)
+
 ## 1.0.0
 
 * release of the stable package

README.md

@@ -251,7 +251,14 @@ Site search tracking gives you insights into how visitors interact with the sear
 * `trackSiteSearch(keyword: string, category?: string, searchCount?: number, dimensions?: Object)` - Tracks search requests on a website.
 
 ### E-Commerce Service
-#### Methods
+#### Methods 
+* `ecommerceAddToCart(products: Product[])` - Tracks action of adding products to a cart.
+* `ecommerceRemoveFromCart(products: Product[])` - Tracks action of removing a products from a cart.
+* `ecommerceOrder(products: Product[], paymentInformation: PaymentInformation)` - Tracks conversion (including products and payment details).
+* `ecommerceCartUpdate(products: Product[], grandTotal: PaymentInformation['grandTotal'])` - Tracks current state of a cart.
+* `ecommerceProductDetailView(products: Product[])` - Tracks product or category view. Must be followed by a page view.
+
+#### Deprecated methods
 * `addEcommerceItem(productSKU: string, productName: string, productCategory: string | string[], productPrice: number, productQuantity: number)` - Adds a product to a virtual shopping cart. If a product with the same SKU is in the cart, it will be removed first. Does not send any data to the Collecting & Processing Pipeline.
 * `removeEcommerceItem(productSKU: string)` - Removes a product with the provided SKU from a virtual shopping cart. If multiple units of that product are in the virtual cart, all of them will be removed. Does not send any data to the Collecting & Processing Pipeline.
 * `clearEcommerceCart()` - Removes all items from a virtual shopping cart. Does not send any data to the Collecting & Processing Pipeline.

angular.json

@@ -141,5 +141,8 @@
         }
       }
     }
+  },
+  "cli": {
+    "analytics": false
   }
 }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piwikpro/ngx-piwik-pro-project",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "scripts": {
     "ng": "ng",
     "start": "ng serve",

projects/ngx-piwik-pro/README.md

@@ -250,6 +250,13 @@ Site search tracking gives you insights into how visitors interact with the sear
 
 ### E-Commerce Service
 #### Methods
+* `ecommerceAddToCart(products: Product[])` - Tracks action of adding products to a cart.
+* `ecommerceRemoveFromCart(products: Product[])` - Tracks action of removing a products from a cart.
+* `ecommerceOrder(products: Product[], paymentInformation: PaymentInformation)` - Tracks conversion (including products and payment details).
+* `ecommerceCartUpdate(products: Product[], grandTotal: PaymentInformation['grandTotal'])` - Tracks current state of a cart.
+* `ecommerceProductDetailView(products: Product[])` - Tracks product or category view. Must be followed by a page view.
+
+#### Deprecated methods
 * `addEcommerceItem(productSKU: string, productName: string, productCategory: string | string[], productPrice: number, productQuantity: number)` - Adds a product to a virtual shopping cart. If a product with the same SKU is in the cart, it will be removed first. Does not send any data to the Collecting & Processing Pipeline.
 * `removeEcommerceItem(productSKU: string)` - Removes a product with the provided SKU from a virtual shopping cart. If multiple units of that product are in the virtual cart, all of them will be removed. Does not send any data to the Collecting & Processing Pipeline.
 * `clearEcommerceCart()` - Removes all items from a virtual shopping cart. Does not send any data to the Collecting & Processing Pipeline.

projects/ngx-piwik-pro/src/lib/constants/track-event.constant.ts

@@ -9,6 +9,11 @@ export enum TRACK_EVENT {
   SET_ECOMMERCE_VIEW = 'setEcommerceView',
   UPDATE_ECOMMERCE_CART = 'trackEcommerceCartUpdate',
   ORDER_ECOMMERCE = 'trackEcommerceOrder',
+  ECOMMERCE_ADD_TO_CART = "ecommerceAddToCart",
+  ECOMMERCE_REMOVE_FROM_CART = "ecommerceRemoveFromCart",
+  ECOMMERCE_PRODUCT_DETAIL_VIEW = "ecommerceProductDetailView",
+  ECOMMERCE_CART_UPDATE = "ecommerceCartUpdate",
+  ECOMMERCE_ORDER = "ecommerceOrder",
   SET_CUSTOM_VARIABLE = 'setCustomVariable',
   DELETE_CUSTOM_VARIABLE = 'deleteCustomVariable',
   STORE_CUSTOM_VARIABLES_IN_COOKIE = 'storeCustomVariablesInCookie',

projects/ngx-piwik-pro/src/lib/initializers/piwik-pro.initializer.ts

@@ -1,7 +1,8 @@
-import { APP_INITIALIZER, FactoryProvider, isDevMode, PLATFORM_ID } from '@angular/core';
+import { APP_INITIALIZER, FactoryProvider, PLATFORM_ID, isDevMode } from '@angular/core';
 import { DOCUMENT, isPlatformBrowser } from '@angular/common';
-import { PiwikProSettings } from '../interfaces/piwik-pro-settings.interface';
+
 import { NGX_PIWIK_PRO_SETTINGS_TOKEN } from '../tokens/ngx-piwik-pro-settings.token';
+import { PiwikProSettings } from '../interfaces/piwik-pro-settings.interface';
 
 export const NGX_PIWIK_PRO_INITIALIZER_PROVIDER: FactoryProvider = {
   provide: APP_INITIALIZER,
@@ -55,14 +56,14 @@ export function PiwikProInitializer(
       s.setAttribute("nonce", settings.nonce);
     }
     s.text = `(function(window, document, dataLayerName, id) {
-window[dataLayerName]=window[dataLayerName]||[],window[dataLayerName].push({start:(new Date).getTime(),event:"stg.start"});var scripts=document.getElementsByTagName('script')[0],tags=document.createElement('script');
-function stgCreateCookie(a,b,c){var d="";if(c){var e=new Date;e.setTime(e.getTime()+24*c*60*60*1e3),d="; expires="+e.toUTCString()}document.cookie=a+"="+b+d+"; path=/"}
-var isStgDebug=(window.location.href.match("stg_debug")||document.cookie.match("stg_debug"))&&!window.location.href.match("stg_disable_debug");stgCreateCookie("stg_debug",isStgDebug?1:"",isStgDebug?14:-1);
-var qP=[];dataLayerName!=="dataLayer"&&qP.push("data_layer_name="+dataLayerName),isStgDebug&&qP.push("stg_debug");var qPString=qP.length>0?("?"+qP.join("&")):"";
-tags.async=!0,tags.src="${settings.containerURL}/containers/"+id+".js"+qPString,scripts.parentNode.insertBefore(tags,scripts);
-!function(a,n,i){a[n]=a[n]||{};for(var c=0;c<i.length;c++)!function(i){a[n][i]=a[n][i]||{},a[n][i].api=a[n][i].api||function(){var a=[].slice.call(arguments,0);"string"==typeof a[0]&&window[dataLayerName].push({event:n+"."+i+":"+a[0],parameters:[].slice.call(arguments,1)})}}(i[c])}(window,"ppms",["tm","cm"]);
-})(window, document, 'dataLayer', '${settings.containerId}')`;
-
+      window[dataLayerName]=window[dataLayerName]||[],window[dataLayerName].push({start:(new Date).getTime(),event:"stg.start"});var scripts=document.getElementsByTagName('script')[0],tags=document.createElement('script');
+      function stgCreateCookie(a,b,c){var d="";if(c){var e=new Date;e.setTime(e.getTime()+24*c*60*60*1e3),d="; expires="+e.toUTCString();f="; SameSite=Strict"}document.cookie=a+"="+b+d+f+"; path=/"}
+      var isStgDebug=(window.location.href.match("stg_debug")||document.cookie.match("stg_debug"))&&!window.location.href.match("stg_disable_debug");stgCreateCookie("stg_debug",isStgDebug?1:"",isStgDebug?14:-1);
+      var qP=[];dataLayerName!=="dataLayer"&&qP.push("data_layer_name="+dataLayerName),isStgDebug&&qP.push("stg_debug");var qPString=qP.length>0?("?"+qP.join("&")):"";
+      tags.async=!0,tags.src="${settings.containerURL}/"+id+".js"+qPString,scripts.parentNode.insertBefore(tags,scripts);
+      !function(a,n,i){a[n]=a[n]||{};for(var c=0;c<i.length;c++)!function(i){a[n][i]=a[n][i]||{},a[n][i].api=a[n][i].api||function(){var a=[].slice.call(arguments,0);"string"==typeof a[0]&&window[dataLayerName].push({event:n+"."+i+":"+a[0],parameters:[].slice.call(arguments,1)})}}(i[c])}(window,"ppms",["tm","cm"]);
+      })(window, document, 'dataLayer', '${settings.containerId}')`
+      
     const head: HTMLHeadElement = document.getElementsByTagName('head')[0];
     head.appendChild(s);
   }

projects/ngx-piwik-pro/src/lib/interfaces/piwik-pro-ecommerce.interface.ts

@@ -0,0 +1,22 @@
+import { LimitedArrayFiveStrings } from './piwik-pro-utils.interface';
+type DimensionId = number;
+export type Product = {
+    sku: string;
+    name?: string;
+    category?: LimitedArrayFiveStrings;
+    price?: number;
+    quantity?: number;
+    brand?: string;
+    variant?: string;
+    customDimensions?: Record<DimensionId, string>;
+};
+
+export type PaymentInformation = {
+  orderId: string;
+  grandTotal: number | string;
+  subTotal?: number | string;
+  tax?: number | string;
+  shipping?: number | string;
+  discount?: number | string;
+};
+

projects/ngx-piwik-pro/src/lib/interfaces/piwik-pro-utils.interface.ts

@@ -0,0 +1 @@
+export type LimitedArrayFiveStrings = [string] | [string, string] | [string, string, string] | [string, string, string, string] | [string, string, string, string, string];

projects/ngx-piwik-pro/src/lib/ngx-piwik-pro.module.spec.ts

@@ -1,9 +1,9 @@
-import { TestBed } from '@angular/core/testing';
-import { NgxPiwikProModule } from './ngx-piwik-pro.module';
-import { NGX_PIWIK_PRO_SETTINGS_TOKEN } from '@piwik-pro/ngx-piwik-pro';
 import { APP_INITIALIZER } from '@angular/core';
-import { PiwikProSettings } from '@piwik-pro/ngx-piwik-pro/src/lib/interfaces/piwik-pro-settings.interface';
 import { DOCUMENT } from '@angular/common';
+import { NGX_PIWIK_PRO_SETTINGS_TOKEN } from '@piwik-pro/ngx-piwik-pro';
+import { NgxPiwikProModule } from './ngx-piwik-pro.module';
+import { PiwikProSettings } from '@piwik-pro/ngx-piwik-pro/src/lib/interfaces/piwik-pro-settings.interface';
+import { TestBed } from '@angular/core/testing';
 
 describe('NgxPiwikProModule test', () => {
   const containerId = 'dummy-container-id';
@@ -46,6 +46,6 @@ describe('NgxPiwikProModule test', () => {
     const scripts = head.getElementsByTagName('script');
 
     expect(scripts.length).toBe(2);
-    expect(scripts[0].src).toEqual(`${containerURL}/containers/${containerId}.js`);
+    expect(scripts[0].src).toEqual(`${containerURL}/${containerId}.js`);
   });
 });

projects/ngx-piwik-pro/src/lib/services/e-commerce/e-commerce.service.ts

@@ -1,5 +1,7 @@
+import { PaymentInformation, Product } from '../../interfaces/piwik-pro-ecommerce.interface';
+
 import { Injectable } from '@angular/core';
-import { PaqService } from '../../services/paq/paq.service';
+import { PaqService } from '../paq/paq.service';
 import { TRACK_EVENT } from '../../constants/track-event.constant';
 
 @Injectable({
@@ -11,6 +13,9 @@ export class ECommerceService {
     private readonly paqService: PaqService
   ) {}
 
+  /**
+   * @deprecated Please use the ecommerceAddToCart instead.
+   */
   addEcommerceItem(
     productSKU: string,
     productName: string,
@@ -28,19 +33,36 @@ export class ECommerceService {
     ])
   }
 
+  ecommerceAddToCart(products: Product[]) {
+    this.paqService.push([TRACK_EVENT.ECOMMERCE_ADD_TO_CART, products])
+  }
+
+  /**
+   * @deprecated Please use the ecommerceRemoveFromCart instead.
+   */
   removeEcommerceItem(productSKU: string) {
     this.paqService.push([
       TRACK_EVENT.REMOVE_ECOMMERCE_ITEM,
       productSKU
     ])
   }
 
+  ecommerceRemoveFromCart(products: Product[]) {
+    this.paqService.push([TRACK_EVENT.ECOMMERCE_REMOVE_FROM_CART, products])
+  }
+
+  /**
+   * @deprecated
+   */
   clearEcommerceCart() {
     this.paqService.push([
       TRACK_EVENT.CLEAR_ECOMMERCE_CART,
     ])
   }
 
+  /**
+   * @deprecated
+   */
   getEcommerceItems(): Promise<object> {
     return new Promise((resolve, reject) => {
       try {
@@ -57,6 +79,9 @@ export class ECommerceService {
     });
   }
 
+  /**
+   * @deprecated Please use the ecommerceOrder instead.
+   */
   trackEcommerceOrder(
     orderId: string,
     orderGrandTotal: number,
@@ -76,13 +101,33 @@ export class ECommerceService {
     ]);
   }
 
+  ecommerceOrder(
+    products: Product[],
+    paymentInformation: PaymentInformation
+  ) {
+    this.paqService.push([TRACK_EVENT.ECOMMERCE_ORDER, products, paymentInformation])
+  }
+
+  /**
+   * @deprecated Please use the ecommerceCartUpdate instead.
+   */
   trackEcommerceCartUpdate(cartAmount: number) {
     this.paqService.push([
       TRACK_EVENT.UPDATE_ECOMMERCE_CART,
       cartAmount
     ]);
   }
 
+  ecommerceCartUpdate(
+    products: Product[],
+    grandTotal: PaymentInformation['grandTotal']
+  ) {
+    this.paqService.push([TRACK_EVENT.ECOMMERCE_CART_UPDATE, products, grandTotal])
+  }
+
+  /**
+   * @deprecated
+   */
   setEcommerceView(productSKU: string, productName?: string, productCategory?: string[], productPrice?: string) {
     this.paqService.push([
       TRACK_EVENT.SET_ECOMMERCE_VIEW,
@@ -92,4 +137,8 @@ export class ECommerceService {
       productPrice
     ]);
   }
+
+  ecommerceProductDetailView(products: Product[]) {
+    this.paqService.push([TRACK_EVENT.ECOMMERCE_PRODUCT_DETAIL_VIEW, products])
+  }
 }

projects/ngx-piwik-pro/tsconfig.lib.json

@@ -6,7 +6,11 @@
     "declaration": true,
     "declarationMap": true,
     "inlineSources": true,
-    "types": []
+    "types": [],
+    "typeRoots": [
+      "src/lib/interfaces",
+      "src/lib/types"
+    ]
   },
   "exclude": [
     "src/test.ts",

projects/piwik-pro-angular-demo/src/app/pages/e-commerce/e-commerce.component.html

@@ -18,7 +18,7 @@ <h1>eCommerce</h1>
     <div>
       <mat-list>
         <mat-list-item *ngFor="let product of productList">
-          {{ product }}
+          {{ product.name }}
         </mat-list-item>
       </mat-list>
     </div>