The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Mojar::Guide::GoogleAnalytics - Reporting from Google Analytics

SETUP

Before you start coding against the API, first ensure you can get results via the query explorer (see link below). To use that, you log into GA using credentials that have access to the appropriate analytics account. Typically this means logging out of the account you use for email and logging back in with an email account that someone has authorised to access the analytics account (although there is no technical problem with these being the same email account).

In the query browser you also select a profile. If your analytics account has multiple profiles, take care which one you test, and ensure that you use the same one when coding against the API.

In order to use the API, you will need

auth_user

The API user that Google created for you when you registered to use the API. This is typically something of the form

  123456789@developer.gserviceaccount.com
private_key

The private key you generated to use against the API. This is typically held in a file (with a .pem suffix) and slurped up each time you want to use it. Check that the file contains a line for "BEGIN PRIVATE KEY" and also for "END PRIVATE KEY".

profile_id

A string of digits identifying the appropriate profile; exactly the same one you tested earlier.

Then create your analytics object.

  my $analytics = Mojar::Google::Analytics->new(
    auth_user => q{123456789@developer.gserviceaccount.com},
    private_key => $pk,
    profile_id => '123456'
  );

You may optionally disable timeouts (default 60 sec) by including

  timeout => 0

FETCH RESULTS

Build the Request

  $analytics->req(
    dimensions => [qw(pagePath)],
    metrics => [qw(entrances exits bounces)],
    sort => 'pagePath',
    start_date => $day,
    end_date => $day,
    start_index => $start,
    max_results => $max_resultset
  );

For the first iteration, start_index should be 1. It is often quicker/easier to test with yesterday's data than today's data. I usually set max_results to be 10_000, so any result set larger than that is fetched in batches.

Get the Result Set

  $res = $analytics->fetch;
  if (defined $res and $res->success) {
    # Success
  }
  else {
    # Failure: check $analytics->res->error (or ->code or ->message)
  }

If you have success you will want to extract the data from the resultset within res; if you have failure you should abort.

Once you have a resultset, check its headers

  $res->{column_headers}[$i]{name}

to ensure they are what your code expects. Then iterate through

  @{$res->rows}

processing your data as appropriate.

If you are using DBI you may find you enjoy faster inserts using columns:

  my @tuple_status;
  my $qty = $insert->execute_array(
    {ArrayTupleStatus => \@tuple_status},
    @{$res->columns}
  );

Update Your Cursor

  $start = $1 if $res->{next_link} and $res->{next_link} =~ /start-index=(\d+)/;

so that you can go round the next iteration with the start_index that the API said to use next.

DEBUGGING

To see the communications between client and server, simply set the MOJO_USERAGENT_DEBUG variable in your environment. For example, in bash this would be

  export MOJO_USERAGENT_DEBUG=1

and then set it to 0 (or unset it completely) to disable all that debug output.

To view an object, you already have dumper available.

  use Mojar::Util 'dumper';
  $self->log->debug(dumper $res);

SEE ALSO

https://www.google.com/analytics

for overview material,

https://developers.google.com/analytics/devguides/reporting/core/v3/reference

for the reference documentation, and

http://ga-dev-tools.appspot.com/explorer

for the query explorer.