Support and Documentation

Integrating Google Analytics

The Google Analytics plugin collects data through Google Analytics from which Brightspot generates reports as described in Viewing analytics at the item level and Site-level analytics. When you integrate Brightspot with Google Analytics, you need to make configuration settings on your Google Analytics account as well as within Brightspot.

. See also:
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 Brightspot.

Administrators perform these tasks.

Creating a Google Analytics account

  1. Create a Google Analytics account as described in Get started with Analytics.

  2. In your Google Analytics account, make the following settings:

    1. Tracking ID, for example UA-118898499-1

    2. View ID, for example 174965383

Creating a Google API service account

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

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

Adding the Google Analytics Integration
Procedure. To add the Google Analytics Integration to Brightspot:

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

  2. In the Sites widget, select a site to integrate with Google Analytics, or select Global to integrate all your sites.

  3. Under Integrations, click |mi-add_circle_outline| at the top of the page and select Google Analytics from the list of choices.

  4. In the Tracking ID field, enter the tracking ID you assigned as described in the section Creating a Google Analytics account.

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

  5. Click Save.

To configure your Brightspot site to retrieve Google Analytics information, see Configuring a site to retrieve Google Analytics for instructions.

Configuring a site to retrieve Google Analytics
Procedure. To configure a Brightspot site to retrieve Google Analytics:

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

  2. In the Sites widget, select a site to integrate with Google Analytics.

    Tip

    If you only have one set of credentials for your Google Analytics account, you can set those credentials under the Global site and they will cascade down to all of your other sites. The value in the Credentials field is the only value that cascades down to your other sites. You must still enter the View ID and remaining settings for each site that you want to retrieve Google Analytics.

  3. Under Integrations, scroll to, and expand, Google Analytics .

  4. Using the table below as a reference, enter settings for the Google Analytics plugin.

    google-analytics-credentials.png

  5. Click Save.

  6. Repeat steps 2-5 for each site that you want to retrieve Google Analytics data.

Table 62. Google Analytics settings—Integrations tab

Field

Description

Credentials

Private JSON key that was downloaded from the Google API service account as described in Creating a Google API service account. Copy the entire contents of the file into this field, including the opening and closing braces. You can set the Credentials at the Global site level and have that value cascade down to all of your other sites, or you can enter unique credentials for each site if you have multiple Google Analytics credentials you use. Credentials entered at the site level always supercede those entered at the Global level.

View ID

ID of the view that was generated in your Google Analytics account as described in Creating a Google Analytics account. You can configure your account to have multiple views, each with a different set of data.

Page Report

Enabling this setting allows the import of page views data, at the per-page level, from Google Analytics.

Site Reports

Type of reports to generate about traffic to your site:

  • Device categories—Indicates types of devices visitors are using on your site.

  • Demographics—Provides gender and age brackets.

  • Referrals—Indicates how visitors arrive at your site, such as referral traffic from other sites or clicking links in search engines.

  • Visits—Provides general information about site visits, such as number of sessions, users, and session duration.



Accessing reports

Brightspot uses the class GoogleAnalyticsProcessTask to retrieve data from the Google Analytics service using the configuration you make as described in Configuring a site to retrieve 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 snippet shows how a modification to a Page can listen for TASK_COMPLETE messages from GoogleAnalyticsProcessTask and then perform a task.

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;

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

    @Indexed 2
    Date lastUpdate;

    @Override
    protected void receiveMessage(String key, Object... args) { 3
        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();
                    }
                }
            }
        }
    }
}

1

Prefixes the internal names of this page's fields with googleAnalytics.

2

Indexes the lastUpdate field, which contains the date that analytic data was last collected for the page.

3

Overrides the receiveMessage method, which listens for the TASK_COMPLETE message from GoogleAnalyticsProcessTask. 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.

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;

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

    @Indexed
    Date lastUpdate;

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

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

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

                TimeSeries pageViewTimeSeries = new TimeSeries(GoogleAnalytics.PAGE_VIEWS_TIME_SERIES_NAME);

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

            Site owner = siteModification.getOwner(); 5
            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()) { 6

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

1

Indexes the method getPageViewsLast24Hours. When Recalculation tasks runs, the page views for the page instance is updated.

2

Initializes the pageViews counter.

3

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 access to the page.

4

Increments the pageViews counter with the number of page views for the Global site.

5

Increments the pageViews counter with the number of page views for the owner site.

6

Increments the pageViews counter with the number of page views for all other sites with access to the page.

7

Returns the counter, reflecting the cumulative number of page views across all of the sites.