README.md

ngAnalytics

AngularJS Directive for Google Analytics Embed API

German tutorial on FLYACTS website

For Contribution and Pull-Requests

Please use the develop-branch!!!

Functionality

• Authorization
• Add DataCharts
• Add ViewSelectors
• Connect DataCharts with ViewSelectors
• Create Reports

Installation

• bower install nganalytics or bower install fly-analytics
• or download src/ng-analytics[.min].js
• or download latest release

Usage

• include ng-analytics[.min].js in your index.html before your module definition

<script type="text/javascript" src="src/ng-analytics.min.js"></script>

• add the ng-analytics module to your module/app dependencies

var myApp = angular.module('myApp', ['ngAnalytics']);

• set your Google Analytics clientId in your run block or use Service Tokens (see ng-analytics-auth)

// inject ngAnalyticsService
myAppModule.run(['ngAnalyticsService', function (ngAnalyticsService) {
    ngAnalyticsService.setClientId('YOUR_CLIENTID'); // e.g. xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com
}]);

• add ng-analytics directives to your DOM

Directives

Authorization - ng-analytics-auth

Handles user authorization with Google. Accepts service-auth-token attribute to set the auth token of a service account (accepts a string)

Usage

<ng-analytics-auth label="Hallo:&nbsp;" hide-on-auth="true" auth-container="embed-api-auth-container"></ng-analytics-auth>

Attributes

• label (optional, default: Google default) - string with label of user account (e.g. "You are logged in as: " -> result: "You are logged in as: xxxxx@googlemail.com")
• hide-on-auth (optional, default: 'false') - bool-string if account string (see "label") should be hidden after authorization
• auth-container (optional, default: 'embed-api-auth-container') - string for the id of the created DOM-element

ViewSelector - ng-analytics-view

Shows dropdowns to switch views for a website.

Usage

<ng-analytics-view view-selector-container="view-selector-container" auth-container="embed-api-auth-container"></ng-analytics-view>

Attributes

• auth-container (optional, default: 'embed-api-auth-container') - string of the id of the auth-container - required to connect view with the authorization
• view-selector-container (optional, default: 'view-selector-container') - string for id of the created DOM-element

DataChart - ng-analytics-chart

Adds a chart and can be connected to a viewSelector.

Usage

<ng-analytics-chart chart="chart" view-selector-container="view-selector-container" auth-container="embed-api-auth-container"></ng-analytics-chart>

Attributes

• chart (required) - object (scope variable) for a google analytics ('ids' are not necessary if connected with viewSelector, 'container' is required to build DOM-nodes and inject the Google chart-object) - e.g.

{
    reportType: 'ga',
    query: {
        metrics: 'ga:sessions',
        dimensions: 'ga:date',
        'start-date': '30daysAgo',
        'end-date': 'yesterday',
        ids: 'ga:XXXXXX' // put your viewID here or leave it empty if connected with a viewSelector
    },
    chart: {
        container: 'chart-container-1', // id of the created DOM-element
        type: 'LINE',
        options: {
            width: '100%'
        }
    }
};

• view-selector-container (optional) - string of id for connected viewSelector
• auth-container (optional, default: 'embed-api-auth-container') - string of the id of the auth-container - required to connect chart with the authorization

Report - ng-analytics-report

Adds report functionality to angular. Sends single or multiple report-queries and get informed about the repsonse.

Usage

<ng-analytics-report queries="queries" auth-container="embed-api-auth-container" view-selector-container="view-selector-container"></ng-analytics-report>

Attributes

• queries (required) - array of report-query object (scope variable) (query. ids is required for each report-query if not connected with viewSelector, e.g.

[{
    query: {
        ids: 'ga:xxxxxx',  // put your viewID here
        metrics: 'ga:sessions',
        dimensions: 'ga:city'
    }
}];

• view-selector-container (optional) - string of id for connected viewSelector
• auth-container (optional, default: 'embed-api-auth-container') - string of the id of the auth-container - required to connect report with the authorization

Active Users in realtime - ng-analytics-active-users

Adds a active user counter.

Usage

<ng-analytics-active-users view-selector-container="view-selector-container" auth-container="embed-api-auth-container"></ng-analytics-active-users>

Attributes

• view-selector-container (optional, required if defaultIds not set) - string of id for connected viewSelector
• auth-container (optional, default: 'embed-api-auth-container') - string of the id of the auth-container - required to connect active user code with the authorization
• default-ids (optional, required if view-selector-container not set) - object with configuration and required ids-property

$scope.defaultIds = {
    ids: 'ga:XXXXXX'
};

• active-users-container (optional, default: 'active-users-container') - string for id of the created DOM-element
• label (optional, default: 'Active Users') - string for the label
• increase-class (optional, default: 'is-increasing') - css-class name, which is set, if user count has increased (class will be removed after 3 seconds)
• decrease-class (optional, default: 'is-decreasing') - css-class name, which is set, if user count has decreased (class will be removed after 3 seconds)

Events

AngularJS events which are triggered by the directive.

• $gaReportSuccess - triggered after all report requests finished successfully, returns results of the queries and the connected DOM-element to easily process the data and put it in the DOM (like using chart.js)

$rootScope.$on('$gaReportSuccess', function (event, response, element) {
    // process the 'response' and put it in the 'element'
});

• $gaReportError - triggered if a report request failed, returns results of the query and the connected DOM-element to easily process the error-data and put it in the DOM

$rootScope.$on('$gaReportError', function (event, response, element) {
    // process the error 'response' and put it in the 'element'
});