Using this package you can easily retrieve data from Google Analytics.
Here are a few examples of the provided methods:
use Spatie\Analytics\Facades\Analytics;
use Spatie\Analytics\Period;
//fetch the most visited pages for today and the past week
Analytics::fetchMostVisitedPages(Period::days(7));
//fetch visitors and page views for the past week
Analytics::fetchVisitorsAndPageViews(Period::days(7));
Most methods will return an \Illuminate\Support\Collection object containing the results.
Support us
We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.
We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.
Installation
This package can be installed through Composer.
composer require spatie/laravel-analytics
Optionally, you can publish the config file of this package with this command:
php artisan vendor:publish --tag="analytics-config"
The following config file will be published in config/analytics.php
return [
/*
* The property id of which you want to display data.
*/
'property_id' => env('ANALYTICS_PROPERTY_ID'),
/*
* Path to the client secret json file. Take a look at the README of this package
* to learn how to get this file. You can also pass the credentials as an array
* instead of a file path.
*/
'service_account_credentials_json' => storage_path('app/analytics/service-account-credentials.json'),
/*
* The amount of minutes the Google API responses will be cached.
* If you set this to zero, the responses won't be cached at all.
*/
'cache_lifetime_in_minutes' => 60 * 24,
/*
* Here you may configure the "store" that the underlying Google_Client will
* use to store it's data. You may also add extra parameters that will
* be passed on setCacheConfig (see docs for google-api-php-client).
*
* Optional parameters: "lifetime", "prefix"
*/
'cache' => [
'store' => 'file',
],
];
How to obtain the credentials to communicate with Google Analytics
Getting credentials
The first thing you’ll need to do is to get some credentials to use Google API’s. I’m assuming that you’ve already created a Google account and are signed in. Head over to Google API’s site and select or create a project.
Next up we must specify which API’s the project may consume. Go to the API Library and search for "Google Analytics Data API".
Choose enable to enable the API.
Now that you’ve created a project that has access to the Analytics API it’s time to download a file with these credentials. Click "Credentials" in the sidebar. You’ll want to create a "Service account key".
On the next screen you can give the service account a name. You can name it anything you’d like. In the service account id you’ll see an email address. We’ll use this email address later on in this guide.
Go to the details screen of your created service account and select "keys", from the "Add key" dropdown select "Create new key".
Select "JSON" as the key type and click "Create" to download the JSON file.
Save the json inside your Laravel project at the location specified in the service_account_credentials_json key of the config file of this package. Because the json file contains potentially sensitive information I don't recommend committing it to your git repository.
Granting permissions to your Analytics property
I'm assuming that you've already created a Analytics account on the Analytics site and are using the new GA4 properties.
First you will need to know your property ID. In Analytics, go to Settings > Property Settings. Here you will be able to copy your property ID. Use this value for the ANALYTICS_PROPERTY_ID key in your .env file.
Now we will need to give access to the service account you created. Go to "Property Access Management" in the Admin-section of the property.
Click the plus sign in the top right corner to add a new user.
On this screen you can grant access to the email address found in the client_email key from the json file you download in the previous step. Analyst role is enough.
Usage
When the installation is done you can easily retrieve Analytics data. Nearly all methods will return an Illuminate\Support\Collection-instance.
Here are a few examples using periods
use Spatie\Analytics\Facades\Analytics;
//retrieve visitors and page view data for the current day and the last seven days
$analyticsData = Analytics::fetchVisitorsAndPageViews(Period::days(7));
//retrieve visitors and page views since the 6 months ago
$analyticsData = Analytics::fetchVisitorsAndPageViews(Period::months(6));
$analyticsData is a Collection in which each item is an array that holds keys date, visitors and pageViews
If you want to have more control over the period you want to fetch data for, you can pass a startDate and an endDate to the period object.
$startDate = Carbon::now()->subYear();
$endDate = Carbon::now();
Period::create($startDate, $endDate);
Provided methods
Visitors and page views
public function fetchVisitorsAndPageViews(Period $period): Collection
The function returns a Collection in which each item is an array that holds keys activeUsers, screenPageViews and pageTitle.
Visitors and page views by date
public function fetchVisitorsAndPageViewsByDate(Period $period): Collection
The function returns a Collection in which each item is an array that holds keys date, activeUsers, screenPageViews and pageTitle.
Total visitors and pageviews
public function fetchTotalVisitorsAndPageViews(Period $period): Collection
The function returns a Collection in which each item is an array that holds keys date, date, visitors, and pageViews.
Most visited pages
public function fetchMostVisitedPages(Period $period, int $maxResults = 20): Collection
The function returns a Collection in which each item is an array that holds keys fullPageUrl, pageTitle and screenPageViews.
Top referrers
public function fetchTopReferrers(Period $period, int $maxResults = 20): Collection
The function returns a Collection in which each item is an array that holds keys screenPageViews and pageReferrer.
User Types
public function fetchUserTypes(Period $period): Collection
The function returns a Collection in which each item is an array that holds keys activeUsers and newVsReturning which can equal to new or returning.
Top browsers
public function fetchTopBrowsers(Period $period, int $maxResults = 10): Collection
The function returns a Collection in which each item is an array that holds keys screenPageViews and browser.
Top countries
public function fetchTopCountries(Period $period, int $maxResults = 10): Collection
The function returns a Collection in which each item is an array that holds keys screenPageViews and country.
Top operating systems
public function fetchTopOperatingSystems(Period $period, int $maxResults = 10): Collection
The function returns a Collection in which each item is an array that holds keys screenPageViews and operatingSystem.
All other Google Analytics queries
For all other queries you can use the get function.
public function get(Period $period, array $metrics, array $dimensions = [], int $maxResults = 10, array $orderBy = [], int $offset = 0, ?FilterExpression $dimensionFilter = null, bool $keepEmptyRows = false, ?FilterExpression $metricFilter = null): Collection
Here's some extra info on the arguments you can pass:
Period $period: a Spatie\Analytics\Period object to indicate that start and end date for your query.
array $metrics: an array of metrics to retrieve. You can find a list of all metrics here.
array $dimensions: an array of dimensions to group the results by. You can find a list of all dimensions here.
int $maxResults: the maximum number of results to return.
array $orderBy: of OrderBy objects to sort the results by.
init $offset: Defaults to 0, you can use this in combination with the $maxResults param to have pagination.
bool $keepEmptyRows: If false or unspecified, each row with all metrics equal to 0 will not be returned. If true, these rows will be returned if they are not separately removed by a filter.
For example:
$orderBy = [
OrderBy::dimension('date', true),
OrderBy::metric('pageViews', false),
];
FilterExpression $dimensionFilter: filter the result to include only specific dimension values. You can find more details here.
For example:
use Google\Analytics\Data\V1beta\Filter;
use Google\Analytics\Data\V1beta\FilterExpression;
use Google\Analytics\Data\V1beta\Filter\StringFilter;
use Google\Analytics\Data\V1beta\Filter\StringFilter\MatchType;
$dimensionFilter = new FilterExpression([
'filter' => new Filter([
'field_name' => 'eventName',
'string_filter' => new StringFilter([
'match_type' => MatchType::EXACT,
'value' => 'click',
]),
]),
]);
FilterExpression $metricFilter: filter applied after aggregating the report's rows, similar to SQL having-clause. Dimensions cannot be used in this filter. You can find more details here.
For example:
use Google\Analytics\Data\V1beta\Filter;
use Google\Analytics\Data\V1beta\FilterExpression;
use Google\Analytics\Data\V1beta\Filter\NumericFilter;
use Google\Analytics\Data\V1beta\NumericValue;
use Google\Analytics\Data\V1beta\Filter\NumericFilter\Operation;
$metricFilter = new FilterExpression([
'filter' => new Filter([
'field_name' => 'eventCount',
'numeric_filter' => new NumericFilter([
'operation' => Operation::GREATER_THAN,
'value' => new NumericValue([
'int64_value' => 3,
]),
]),
]),
]);
Testing
Faking
To fake calls within the package in your own project you can use the fake method on the Spatie\Analytics\Facades\Analytics facade.
For example:
<?php
use Spatie\Analytics\Facades\Analytics;
test('feature in your project', function () {
// Arrange
Analytics::fake();
// Act
$response = $this->actingAs($admin)->get('/analytics');
// Assert
$response->assertStatus(200);
});
You can also specify the expected result either as an array or Illuminate\Support\Collection to be returned when a method is called on the facade.
For example:
<?php
use Spatie\Analytics\Facades\Analytics;
test('feature in your project', function () {
// Arrange
Analytics::fake([
[
'pageTitle' => 'Test Page',
'activeUsers' => 10,
'screenPageViews' => 20,
],
]);
// Act
$response = $this->actingAs($admin)->get('/analytics');
// Assert
$response->assertStatus(200);
});
Package tests
Run the tests with:
vendor/bin/pest
Changelog
Please see CHANGELOG for more information what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security
If you've found a bug regarding security please mail [email protected] instead of using the issue tracker.
Credits
- Freek Van der Herten
- All Contributors
Special thanks to Caneco for the original logo.
License
The MIT License (MIT). Please see License File for more information.
