123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274 |
- = sfGoogleAnalyticsPlugin plugin =
- Easily add [http://www.google.com/analytics Google Analytics] tracking code to your presentation layer.
- ''This documentation is a work in progress. Thank you for your patience.''
- == Installation ==
- === 1. Install ===
- You can install using the `plugin-install` task:
- {{{
- php symfony plugin-install sfGoogleAnalyticsPlugin
- }}}
- You can also pull the code directly from the [http://svn.symfony-project.org/plugins/sfGoogleAnalyticsPlugin/trunk Subversion repository] using a `svn checkout` or the `svn:externals` property on your project's `/plugins` directory.
- Once the plugin code is accessible to your project, you need to add the `sfGoogleAnalyticsFilter` to your filter chain:
- {{{
- #!yaml
- rendering: ~
- security: ~
- # insert your own filters here
- sf_google_analytics_plugin:
- class: sfGoogleAnalyticsFilter
- cache: ~
- common: ~
- execution: ~
- }}}
- ''NOTE: This is the symfony 1.1 `filters.yml` file. The equivalent symfony 1.0 file looks slightly different.''
- === 2. Configure ===
- Basic configuration is done in your application's `app.yml` file:
- {{{
- #!yaml
- all:
- sf_google_analytics_plugin:
- enabled: on
- profile_id: XX-XXXXX-X
- tracker: google
- }}}
- You'll have to copy the `profile_id` value out of the tracking code Google supplies for your site profile. This value typically starts with the letter U and ends with a single digit.
- This plugin defaults to using the older `urchin` tracker. To take advantage of the latest featureset of Google Analytics, change the `tracker` value to `google` for the older snippet or `asynchronous` for the more performant one. This will insert the new `ga.js` tracking code into your project.
- == Advanced Usage ==
- This plugin provides much more functionality than a simple insert of your tracking code. Here are some highlights:
- === How do I customize the name a page is tracked as? ===
- If you would like to track a certain page as something other than what appears in the browser address bar, you can do so by modifying the `page_name` parameter in `module.yml`:
- {{{
- #!yaml
- all:
- myAction:
- sf_google_analytics_plugin:
- params:
- page_name: something_else
- }}}
- For finer control over when the alternate page name is used, you can access the tracker object directly in your action. This also exposes additional funcionality.
- ==== Option: `use_flash` ====
- For example, if you want to track a successful form submission for a form that redirects to the same page on success and on error:
- {{{
- #!php
- <?php
- class mainActions extends sfActions
- {
- public function executeContact()
- {
- // form submission logic...
- if ($success)
- {
- $this->getTracker()->setPageName('/contact/success', array(
- 'use_flash' => true,
- ));
- $this->setFlash('feedback', 'Thank you!');
- $this->redirect('main/contact');
- }
- }
- }
- }}}
- In this example, the request after the successful form post will be tracked as `/contact/success`.
- ==== Option: `is_route` ====
- One more option available is the `is_route` option. When this flag is applied, the string provided for a page name will be passed through `sfRouting` before being added to the page. Using this option allows you to centralize all URLs, those real and for tracking purposes only, in your application's `routing.yml` file:
- {{{
- #!yaml
- contact:
- url: /contact
- param: { module: main, action: contact }
- # be sure the tracking rule comes AFTER the real rule so the application
- # doesn't use it for any url_for('main/contact') calls
- track_contact:
- url: /contact/success
- param: { module: main, action: contact }
- }}}
- {{{
- #!php
- <?php
- class mainActions extends sfActions
- {
- public function executeContact()
- {
- // form submission logic...
- if ($success)
- {
- $this->getTracker()->setPageName('@track_contact', array(
- 'use_flash' => true,
- 'is_route' => true,
- ));
- $this->setFlash('feedback', 'Thank you!');
- $this->redirect('@contact');
- }
- }
- }
- }}}
- === How do I selectively disable tracking? ===
- You can easily configure the tracking code for a single module or even a single action by using the `module.yml` configuration file:
- {{{
- #!yaml
- all:
- # disable tracking for this module...
- sf_google_analytics_plugin:
- params:
- enabled off
-
- # ...or for a single action
- index:
- sf_google_analytics_plugin:
- params:
- enabled off
- }}}
- Alternatively, you can access the tracker object directly from inside your action:
- {{{
- #!php
- <?php
- class mainActions extends sfActions
- {
- public function executeIndex()
- {
- $this->getTracker()->setEnabled(false);
- }
- }
- }}}
- === Can I insert the tracking code at the top of my page? ===
- You can configure this in `app.yml`:
- {{{
- #!yaml
- all:
- sf_google_analytics_plugin:
- profile_id: XX-XXXXX-X
- insertion: top
- }}}
- === Can I track demographic information? ===
- You can expose whatever information you store on your users (that your privacy policy allows, of course) to Google Analytics. This is best done in your sign-in routine. For example, if you're using [wiki:sfGuardPlugin]:
- {{{
- #!php
- <?php
- class myUser extends sfGuardSecurityUser
- {
- /**
- * Overload to add custom tracking variables to the current user.
- *
- * Variables are added using flash, assuming sign in will be followed by a
- * redirect.
- *
- * @see sfGuardSecurityUser
- */
- public function signIn($user, $remember = false, $con = null)
- {
- parent::signIn($user, $remember, $con);
- // assign tracking variables
- if ($gender = $user->getProfile()->getGender())
- {
- $this->getTracker()->setVar('gender/'.$gender, array(
- 'use_flash' => true,
- ));
- }
- if ($this->hasCredential('moderator'))
- {
- $this->getTracker()->setVar('userType/moderator', array(
- 'use_flash' => true,
- ));
- }
- }
- }
- }}}
- == Changelog ==
- === Version 1.1.2 ===
- * Fixed symfony 1.1 compatibility in `sfLogger` interactions.
- === Version 1.1.1 ===
- * Fixed Javascript case-sensitivity bug.
- === Version 1.1.0 ===
- * '''Added support for new Google Javascript library (`ga.js`).'''
- * Updated API to include more human-readable method names.
- * Added support for tracking e-commerce transactions.
- * Added option to parse tracking argument with `sfRouting`.
- * Added option to defer many tracker calls to the next response, similar to `sfFlash` storage (helpful for redirects).
- === Version 1.0-RC1 ===
- * Renamed plugin from sfUrchinPlugin to sfGoogleAnalyticsPlugin.
- === Version 0.3.1-beta ===
- * Bugfix to insertion top to accommodate `<body>` tags with attributes.
- === Version 0.3.0-beta ===
- * Broke filter logic into protected methods for easy overloading.
- * Added insertion configuration.
- === Version 0.2.0-beta ===
- * Added support for SSL requests.
- * Added mixin methods to actions for easy modification of initialization variables and parameters.
- * Added escaping of Javascript values.
- === Version 0.1.0-beta ===
- * Initial public release.
- == Maintainers ==
- Kris Wallsmith
|