ember-google-analytics-embed

Ember Google Analytics Embed

Ember Google Analytics Embed is an addon for quickly building custom Google Analytics dashboards in your Ember.js app, using the Google Analytics Embed API.

The addon exposes the following components to use in your templates:

• Bar Chart (ga-embed-bar-chart)
• Column Chart (ga-embed-column-chart)
• Geo Chart (ga-embed-geo-chart)
• Line Chart (ga-embed-line-chart)
• Pie Chart (ga-embed-pie-chart)
• Table (ga-embed-table)

The addon also enables Analytics user authorization using the authorization (ga-embed-authorize) component and view selection via the view selector (ga-embed-view-selector) component.

Demos

Check out the Embed API demos page for examples.

Installation

ember install ember-google-analytics-embed

Setup

To authorize your application to access the Google Analytics API, you must create a Client ID from the Google API Console. When you've obtained your Client ID, add it to your environment file. If you are using Geo Charts, you must also include an API Key, for accessing the Google Maps Javascript API. Both these APIs must be enabled from your API console and have the right origins/referrers set.

// config/environment.js
ENV['google-analytics-embed'] = {
  clientId: 'YOUR_CLIENT_ID',
  apiKey: 'YOUR_API_KEY'
};

Authorization

There are two ways to authorize users: through the authorization flow, requiring a user to click and authenticate, or via an access token sent from your server.

Adding the base ga-embed-authorize component to your templates will create a 'Sign in to Google Analytics' button and handle the authorization flow automatically:

{{ga-embed-authorize}}

Inject the ga-embed service into your templates to conditionally show/hide elements:

{{#if gaEmbed.isAuthorized}}
  // Add visualizations here
{{/if}}

The ga-embed service also exposes information about the current authorized user:

{{log gaEmbed.authorizedUser}}
// => { email: '[e-mail]', imageUrl: '...', name: 'Foo Bar' }

Sign Out

To enable the user to sign out, inject the ga-embed service into the consuming object and create the following action.

gaEmbed: service(),

actions: {
  signOut() {
    get(this, 'gaEmbed').signOut().then(() => {
      // Returns a promise when complete
    });
  }
}

Access Token Authorization

To remove the user auth flow, you may return an access token from your server. Simply pass the access token to the ga-embed-authorize component. You can find more information on setting up server side authorization here.

{{ga-embed-authorize accessToken=analyticsAccessToken}}

Visualizations

Each visualization accepts two main attributes, a query and an options hash.

Query

To get data from our Google Analytics property, we must build a query using the Google Reporting API. The example below shows a pie chart of sessions, segmented by country. It limits the data to the last 30 days up until today and requests just the top ten results.

{{ga-embed-pie-chart
    query=(hash
      ids="YOUR_PROPERTY_ID"
      metrics="ga:sessions"
      dimensions="ga:country"
      start-date="30daysAgo"
      sort="-ga:sessions"
      max-results=10
      end-date="today"
    )}}

Options

An options hash may be passed to each chart, allowing full configuration of the visualization.

{{ga-embed-pie-chart query=query options=options}}

Individual options properties may also be passed and can be dynamically updated.

{{ga-embed-pie-chart
    query=query
    options=options
    title="Sessions by country"
    is3D=pieChartIs3D
    }}

Components

Bar Chart

Creates a bar chart visualization and accepts the following configuration options.

{{ga-embed-bar-chart query=query options=options}}

Column Chart

Creates a column chart visualization and accepts the following configuration options.

{{ga-embed-column-chart query=query options=options}}

Geo Chart

Creates a geo chart visualization and accepts the following configuration options. This component lazy-loads the Google Maps Geocoding API.

The region property can be dynamically updated and is validated before the chart is updated to ensure a valid region code is used.

{{ga-embed-geo-chart query=query options=options region=region}}

Line Chart

Creates a line chart visualization and accepts the following configuration options.

{{ga-embed-line-chart query=query options=options}}

Pie Chart

Creates a pie chart visualization and accepts the following configuration options.

To transform a pie chart into a donut chart, simply add a value for the pie hole.

{{ga-embed-pie-chart query=query options=options pieHole=0.4}}

Table

Creates a table visualization and accepts the following configuration options.

{{ga-embed-table query=query options=options}}

Loading State

Each visualization has a loading state class of .ga-embed-visualization-loading, which you can customize in your CSS. The classes set on visualizations allow for custom loading states per visualization.

<div id="ember123" class="ga-embed-visualization ga-embed-chart ga-embed-line-chart ga-embed-visualization-loading">...</div>

Auto Resizing

By default, visualizations auto resize on window resize. To disable auto resizing, set responsiveResize=false on the visualization.

{{ga-embed-line-chart query=query options=options responsiveResize=false}}

Debouncing

When dynamically updating many properties on a visualization, it may be beneficial to debounce executing a new render. To do so, the visualization accepts a debounce value in milliseconds (ms).

{{ga-embed-line-chart query=query options=options debounce=100}}

View Selection

The ga-embed-view-selector component allows the user to select a view from any property they are authorized on. Add the view selector component to your template.

{{#if gaEmbed.isAuthorized}}
  {{ga-embed-view-selector ids=(mut viewIds) onChange=(action 'customAction')}}
{{/if}}

Use the mutable property in your queries:

{{ga-embed-pie-chart
    query=(hash
      ids=viewIds
      // ...
    )}}

Querying the Reporting API

The gaEmbed service enables a quick method to query data from analytics without directly using a visualization. This can be useful for querying the Google Analytics Reporting API and using the data in your own custom components.

get(this, 'gaEmbed').getData({
  'ids': 'YOUR_PROPERTY_ID',
  'metrics': 'ga:sessions',
  'dimensions': 'ga:date',
  'start-date': '30daysAgo',
  'end-date': 'yesterday'
}).then(data => {
  console.log(data);
}).catch(err => {
  console.log(err);
});

Using Google Analytics Embed API

• Google Embed API

  • Component Reference
  • Examples

• Google Charts API

• Google Reporting API

  • Dimensions & Metrics Explorer

Contributing

A crude dummy app demonstrates all the functionality of the addon. To view the dummy app, clone the repo and simply create a .env file with the following information:

# .env
GOOGLE_API_KEY=YOUR_API_KEY
GOOGLE_CLIENT_ID=YOUR_CLIENT_ID

Then start the server using:

ember serve