Getting Started

Minimal Steps

Installation Clone the submodule into your project:

git submodule add git@github.com:drymek/GoogleBundle.git src/AntiMattr/GoogleBundle

protected $bundles = [
    // ...
    new AntiMattr\GoogleBundle\GoogleBundle(),
];

Basic Configuration Add Google Analytics to config/packages/google.yaml (or config.yml):

google:
    analytics:
        trackers:
            default:
                name:      "gaTracker"
                accountId: "UA-xxxx-x"
                domain:    ".yourdomain.com"
                trackPageLoadTime: true

First Use Case Include the async tracker in your Twig layout (e.g., base.html.twig):
```
{% block head %}
    {{ parent() }}
    {% include "GoogleBundle::Analytics:async.html.twig" %}
{% endblock %}
```
Verify the script loads in the browser’s <head> or before </body>.

Implementation Patterns

Core Workflows

Service Injection Access the analytics service via dependency injection:

use AntiMattr\GoogleBundle\Analytics\AnalyticsService;

public function __construct(AnalyticsService $analytics) {
    $this->analytics = $analytics;
}

Use it to log custom page views:

$this->analytics->setCustomPageView('/custom-path');

Dynamic Tracker Configuration Define multiple trackers in config/google.yaml:

google:
    analytics:
        trackers:
            default: { accountId: "UA-123-1" }
            secondary: { accountId: "UA-456-2", domain: ".subdomain.com" }

Reference them in Twig:

{% include "GoogleBundle::Analytics:async.html.twig" with {'tracker': 'secondary'} %}

Event-Based Tracking Trigger events (e.g., e-commerce) via the service:
```
$this->analytics->trackEvent('Category', 'Action', 'Label', 1.00);
```

JavaScript Maps Integration Leverage the fork’s JS Maps support by including the provided Twig template:

{% include "GoogleBundle::Maps:init.html.twig" %}

Configure maps in config/google.yaml:

google:
    maps:
        api_key: "YOUR_API_KEY"
        libraries: ["places", "drawing"]

Integration Tips

Symfony 5+ Compatibility: Use config/packages/google.yaml for modern Symfony apps.
Environment-Specific Config: Override settings per environment (e.g., config/google/dev.yaml).
Asset Management: Ensure Google’s JS/CSS assets are loaded via Symfony’s asset pipeline (e.g., Webpack Encore).

Gotchas and Tips

Pitfalls

Submodule Updates
- Manually update the submodule:
```
cd src/AntiMattr/GoogleBundle && git pull origin main
```
- Avoid composer require; this bundle isn’t Composer-friendly.
Twig Template Paths
- Use double colons (::) for Twig paths (e.g., "GoogleBundle::Analytics:async.html.twig").
- Ensure the GoogleBundle is registered before Twig templates are rendered.
Domain Mismatches
- The domain config must match your site’s domain (e.g., .example.com for example.com and sub.example.com).
- Test with Google’s Tag Assistant to validate tracking.
Async Loading Conflicts
- If _gaq fails to load, ensure no other analytics scripts (e.g., GA4) are included.
- Place the async template before </body> for optimal performance.

Debugging

Check Console for Errors: Look for GoogleBundle logs in var/log/dev.log.
Verify API Keys: Ensure api_key in config/google.yaml is correct for Maps services.
Network Tab: Confirm Google’s JS/CSS loads without 404s (e.g., https://maps.googleapis.com/...).

Extension Points

Custom Trackers Extend the AnalyticsService to add methods for your use case:

// src/Service/CustomAnalytics.php
class CustomAnalytics extends AnalyticsService {
    public function trackCustomEvent(string $event) {
        $this->queue[] = ['_trackEvent', [$event]];
    }
}

Bind it in services.yaml:

services:
    App\Service\CustomAnalytics: '@google.analytics'

Override Twig Templates Copy templates from src/AntiMattr/GoogleBundle/Resources/views/ to templates/bundles/google/ to customize them.

Add New Services Fork the bundle and extend GoogleBundle to support additional Google services (e.g., Firebase):

// src/AntiMattr/GoogleBundle/GoogleBundle.php
public function build(ContainerBuilder $container) {
    parent::build($container);
    $container->loadFromExtension('google', [
        'firebase' => ['api_key' => '%env(GOOGLE_FIREBASE_KEY)%']
    ]);
}

Google Bundle Laravel Package