# Google Ads API V23 Upgrade Notes

## Scope

This upgrade migrates Google Ads integration from `v19` to `v23` to remove the sunset endpoint issue (`UNIMPLEMENTED` / "GRPC target method can't be resolved").

## Final Version Decision

- **Google Ads API target:** `v23` (preferred modern target).
- **Client library:** `googleads/google-ads-php` upgraded to `v32.3.0`.
- **composer constraint:** `^32.2.0`.

## Code Changes Applied

- Dependency upgrade:
  - `composer.json`
  - `composer.lock`
- Google Ads namespace migration `V19 -> V23`:
  - `app/Services/Google/GoogleAdsService.php`
  - `app/Services/Google/GoogleAdsServiceTrait.php`
  - `app/Http/Controllers/GoogleAdsController.php`
- Config update:
  - `google_ads_php.ini` -> `version = v23`
- Test/help text updates:
  - `app/Console/Commands/TestGoogleAdsKeyword.php`
  - `test_usage_guide.php`
  - `test_job_workflow.php`

## Local Validation Executed

1. `php artisan package:discover --ansi` -> success.
2. `php artisan googleads:test-keyword "cuchara"` -> request now hits `v23` endpoint family (no `UNIMPLEMENTED`).

Observed response now is an **auth/project binding** error:

- `PERMISSION_DENIED`
- `authorizationError: DEVELOPER_TOKEN_PROHIBITED`
- `Developer token is not allowed with project '454126386927'.`

This confirms the endpoint version issue is solved locally and the remaining blocker is credential/project authorization.

## Pipeline Validation Status (Job -> Google Ads -> BigQuery)

- Laravel service wiring loads correctly after migration.
- Syntax validation passed for core pipeline files.
- Full end-to-end insert validation is blocked by the current Google Ads authorization error above.
- BigQuery write paths and table targets remain unchanged in code.

## Deployment / Monitoring Runbook

Run on target environment after merge:

1. `php artisan config:clear`
2. `php artisan cache:clear`
3. `php artisan queue:restart`
4. Optional: restart Horizon/supervisor workers if used
5. Execute smoke command:
   - `php artisan googleads:test-keyword "cuchara"`
6. Monitor logs for:
   - absence of `UNIMPLEMENTED` / `GRPC target method can't be resolved`
   - Google Ads auth errors (`DEVELOPER_TOKEN_PROHIBITED`, `DEVELOPER_TOKEN_NOT_APPROVED`)
   - BigQuery insertion failures

## Next Action Required Outside Code

- Ensure the OAuth client/project used to generate the refresh token is explicitly authorized for the active developer token in Google Ads API Center.
- Keep developer token on **Basic/Standard** access for Keyword Plan endpoints.