README

Symfony2 bundle for manage external tracking scripts/pixel trackers.

Introduction

This bundle allows you to manage pixeltrackers / script trackers your partners without interfering with user navigation :

Trackers can be managed from one or more classes, and are added via an event handler.
The display of trackers can be pushed after the page loads, or even with a timer
No more dependence to any JavaScript framework ;)

Installation

Composer

Add to composer.json in your project to require section:

...
    {
        "geekyhouse/external-tracking-bundle": "dev-master"
    }
...

Run command: php composer.phar install

Add this bundle to your application's kernel

//app/AppKernel.php
public function registerBundles()
{
    return array(
         // ...
        new GeekyHouse\ExternalTrackingBundle\ExternalTrackingBundle(),
        // ...
    );
}

Conﬁgure service in your YAML conﬁguration

You can overwrite bundle classes. Default values :

# app/conﬁg/conﬁg.yml
external_tracking:
	manager_class: GeekyHouse\ExternalTrackingBundle\Service\ExternalTrackingManager
	request_listener_class: GeekyHouse\ExternalTrackingBundle\EventListener\RequestListener
	extension_class: GeekyHouse\ExternalTrackingBundle\Twig\Extension\ExternalTrackingExtension

Custom events listeners

This bundle provides 2 events dispatchers that you can use :

geekyhouse.event.before_get_trackers : Called first when "getTrackers" is called
geekyhouse.event.after_get_trackers : Called juste before return when "getTrackers" is called

You can easily create a custom service which add datas just before writing trackers, like this :

# app/conﬁg/conﬁg.yml
services:
    my.custom.listener:
        class: My\Bundle\EventListener\CustomListener
        tags:
            - { name: kernel.event_listener, event: geekyhouse.event.before_get_trackers, method: beforeGetTrackers }
            - { name: kernel.event_listener, event: geekyhouse.event.after_get_trackers, method: afterGetTrackers }
        arguments: [@service_container]

// My/Bundle/EventListener/CustomListener.php
namespace My\Bundle\EventListener;

use GeekyHouse\ExternalTrackingBundle\Event\ExternalTrackingEvent;

class CustomListener
{

    private $container;

    public function __construct($container)
    {
        $this->container = $container;
    }

    public function beforeGetTrackers(ExternalTrackingEvent $event)
    {
        $UserManager = $this->container->get('my.user.manager');
        $this->ExternalTrackingManager->pushData(
            array(
                'user' => $UserManager->getCurrentUser()
            )
        );
    }

    public function afterGetTrackers(ExternalTrackingEvent $event)
    {
    }

}

In this example, we just add custom user datas on ExternalTrackingManager systematically.

Twig Extension

A Twig extension is given by default : GeekyHouse\ExternalTrackingBundle\Twig\Extension

It provides the function get_external_trackers which write your trackers on a page.

This function takes 2 arguments :

onDocumentReady (default TRUE) If TRUE, wait the DOM loading before writing the trackers.
timer (default 500) The time in milliseconds to wait before writing the trackers (after DOM loading if TRUE).

Use this function on a Twig template like this :

# base.html.twig
[...]
    {{ get_external_trackers(true, 500)|raw }}
[...]

Don't forget the |raw, or Twig will escape the JavaScript tags.

It's recomended to write this line at the end of the page.

This extension contains a private method, cleanJavascriptString, whose purpose is to convert PHP string into evaluable JavaScript string. This method is in bêta test currently, please tell us if you have some problem with it :)

geekyhouse / external-tracking-bundle

Maintainers

Details