Google Base Package

This page covers only the parts of the base artisanpack-ui/google setup that matter for the Tag Manager integration. The base package's own docs are the source of truth for OAuth details.

Why it's required

The base package owns:

• OAuth2 authorization-code + PKCE flow
• Encrypted access and refresh token storage on the google_connections table
• The scope registry that pools scopes from every installed Google service package
• Transparent token refresh via TokenManager

Every server-side call this package makes to the Tag Manager API is authenticated by a token the base package hands out. Without the base package configured, TagManagerClient throws BaseNotInstalledException and the routes return 501.

What to do

1. Install the base package — done automatically by this package's Composer dependency.

2. Publish migrations and migrate:

   php artisan vendor:publish --tag=google-migrations
   php artisan migrate
   

3. Enable the Tag Manager API on your Google Cloud project. Under APIs & Services → Library, find "Tag Manager API" and click Enable. Without this, every API call returns 403 regardless of the scope.

4. Add the scope on the OAuth consent screen. Add https://www.googleapis.com/auth/tagmanager.readonly under APIs & Services → OAuth consent screen → Scopes. The package contributes this scope to the base package's scope registry automatically, but Google's consent screen must also know about it or the user will see a "scope not authorized" error.

5. Register your OAuth client via your chosen credential driver on the base package (config, database, or cms).

6. Connect a user through the base package's connect flow. The consent screen will include Tag Manager read-only access alongside every other Google service scope the app requests.

Verifying

From tinker:

$user = \App\Models\User::find( 1 );
$connection = $user->googleConnection;

// The scope should be present:
in_array( 'https://www.googleapis.com/auth/tagmanager.readonly', $connection->granted_scopes ?? [], true );

// The client should be able to list accounts:
$client = app( \ArtisanPackUI\GoogleTagManager\Api\TagManagerClient::class );
$accounts = $client->listAccounts( $connection );

If listAccounts throws:

• BaseNotInstalledException — base package isn't fully installed. Check composer show artisanpack-ui/google.
• ApiException with apiError() === 401 — token is invalid. Ask the user to reconnect via the base package.
• ApiException with apiError() === 403 — the Tag Manager API isn't enabled on your Cloud project, or the connected user doesn't have access to any GTM containers.