Google Analytics

The Google Analytics plugin collects site data through the external Google Analytics service, from which Brightspot generates various types of reports. Report data is stored as records in the database, retrievable by custom widgets or applications.

Note

The reports generated by Google Analytics are separate from those generated by Brightspot Reports.

Configuring Google Analytics

To integrate Google Analytics with Brightspot, you must have a Google Analytics account and a Google API Service account, both of which generate values that you need to configure a Brightspot site to work with Google Analytics.

Administrators perform these tasks.

Creating a Google Analytics Account

  1. Create a Google Analytics account as described on this page: https://support.google.com/analytics/answer/1008015?hl=en.

    Your newly created account will include property and view settings.

  2. For Brightspot configuration purposes, record the following two settings in your Google Analytics account:

    • Tracking ID , for example, UA-118898499-1
    • View ID, for example, 174965383

Creating a Google API Service Account

Create a service account on the Google APIs site: https://console.developers.google.com/apis/credentials.

Create credentials using a service account key that is a JSON key type. The key is downloaded as a JSON file.

Configuring a Brightspot Site

  1. From the Navigation Menu, select Admin > Sites & Settings.

  2. Select a site with which to integrate Google Analytics.

  3. On the Plugins tab, scroll to “Feature Plugins” and select Google: Analytics.

  4. Click Save.

    Configuration options for Google Analytics are added to the Front-End tab.

  5. On the Front-End tab, scroll to “Integrations”.

  6. Click Add Google Analytics.

  7. In the Tracking ID field, enter the tracking ID that was generated in your Google Analytics account.

    The tracking ID generates a JavaScript snippet that is incorporated into your site pages. It enables tracking of your site by Google Analytics.

  8. Staying on the Front-End tab, scroll to “Google Analytics.”

  9. Using the following table as a reference, enter settings for the Google Analytics plugin.

  10. Click Save.

Google Analytics Settings–Front-End Tab
Field Description
Credentials The private JSON key that was downloaded from the Google API service account. Copy the entire contents of the file into this field, including the opening and closing braces.
View ID The ID of the view that was generated in your Google Analytics account. You can configure your account to have multiple views, each with a different set of data.
Page Report Basic information on each page viewed on the Brightspot site. This information can be used to sort by page view in dynamic lists, and to include page view totals in the Search Panel.

Site Reports

The type of reports to generate about traffic to the Brightspot site:

  • Device categories report indicates device types that access the site.
  • Demographics report indicates gender and age brackets.
  • Referrals report indicates the traffic sources to the Brightspot site, for example, referral traffic from other sites or search traffic from search engines.
  • Visits report provides general information about site visits, like number of sessions, users, and session duration.

Accessing Reports

Brightspot uses a repeating task, GoogleAnalyticsProcessTask, to retrieve data from the Google Analytics service and to save it in the database in one or more report formats, as set in the site configuration for Google Analytics.

When the GoogleAnalyticsProcessTask is complete, it sends a GoogleAnalyticsProcessTask.TASK_COMPLETE message to Brightspot. The message can be used to trigger further processing, such as recalculating indexed methods and retrieving report data.

The following example shows how a modification to a Page can receive TASK_COMPLETE messages from GoogleAnalyticsProcessTask.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
package brightspot.core.page;
import com.psddev.dari.db.Modification;
import com.psddev.dari.db.Recordable;
import com.psddev.dari.util.StringUtils;
import com.psddev.google.analytics.GoogleAnalytics;
import com.psddev.dari.util.ObjectUtils;
import java.util.Date;

@Recordable.FieldInternalNamePrefix("googleAnalytics.")
public class GoogleAnalyticsPageModification extends Modification<Page> {

   @Indexed
   Date lastUpdate;

