|
1 | | -# NgxPixelWorkspace |
| 1 | +# ngx-pixel |
2 | 2 |
|
3 | | -This project was generated with [Angular CLI](https://github.com/angular/angular-cli) version 11.0.2. |
| 3 | + |
4 | 4 |
|
5 | | -## Development server |
| 5 | +<center> |
| 6 | +A simple Angular library to simplify tracking using a Facebook Pixel. |
| 7 | +</center> |
6 | 8 |
|
7 | | -Run `ng serve` for a dev server. Navigate to `http://localhost:4200/`. The app will automatically reload if you change any of the source files. |
| 9 | +--- |
8 | 10 |
|
9 | | -## Code scaffolding |
| 11 | +## Introduction |
| 12 | +Using a Facebook Pixel is fairly simple. You add the script to the `head` section of all pages, after which you can use the `fbq` function. However, in Angular it's not as straight-forward. The main two problems are as follows: |
10 | 13 |
|
11 | | -Run `ng generate component component-name` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module`. |
| 14 | +- Navigation using the Angular Router is not tracked. |
| 15 | +- There are no TypeScript definitions by default, so no Intellisense or linting. |
12 | 16 |
|
13 | | -## Build |
| 17 | +***ngx-pixel*** solves both of these issues. |
14 | 18 |
|
15 | | -Run `ng build` to build the project. The build artifacts will be stored in the `dist/` directory. Use the `--prod` flag for a production build. |
| 19 | +## Usage |
| 20 | +Using ***ngx-pixel*** is very simple. |
| 21 | + |
| 22 | +### 1. Installing the NPM package |
| 23 | +You can install the NPM package with `npm install ngx-pixel` |
| 24 | + |
| 25 | +### 2. Add it to your app module |
| 26 | +Add the library to your app's module, usually `app.module.ts`. Make sure you use the `forRoot()` method. Within this method, add your [Facebook Pixel ID](https://www.facebook.com/business/help/952192354843755). |
| 27 | +```typescript |
| 28 | +import { PixelModule } from 'ngx-pixel'; |
| 29 | + |
| 30 | +@NgModule({ |
| 31 | + declarations: [ |
| 32 | + AppComponent |
| 33 | + ], |
| 34 | + imports: [ |
| 35 | + BrowserModule, |
| 36 | + PixelModule.forRoot({ enabled: true, pixelId: 'YOUR_PIXEL_ID'}) |
| 37 | + ], |
| 38 | + providers: [], |
| 39 | + bootstrap: [AppComponent] |
| 40 | +}) |
| 41 | +export class AppModule { } |
| 42 | +``` |
| 43 | +**NOTE:** By default, the library does not start tracking immediately. In most cases this requires user consent to comply with GDPR and other privacy regulations. If you would still like start tracking as soon as your app module loads, include the `enabled: true` parameter in when you call `forRoot()`. |
| 44 | + |
| 45 | +### 3. Add it to your components |
| 46 | +In any component where you would like to track certain events, you can import the ***ngx-pixel service*** with `import { PixelService } from 'ngx-pixel';` |
| 47 | +Then you can inject the service into your component as follows: |
| 48 | +```TypeScript |
| 49 | +export class HomeComponent { |
| 50 | + |
| 51 | + constructor( |
| 52 | + private pixel: PixelService |
| 53 | + ) { } |
| 54 | + |
| 55 | +} |
| 56 | +``` |
| 57 | + |
| 58 | +### 4. Tracking events |
| 59 | +There are two groups of events that you can track, namely *Standard events* and *Custom events*. |
| 60 | + |
| 61 | +#### Standard events |
| 62 | +**Standard events** are common events that Facebook has created. You can find the full list [here](https://developers.facebook.com/docs/facebook-pixel/reference). You can track a Standard event like this: |
| 63 | + |
| 64 | + |
| 65 | +The first argument is the type of event as defined by Facebook. The optional second argument can be used to pass more information about the event. E.g.: |
| 66 | +```typescript |
| 67 | +this.pixel.track('InitiateCheckout', { |
| 68 | + content_ids: ['ABC123', 'XYZ456'], // Item SKUs |
| 69 | + value: 100, // Value of all items |
| 70 | + currency: 'USD' // Currency of the value |
| 71 | +}); |
| 72 | +``` |
| 73 | + |
| 74 | +#### Custom events |
| 75 | +Tracking **Custom events** works very similar to tracking Standard events. The only major difference is that there are no TypeScript interfaces and therefore no Intellisense. This is because the event *name* and optional *properties* can be anything. Tracking a custom event with ***ngx-pixel*** looks like this: |
| 76 | +```TypeScript |
| 77 | +this.pixel.trackCustom('MyCustomEvent'); |
| 78 | +``` |
| 79 | + |
| 80 | +And just like with Standard events, you can add more properties. This is recommended, since this enables you to create even more specific audiences within Facebook Business Manager. Which properties you add is completely up to you. Here is an example: |
| 81 | +```TypeScript |
| 82 | +this.pixel.trackCustom('MyCustomEvent', { |
| 83 | + platform: 'limewire' |
| 84 | +}) |
| 85 | +``` |
| 86 | + |
| 87 | +## Important notes |
| 88 | +- ***ngx-pixel*** was developed using Angular 11, which uses the Ivy compiler instead of the older View Engine compiler. If your project uses Angular 8 or earlier, or if you decided to keep using View Engine with newer Angular versions, ***ngx-pixel*** might not be compatible, although I have not yet tested this to confirm. |
| 89 | + |
| 90 | +## What's next? |
| 91 | +- [ ] Checking Pixel ID's using a RegEx. I first want to confirm whether all Pixel ID's follow the same format. |
| 92 | +- [ ] Adding tests. |
| 93 | +- [ ] Testing View Engine backwards-compatibility. |
| 94 | + |
| 95 | +--- |
| 96 | +<center> |
| 97 | +Created with ❤️ by Niels Kersic, [niels.codes](https://niels.codes). |
| 98 | +</center> |
16 | 99 |
|
17 | | -## Running unit tests |
18 | 100 |
|
19 | | -Run `ng test` to execute the unit tests via [Karma](https://karma-runner.github.io). |
20 | 101 |
|
21 | | -## Running end-to-end tests |
22 | 102 |
|
23 | | -Run `ng e2e` to execute the end-to-end tests via [Protractor](http://www.protractortest.org/). |
24 | 103 |
|
25 | | -## Further help |
26 | 104 |
|
27 | | -To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.io/cli) page. |
|
0 commit comments