# cnBolt-Extensions-Tracking

A bolt extension as a wrapper for the generic Condé-Nast tracking solution.

## Installation
This extension is hosted in a private git repository and has to be installed manually.

1.) Edit your extensions/composer.json file and add the **cnd/tracking** to the require section:
```
"require": {
    "cnd/tracking": "*"
}
```
1.1) Since satis is our used composer repository generator, it is not necessary to add the cnd-tracking to the repository section. 
If satis is not in action one has to add the following code to the repositories section.
```
    "repositories": {
        "cnd-tracking": {
            "type": "git",
            "url": "https://github.com/CondeNastDigital/cnBolt-Extensions-Tracking.git"
        }
    },
```
2.) Change to the extensions folder and install via composer.
```
composer require cnd/tracking
```
Installing or updating via the Bolt admin interface is also possible but would require the web-server's user to have proper access to the GitHup repository. This is usually not the case.

## Configuration
To use the extension, you have to configure the extension itself as usual inside the file **app/config/extensions/tracking.cnd.yml**

**Sample**
```
site-id: "1234" # tracking site id's can be provided by the data team

contenttype-ids:
    article: "0001"
    portal: "0002"

providers:
    GTM:
        providerScript: /js/tracking/providers/googleGTM.js
        trackingId: GTM-CODE-123
        bodyEnd: |
            <!-- Google Tag Manager -->
            <noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-CODE-123" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
            <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
                        new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
                        j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
                        '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
                })(window,document,'script','dataLayer','GTM-CODE-123');</script>
            <!-- End Google Tag Manager -->
    Debug:
        providerScript: /js/tracking/providers/consoleTracking.js
```

If you want to enable Google's A/B testing tool "Optimize", you can add this code as a new provider.

```
Optimize:
    headStart: |
        <!-- Google Optimize -->

        <!-- Anti-flicker snippet -->
        <style>.async-hide { opacity: 0 !important} </style>
        <script>(function(a,s,y,n,c,h,i,d,e){s.className+=' '+y;h.start=1*new Date;
        h.end=i=function(){s.className=s.className.replace(RegExp(' ?'+y),'')};
        (a[n]=a[n]||[]).hide=h;setTimeout(function(){i();h.end=null},c);h.timeout=c;
        })(window,document.documentElement,'async-hide','dataLayer',4000,
        {'GTM-PP5QW4Z':true});</script>

        <!-- Modified Analytics code with Optimize plugin -->
        <script>(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
            (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
            m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
            })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');

            ga('create', 'UA-111111-22', 'auto',{allowLinker: true});
            ga('require', 'GTM-XXXXX');
        </script>
        <!-- End Google Optimize -->
```

### Specification

- *site-id* - This id defines the individual number of the website (brand). This ID can be provided by the data team
- *contenttype-ids* - This holds all contenttypes which are set in the **contenttypes.yml**. The ids were either set by you for each contenttype, or the data team will give you the ids for each contenttype. Either way, you have to communicate with the data team about the ids.
- *providers* - In the providers section you can add specific providers. In the sample above, *GTM* and *Debug* are set.
- *providerScript* - This script will make the magic happen.
- *trackingId* - This id can be provided by the data team
- *bodyEnd* - You can add special code to a specific place on your site. This will be written directly into the sourcecode. In this case this snippet will be written at the end of the body-tag. At the moment *bodyStart*, *bodyEnd* and *headStart* are possible.

## Usage
All events or dimensions are called via the tracking.js. The library creates the global *cnTracking* object. This object provides all methods for tracking data:

### trackPage(data)
**This call will be added automatically by the extension!**

Track page-level data.

- *data* the data parameter contains a key/value object.

### trackEvent(event, object, parameters)
Track normal events.

- *event* the type of the event as string
- *object* the object being clicked on
- *parameters* additional event parameters

### productView(data)
A product has been viewd in detail.

- *data* the data parameter contains the object being showed.

### productTeaser(data)
A product has been shown as a teaser

- *data* the data parameter contains the object being showed.

### productConversion(data)
A product has been converted or bought.

- *data* the data parameter contains the object being converted.

### ecommerceEvent(event, object, parameters)
An e-commerce object has been fired.

- *event* the type of the event as string
- *object* either an array with products or the object being clicked on
- *parameters* additional event parameters

## Samples
```
cnTracking.productTeaser({
    'list': "top-teasers",
    'position': "5",
    'name': "Mein Produkt",
    'type': "product"
});
```

```
cnTracking.trackPage({
    "page_type": "video_detail",
    "publish_date": "2015-07-17",
    "video_length": 210,
    "video_id": "brightcove-4359754262001",
    "brand": "WIRED",
    "series": "Neon Future Sessions",
    "category": "Technology",
    "playlist": "CNE für WIRED"
});
```
```
cnTracking.trackEvent(
    "video", 
    {
        'id': 'brightcove-4359754262001',
        'name': 'Neon Future Sessions - Stan Lee Thinks the World Is Going to Blow Itself Up, Steve Aoki Finds Out Why',
        'brand': 'WIRED',
        'category': 'Technology'
    },
    {"type": "play"}
);
```
```
cnTracking.ecommerceEvent(
  'ecommerce': {
    'detail': {
      'actionField': {'list': 'Apparel Gallery'},
      'products': [{
        'name': 'Triblend Android T-Shirt',       // Name or ID is required.
        'id': '12345',
        'price': '15.25',
        'brand': 'Google',
        'category': 'Apparel',
        'variant': 'Gray',
        'list': 'Search Results',
        'position': 1,
        'quantity': 1
       }]
     }
   }
);
```

## Customizations ##
The tracking extension uses three twig templates to generate its code. These templates can be overridden by files with the same name inside your theme folder.

### tracking_footer.twig ###
This snippet is added at the end of the page body and generates all configured tracking provider snippets

### tracking_header.twig ###
This snippet is added inside the page head and includes the necessary JS scripts

### tracking_page.twig ###
This snippet is added at start of the body and inserts the default cnTracking.trackPage() call.