NAME
Net::Google::Analytics::MeasurementProtocol - send Google Analytics user interaction data from Perl
SYNOPSIS
use Net::Google::Analytics::MeasurementProtocol;
my $ga = Net::Google::Analytics::MeasurementProtocol->new(
tid => 'UA-XXXX-Y',
);
# Now, instead of this JavaScript:
# ga('send', 'pageview', {
# 'dt': 'my new title'
# });
# you can do this, in Perl:
$ga->send( 'pageview', {
dt => 'my new title',
dl => 'http://www.example.com/some/page',
});DESCRIPTION
This is a Perl interface to Google Analytics Measurement Protocol, allowing developers to make HTTP requests to send raw user interaction data directly to Google Analytics servers. It can be used to tie online to offline behaviour, sending analytics data from both the web (via JavaScript) and from the server (via this module).
CONSTRUCTOR
new( %options )
new( \%options )
my $ga = Net::Google::Analytics::MeasurementProtocol->new(
tid => 'UA-1234567-8',
aip => 1,
cid => $some_UUID_version4,
);Creates a new object with the provided information. There are many options to customize behaviour.
Required parameters:
tid String. This is the tracking ID / web property ID. You should have gotten this from your Google Analytics account, and it looks like
"UA-XXXX-Y". All collected data is associated by this ID.
Parameters with default values
v (for "version") Number string. Defaults to '1', which is the current version (March 2016). This is the protocol version to use. According to Google, this will only change when there are changes made that are not backwards compatible.
aip (for "anonymize ip") Boolean. Defaults to 1. If set to true, the IP address of the sender (your server) will be anonymized.
cid (for "client id") String with UUID version 4. Defaults to a random UUID created for this object (staying the same for as long as the object lives). This anonymously identifies a particular user, device, or browser instance. For the web, this is generally stored as a first-party cookie with a two-year expiration. For mobile apps, this is randomly generated for each particular instance of an application install.
It is recommended that you set this to a single value and use that same value throughout your app.
cd (for "screen name") String. Defaults to "/". The screen name of the 'screenview' hit.
an (for "application name") String. defaults to "My App". Specifies the application name.
ds (for "data source") String. Defaults to "app". Indicates the data source of the hit.
ua (for "user agent") String. Defaults to "Net::Google::Analytics::MeasurementProtocol/$VERSION".
ua_object
Object. Either a Furl object, LWP::UserAgent or something with inherits from LWP::UserAgent, like WWW::Mechanize. Defaults to using Furl.
Other parameters
There are many, many parameters available. Please check the official Measurement Protocol Parameter Reference.
METHODS
send( $type, \%params )
Arguments:
$type- The hit type. Can be pageview, screenview, event, transaction, item, social, exception or timing.\%params- Hashref with any other options you want to send to Google Analytics.
Returns: true/false, whether the request was accepted by Google Analytics servers or not. NOTE: If you set the debug flag, it will return the full response object for inspection. See the "DEBUGGING" section below for more information.
DEBUGGING
According to Google Analytics' documentation, the Measurement Protocol will return a 2xx status code if the HTTP request was received. The Measurement Protocol does not return an error code if the payload data was malformed, or if the data in the payload was incorrect or was not processed by Google Analytics.
If you do not get a 2xx status code, your call to send will return false. If it does, you should NOT retry the request. Instead, you should stop and correct any errors in your HTTP request.
Fortunately, Google Analytics offers a validation server for your hits, without risk of damaging your production analytics data. To access it, simply set the 'debug' flag to true when creating the object:
my $ga = Net::Google::Analytics::MeasurementProtocol->new(
tid => 'UA-XXXX-Y',
debug => 1,
);Now, calls to send will make the request to Google's validation servers and return the entire response object, which should contain JSON indicating whether your request is valid or not, and if not, why it wasn't accepted. So you can do something like this:
use Data::Printer;
use JSON;
# assuming the 'debug' flag is on:
my $res = $ga->send( 'pageview', { dl => 'http://www.example.com' } );
my $data = JSON::decode_json( $res->decoded_content );
my $is_valid = $data->{hitParsingResult}[0]{valid};
if (!$is_valid) {
p $data;
}SEE ALSO
Google Analytics Measurement Protocol Parameter Reference
Google Analytics Measurement Protocol Reference
Google Analytics Measurement Protocol - Validating Hits
Measurement Protocol Developer Guide
LICENSE AND COPYRIGHT
Copyright 2015-2016 Breno G. de Oliveira <garu at cpan.org>. All rights reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.
DISCLAIMER OF WARRANTY
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.