v1.0.2 (#4)

* Update package.json Updated package.json to no longer require Angular 11 as a peer dependency * Fix #3 Removed pixel ID length check as these are not always the same length. There is also no documentation which shapes a pixel ID can take. * Update models Moved Pixel event names from inline to models as new type PixelEventName * Fix #1 Allow dynamic pixel IDs to be passed to `initialize()`. A default ID should still be provided in module declaration. * Update JSDoc * Add logging Added console warnings when either of the tracking functions is called without an active Pixel instance * Update package.json
NielsCodes · May 24, 2021 · 8e84035 · 8e84035
1 parent 64918b0
commit 8e84035
Show file tree

Hide file tree

Showing 7 changed files with 68 additions and 47 deletions.
diff --git a/README.md b/README.md
@@ -35,7 +35,7 @@ import { PixelModule } from 'ngx-pixel';
   ],
   imports: [
     BrowserModule,
-    PixelModule.forRoot({ enabled: true, pixelId: 'YOUR_PIXEL_ID'})
+    PixelModule.forRoot({ enabled: true, pixelId: 'YOUR_PIXEL_ID' })
   ],
   providers: [],
   bootstrap: [AppComponent]
@@ -117,6 +117,12 @@ export class HomeComponent {
 }
 ```
 
+## Enabling with a dynamic Pixel ID
+In situations where the Pixel ID needs to be changed dynamically, this can be done using `initialize()` with the new Pixel ID as an optional argument. 
+**Notes:** 
+- A Pixel ID still needs to be provided when importing ***ngx-pixel*** in the module.
+- The previous instance should be removed with `remove()` before initializing a new Pixel ID.  
+
 ## Disabling ***ngx-pixel***
 Disabling works very similar to *enabling* from within a component and looks like this:
 ```TypeScript
@@ -141,9 +147,8 @@ export class HomeComponent {
 ---
 
 # What's next?
-- [ ] Checking Pixel ID's using a RegEx. First need to confirm whether all Pixel ID's follow the same format.
+- [ ] Adding Angular Universal SSR support.
 - [ ] Adding tests.
-- [ ] Testing View Engine backwards-compatibility.
 - [ ] Removing all Facebook scripts on removal, not just the initial script.
 
 ---

diff --git a/projects/pixel/README.md b/projects/pixel/README.md
@@ -35,7 +35,7 @@ import { PixelModule } from 'ngx-pixel';
   ],
   imports: [
     BrowserModule,
-    PixelModule.forRoot({ enabled: true, pixelId: 'YOUR_PIXEL_ID'})
+    PixelModule.forRoot({ enabled: true, pixelId: 'YOUR_PIXEL_ID' })
   ],
   providers: [],
   bootstrap: [AppComponent]
@@ -117,6 +117,12 @@ export class HomeComponent {
 }
 ```
 
+## Enabling with a dynamic Pixel ID
+In situations where the Pixel ID needs to be changed dynamically, this can be done using `initialize()` with the new Pixel ID as an optional argument. 
+**Notes:** 
+- A Pixel ID still needs to be provided when importing ***ngx-pixel*** in the module.
+- The previous instance should be removed with `remove()` before initializing a new Pixel ID.  
+
 ## Disabling ***ngx-pixel***
 Disabling works very similar to *enabling* from within a component and looks like this:
 ```TypeScript
@@ -141,16 +147,17 @@ export class HomeComponent {
 ---
 
 # What's next?
-- [ ] Checking Pixel ID's using a RegEx. First need to confirm whether all Pixel ID's follow the same format.
+- [ ] Adding Angular Universal SSR support.
 - [ ] Adding tests.
-- [ ] Testing View Engine backwards-compatibility.
 - [ ] Removing all Facebook scripts on removal, not just the initial script.
 
 ---
+
 Created with ❤️ by Niels Kersic, [niels.codes](https://niels.codes).
 
 
 
 
 
 
+
diff --git a/projects/pixel/package.json b/projects/pixel/package.json
@@ -7,16 +7,16 @@
     "url": "https://niels.codes"
   },
   "license": "MIT",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "repository": {
     "type": "git",
     "url": "https://github.com/NielsKersic/ngx-pixel"
   },
   "peerDependencies": {
-    "@angular/common": "^11.0.1",
-    "@angular/core": "^11.0.1"
+    "@angular/common": ">=11.0.1",
+    "@angular/core": ">=11.0.1"
   },
   "dependencies": {
-    "tslib": "^2.0.0"
+    "tslib": ">=2.0.0"
   }
 }
