social-widget-tracker.md

socialWidgetTracker

This guide explains what the socialWidgetTracker plugin is and how to integrate it into your analytics.js tracking implementation.

Overview

The socialWidgetTracker automatically adds social tracking for the official Twitter tweet/follow buttons and the Facebook like button. If you have the official Twitter or Facebook buttons on your page and you've enabled the socialWidgetTracker plugin, user interactions with those buttons will be automatically tracked.

Usage

To enable the socialWidgetTracker plugin, run the require command, specify the plugin name 'socialWidgetTracker', and pass in the configuration options (if any) you want to set:

ga('require', 'socialWidgetTracker', options);

Options

The following table outlines all possible configuration options for the socialWidgetTracker plugin. If any of the options has a default value, the default is explicitly stated:

Name	Type	Description
fieldsObj	Object	See the common options guide for the fieldsObj description.
hitFilter	Function	See the common options guide for the hitFilter description.

Default field values

The socialWidgetTracker plugin sets the following default field values on all hits it sends. To customize these values, use one of the options described above.

Facebook like button

Field	Value
hitType	'social'
socialNetwork	'Facebook'
socialAction	'like' or 'unlike' (depending on the button state)
socialTarget	The URL the button was registered with.

Twitter tweet button

Field	Value
hitType	'social'
socialNetwork	'Twitter'
socialAction	'tweet'
socialTarget	The widget's data-url attribute or the URL of the current page.

Twitter follow button

Field	Value
hitType	'social'
socialNetwork	'Twitter'
socialAction	'follow'
socialTarget	The widget's data-screen-name attribute.

Methods

The following table lists all methods for the socialWidgetTracker plugin:

Name	Description
remove	Removes the socialWidgetTracker plugin from the specified tracker, removes all event listeners registered with the social SDKs, and restores all modified tasks to their original state prior to the plugin being required.

For details on how analytics.js plugin methods work and how to invoke them, see calling plugin methods in the analytics.js documentation.

Examples

Basic usage

In most cases, this plugin needs no customization:

ga('require', 'socialWidgetTracker');

Sending events instead of social interaction hits

If you want to send events instead of social interaction hits, you can map the hit field values via the hitFilter option:

ga('require', 'socialWidgetTracker', {
  hitFilter: function(model) {
    // Changes the hit type from `social` to `event`.
    model.set('hitType', 'event');

    // Maps the social values to event values.
    model.set('eventCategory', model.get('socialNetwork'));
    model.set('eventAction', model.get('socialAction'));
    model.set('eventLabel', model.get('socialTarget'));

    // Unsets the social values.
    model.set('socialNetwork', null);
    model.set('socialAction', null);
    model.set('socialTarget', null);
  }
});