   @Override
   protected void receiveMessage(String key, Object... args) {
      if (!StringUtils.isBlank(key) && key.startsWith(GoogleAnalytics.MESSAGE_REPORT_PAGE)) {
         if (!ObjectUtils.isBlank(args)) {
             Object endDate = args[0];

             if (args[0] != null && args[0] instanceof Date) {
                 Date newLastUpdate = (Date) args[0];

                 if (!ObjectUtils.equals(lastUpdate, newLastUpdate)) {
                     lastUpdate = newLastUpdate;
                     this.save();
                 }
             }
         }
     }
   }
}

In the previous snippet—

  • Line 9 uses the FieldInternalNamePrefix annotation to prefix the internal names of the fields with googleAnalytics.
  • Line 12 indexes the lastUpdate field, which contains the date that analytic data was last collected for the page.
  • Line 16–31 show the receiveMessages method, which processes the TASK_COMPLETE message from GoogleAnalyticsProcessTask. The date of the last analytics update is passed to the method. The method compares the passed-in date to the date last saved on the page. If the passed-in date is newer than the saved date, then the method saves the passed-in date.

You can also use modifications to access Google report data for objects that you want to report on. Use the TimeSeries and TimeSeriesValues classes to specify the time scope of data to be retrieved and reported on.

The following example calculates total page views for the last 24 hours for Page.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
package brightspot.core.page;

import com.psddev.cms.db.Site;
import com.psddev.dari.db.Modification;
import com.psddev.dari.db.Recordable;
import com.psddev.dari.util.StringUtils;
import com.psddev.google.analytics.GoogleAnalytics;
import com.psddev.timeseries.TimeSeries;
import com.psddev.timeseries.TimeSeriesValues;
import com.psddev.dari.util.ObjectUtils;
import java.util.Date;

@Recordable.FieldInternalNamePrefix("googleAnalytics.")
public class GoogleAnalyticsPageModification extends Modification<Page> {

   @Indexed
   Date lastUpdate;

   @Indexed
   public float getPageViewsLast24Hours() {
      long pageViews = 0;

      Site.ObjectModification siteModification = this.as(Site.ObjectModification.class);

      if (siteModification != null) {
         if (siteModification.isGlobal()) {

             TimeSeries pageViewTimeSeries = new TimeSeries(GoogleAnalytics.PAGE_VIEWS_TIME_SERIES_NAME);

             if (pageViewTimeSeries != null) {
                 pageViews += TimeSeriesValues.ofHours(24, getId(), pageViewTimeSeries).sum();
             }
         }

         Site owner = siteModification.getOwner();
         if (owner != null) {
             TimeSeries pageViewTimeSeries = new TimeSeries(GoogleAnalytics.PAGE_VIEWS_TIME_SERIES_NAME + "." + owner.getId());
             if (pageViewTimeSeries != null) {
                 pageViews += TimeSeriesValues.ofHours(24, getId(), pageViewTimeSeries).sum();
             }
         }

         for (Site site : siteModification.getConsumers()) {

             TimeSeries pageViewTimeSeries = new TimeSeries(GoogleAnalytics.PAGE_VIEWS_TIME_SERIES_NAME + "." + site.getId());
             if (pageViewTimeSeries != null) {
                 pageViews += TimeSeriesValues.ofHours(24, getId(), pageViewTimeSeries).sum();
             }
         }
      }
      return pageViews;
   }
}

In the previous snippet—

  • Line 19 indexes the method getPageViewsLast24Hours. When RecalculationTask runs, the page views for the page instance is updated.
  • Line 21 initializes the pageViews counter.
  • Line 23 links the Page state to an instance of Site.ObjectModification.class, enabling the following code to get the number of page views for all of the sites that have access to the page: global, the owner site, and any other sites that have been granted access to the page.
  • Line 26–33 increment the pageViews counter with the number of page views for the global site.
  • Line 35–41 increment the pageViews counter with the number of page views for the owner site.
  • Line 43–49 increment the pageViews counter with the number of page views for all other sites with access to the page.
  • Line 51 returns the counter, reflecting the cumulative number of page views across all of the sites.

See also: