Analytics Data Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require google/analytics-data

Ensure your project uses PHP 8.0+ (recommended: 8.1+).

2. Authentication: Use Google’s authentication guide to set up credentials (e.g., service account JSON key). Store the path securely (e.g., Laravel .env):

   GOOGLE_APPLICATION_CREDENTIALS=/path/to/your/service-account.json
   

3. First Use Case: Fetch basic metrics for a GA4 property (replace properties/{PROPERTY_ID}):

   use Google\Analytics\Data\V1beta\BetaAnalyticsDataClient;
   use Google\Analytics\Data\V1beta\RunReportRequest;
   use Google\Analytics\Data\V1beta\Dimension;
   use Google\Analytics\Data\V1beta\Metric;
   
   $client = new BetaAnalyticsDataClient();
   $request = (new RunReportRequest())
       ->setProperty('properties/12345678')
       ->setDimensions([new Dimension()->setName('country')])
       ->setMetrics([new Metric()->setName('activeUsers')]);
   
   $response = $client->runReport($request);
   

Key Entry Points

• Client Classes:
  • BetaAnalyticsDataClient (v1beta, recommended for new projects)
  • AlphaAnalyticsDataClient (v1alpha, legacy—avoid unless maintaining old code)
• Core Methods:
  • runReport(): Standard reporting.
  • runPivotReport(): Pivot tables.
  • runAsyncQuery(): Background processing.
• Deprecated/Removed:
  • SheetExportAudienceList (removed in v1alpha) is no longer available in v1beta.

Implementation Patterns

Common Workflows

1. Reporting with Filters

Use FilterExpression for granular data extraction:

use Google\Analytics\Data\V1beta\FilterExpression;
use Google\Analytics\Data\V1beta\SimpleComparisonFilter;

$filter = (new FilterExpression())
    ->setFilters([
        (new SimpleComparisonFilter())
            ->setDimensionName('country')
            ->setOperator('EQUALS')
            ->setValue('United States')
    ]);

$request->setFilter($filter);

2. Date Ranges

Define time spans with DateRange:

use Google\Analytics\Data\V1beta\DateRange;

$request->setDateRanges([
    (new DateRange())
        ->setStartDate('7daysAgo')
        ->setEndDate('today')
]);

3. Async Processing

Offload heavy queries to Google’s servers:

$asyncRequest = (new RunAsyncQueryRequest())
    ->setProperty('properties/12345678')
    ->setQuery('SELECT * FROM events WHERE event_name = "purchase"');

$task = $client->runAsyncQuery($asyncRequest);
$result = $client->getReportTask($task->getName());

4. Laravel Integration

Service Provider:

// app/Providers/AnalyticsServiceProvider.php
public function register()
{
    $this->app->singleton(BetaAnalyticsDataClient::class, function ($app) {
        return new BetaAnalyticsDataClient();
    });
}

Facade (Optional):

// app/Facades/Analytics.php
public static function runReport(array $params)
{
    return app(BetaAnalyticsDataClient::class)->runReport($params);
}

Usage in Controllers:

use App\Facades\Analytics;

$data = Analytics::runReport([
    'property' => 'properties/12345678',
    'dimensions' => ['country'],
    'metrics' => ['activeUsers'],
]);

5. Error Handling

Wrap API calls in try-catch blocks:

try {
    $response = $client->runReport($request);
} catch (ApiException $e) {
    Log::error('Analytics API Error: ' . $e->getMessage());
    return response()->json(['error' => 'Failed to fetch data'], 500);
}

Advanced Patterns

Pagination

Use nextPageToken for large datasets:

$response = $client->runReport($request);
$nextPageToken = $response->getNextPageToken();

while ($nextPageToken) {
    $request->setPageToken($nextPageToken);
    $response = $client->runReport($request);
    $nextPageToken = $response->getNextPageToken();
}

Sampling Control

Explicitly set sampling levels:

$request->setSamplingLevel('HIGH_PRECISION');

Custom Dimensions/Metrics

Reference custom definitions by name:

$request->setDimensions([new Dimension()->setName('customEvent:custom_dimension')]);

Gotchas and Tips

Pitfalls

1. Authentication Issues:

   • Error: Invalid credentials or 403 Forbidden.
   • Fix: Ensure GOOGLE_APPLICATION_CREDENTIALS points to a valid JSON key with analytics.readonly (or .data) scope. Verify the service account has access to the GA4 property.

2. Deprecated Methods:

   • Avoid AlphaAnalyticsDataClient (v1alpha). Use BetaAnalyticsDataClient (v1beta) for new projects.
   • Removed in v1alpha: SheetExportAudienceList is no longer available in any version. Ensure your code doesn’t rely on this deprecated feature.

3. Quota Limits:

   • Free tier has strict quotas. Monitor quotaStatus in responses:

     $quota = $response->getMetadata()->getQuotaStatus();
     if ($quota->getConsumed() >= $quota->getLimit()) {
         // Handle quota exhaustion
     }
     

4. Date Range Formatting:

   • Use ISO 8601 (YYYY-MM-DD) or relative terms (7daysAgo, today). Invalid formats return empty results.

5. Async Task Timeouts:

   • GetReportTask may take minutes to hours. Implement exponential backoff:

     $retryDelay = 1000; // ms
     while (!$result->getCompleted()) {
         sleep($retryDelay / 1000);
         $retryDelay *= 2;
         $result = $client->getReportTask($task->getName());
     }
     

Debugging Tips

1. Enable gRPC Logging: Set environment variable to debug gRPC calls:

   GRPC_VERBOSITY=DEBUG
   

2. Validate Requests: Use serializeToJsonString() to inspect request payloads:

   $requestJson = $request->serializeToJsonString();
   Log::debug('Analytics Request:', ['payload' => $requestJson]);
   

3. Common Errors:

   • INVALID_ARGUMENT: Check dimension/metric names (case-sensitive, e.g., country vs Country).
   • RESOURCE_EXHAUSTED: Reduce date range or sampling level.
   • UNAVAILABLE: Retry with exponential backoff (Google’s backend issues).

Extension Points

1. Custom Response Mappers: Transform raw responses into Laravel collections:

   $rows = collect($response->getRows())
       ->map(function ($row) {
           return [
               'dimension' => $row->getDimensionValues()[0]->getValue(),
               'metric' => $row->getMetricValues()[0]->getValue(),
           ];
       });
   

2. Caching Layer: Cache frequent reports (e.g., daily metrics) using Laravel’s cache:

   $cacheKey = 'analytics_report_' . md5($request->serializeToJsonString());
   return Cache::remember($cacheKey, now()->addHours(1), function () use ($client, $request) {
       return $client->runReport($request);
   });
   

3. Webhook Integration: Use AudienceExport for real-time data pushes (if applicable to your use case):

   $export = (new CreateAudienceExportRequest())
       ->setName('properties/12345678/audienceExports/export1')
       ->setDestination('bigquery://project/dataset/table')
       ->setAudienceSegment('segments/123');
   
   $client->createAudienceExport($export);
   

4. Testing: Use mock