diff --git a/projects/pixel/src/lib/pixel.models.ts b/projects/pixel/src/lib/pixel.models.ts
@@ -55,7 +55,8 @@ export interface PixelEventProperties {
 
   /**
    * The currency for the `value` specified.
-   * @see {@link https://developers.facebook.com/docs/marketing-api/currencies}
+   *
+   * See {@link https://developers.facebook.com/docs/marketing-api/currencies Facebook Pixel docs - currency codes}
    */
   currency?:
   'AED' | 'ARS' | 'AUD' |
@@ -79,3 +80,22 @@ export interface PixelEventProperties {
   'VEF' | 'VND' |
   'ZAR';
 }
+
+export type PixelEventName = 'AddPaymentInfo' |
+'AddToCart' |
+'AddToWishlist' |
+'CompleteRegistration' |
+'Contact' |
+'CustomizeProduct' |
+'Donate' |
+'FindLocation' |
+'InitiateCheckout' |
+'Lead' |
+'PageView' |
+'Purchase' |
+'Schedule' |
+'Search' |
+'StartTrial' |
+'SubmitApplication' |
+'Subscribe' |
+'ViewContent';
diff --git a/projects/pixel/src/lib/pixel.module.ts b/projects/pixel/src/lib/pixel.module.ts
@@ -3,16 +3,15 @@ import { ModuleWithProviders, NgModule } from '@angular/core';
 import { PixelService } from './pixel.service';
 
 @NgModule({
-  imports: [
-  ],
+  imports: [],
 })
 export class PixelModule {
 
   private static config: PixelConfiguration | null = null;
 
   constructor( private pixel: PixelService ) {
     if (!PixelModule.config) {
-      throw Error('ngx-pixel not configured correctly');
+      throw Error('ngx-pixel not configured correctly. Pass the `pixelId` property to the `forRoot()` function');
     }
     if (PixelModule.config.enabled) {
       this.pixel.initialize();
@@ -21,6 +20,7 @@ export class PixelModule {
 
   /**
    * Initiale the Facebook Pixel Module
+   *
    * Add your Pixel ID as parameter
    */
   static forRoot(config: PixelConfiguration): ModuleWithProviders<PixelModule> {
@@ -40,18 +40,10 @@ export class PixelModule {
    * @param pixelId Pixel ID to verify
    */
   private static verifyPixelId(pixelId: string): void {
-
-    // Regular expression for Pixel ID format (15 digits) (not yet implemented)
-    const regex = /^\d{15}$/;
-
-    // TODO: Check validity of Pixel ID with a RegEx.
     // Have to verify first that all Pixel IDs follow the same 15 digit format
     if (pixelId === null || pixelId === undefined || pixelId.length === 0) {
       throw Error('Invalid Facebook Pixel ID. Did you pass the ID into the forRoot() function?');
-    } else if (!regex.test(pixelId)) {
-      throw Error('Invalid Facebook Pixel ID. The ID should consist of 15 digits.');
     }
-
   }
 
 }
diff --git a/projects/pixel/src/lib/pixel.service.ts b/projects/pixel/src/lib/pixel.service.ts
@@ -1,4 +1,4 @@
-import { PixelConfiguration, PixelEventProperties } from './pixel.models';
+import { PixelEventName, PixelConfiguration, PixelEventProperties } from './pixel.models';
 import { Inject, Injectable, Optional } from '@angular/core';
 import { NavigationEnd, Router } from '@angular/router';
 import { filter } from 'rxjs/operators';
@@ -33,9 +33,13 @@ export class PixelService {
    * - Adds the script to page's head
    * - Tracks first page view
    */
-  initialize(): void {
+  initialize(pixelId = this.config.pixelId): void {
+    if (this.isLoaded()) {
+      console.warn('Tried to initialize a Pixel instance while another is already active. Please call `remove()` before initializing a new instance.');
+      return;
+    }
     this.config.enabled = true;
-    this.addPixelScript(this.config.pixelId);
+    this.addPixelScript(pixelId);
   }
 
   /** Remove the Pixel tracking script */
@@ -46,32 +50,19 @@ export class PixelService {
 
   /**
    * Track a Standard Event as predefined by Facebook
-   * @see {@link https://developers.facebook.com/docs/facebook-pixel/reference}
+   *
+   * See {@link https://developers.facebook.com/docs/facebook-pixel/reference Facebook Pixel docs - reference}
    * @param eventName The name of the event that is being tracked
    * @param properties Optional properties of the event
    */
   track(
-    eventName:
-    'AddPaymentInfo' |
-    'AddToCart' |
-    'AddToWishlist' |
-    'CompleteRegistration' |
-    'Contact' |
-    'CustomizeProduct' |
-    'Donate' |
-    'FindLocation' |
-    'InitiateCheckout' |
-    'Lead' |
-    'PageView' |
-    'Purchase' |
-    'Schedule' |
-    'Search' |
-    'StartTrial' |
-    'SubmitApplication' |
-    'Subscribe' |
-    'ViewContent',
+    eventName: PixelEventName,
     properties?: PixelEventProperties
     ): void {
+    if(!this.isLoaded()) {
+      console.warn('Tried to track an event without initializing a Pixel instance. Call `initialize()` first.');
+      return;
+    }
 
     if (properties) {
       fbq('track', eventName, properties);
@@ -83,11 +74,17 @@ export class PixelService {
 
   /**
    * Track a custom Event
-   * @see {@link https://developers.facebook.com/docs/facebook-pixel/implementation/conversion-tracking#custom-conversions}
+   *
+   * See {@link https://developers.facebook.com/docs/facebook-pixel/implementation/conversion-tracking#custom-conversions Facebook Pixel docs - custom conversions}
    * @param eventName The name of the event that is being tracked
    * @param properties Optional properties of the event
    */
   trackCustom(eventName: string, properties?: object): void {
+    if(!this.isLoaded()) {
+      console.warn('Tried to track an event without initializing a Pixel instance. Call `initialize()` first.');
+      return;
+    }
+
     if (properties) {
       fbq('trackCustom', eventName, properties);
     } else {

diff --git a/tsconfig.json b/tsconfig.json
@@ -31,4 +31,4 @@
     "strictInputAccessModifiers": true,
     "strictTemplates": true
   }
-}
+}