zhongwei/gh-henkisdabro-wookstar-claude-code-plugins-gtm-suite

Fork 0

Files

Zhongwei Li c02dafae1d Initial commit

2025-11-29 18:32:45 +08:00

12 KiB

Raw Permalink Blame History

GTM API Overview

Sources:

Last Updated: 2025-01-09

Overview

The Google Tag Manager API provides programmatic access to Google Tag Manager configuration data for authorized users. With this API, you can automate common tag management tasks, including creating containers, managing tags, triggers, variables, and publishing container versions.

Why Use the GTM API

Benefits:

Automation: Automate repetitive tasks like creating similar tags across containers
Scalability: Manage multiple containers programmatically
Integration: Integrate GTM with your existing workflows and tools
Version Control: Implement custom version control and deployment workflows
Bulk Operations: Create, update, or delete resources in bulk

Common Use Cases:

Deploying standard tag configurations across multiple containers
Implementing custom approval workflows
Syncing GTM configurations with external systems
Creating automated testing for tag configurations
Building custom GTM management interfaces

API Capabilities

The GTM API allows you to manage:

Accounts: Access and list GTM accounts
Containers: Create, read, update containers
Workspaces: Manage draft configurations
Tags: Create and configure tags programmatically
Triggers: Set up firing conditions
Variables: Define data sources
Folders: Organize container elements
Built-in Variables: Enable/disable built-in variables
Versions: Create, publish, and manage versions
Environments: Configure staging environments
User Permissions: Manage account and container access

Authentication

The GTM API uses OAuth 2.0 for authentication and authorization.

OAuth 2.0 Scopes

Choose the appropriate scope based on your needs:

https://www.googleapis.com/auth/tagmanager.readonly
Read-only access to all GTM data

https://www.googleapis.com/auth/tagmanager.edit.containers
Edit access to container configurations

https://www.googleapis.com/auth/tagmanager.delete.containers
Permission to delete containers

https://www.googleapis.com/auth/tagmanager.edit.containerversions
Create and modify container versions

https://www.googleapis.com/auth/tagmanager.publish
Publish container versions

https://www.googleapis.com/auth/tagmanager.manage.users
Manage user permissions

https://www.googleapis.com/auth/tagmanager.manage.accounts
Full account access

Setup Steps

Create a Project in Google Cloud Console
Enable the GTM API for your project
Create OAuth 2.0 Credentials:
- For web apps: OAuth 2.0 Client ID
- For server apps: Service Account
Download credentials JSON file
Implement OAuth flow in your application

Python Example

from google.oauth2.credentials import Credentials
from googleapiclient.discovery import build

# Define scopes
scopes = ['https://www.googleapis.com/auth/tagmanager.edit.containers']

# Create service
service = build('tagmanager', 'v2', credentials=credentials)

JavaScript Example

const CLIENT_ID = 'YOUR_CLIENT_ID';
const SCOPES = [
  'https://www.googleapis.com/auth/tagmanager.edit.containers'
];

gapi.client.load('tagmanager', 'v2', () => {
  // API loaded
});

API Resources and Hierarchy

GTM API follows a hierarchical structure:

Account (accounts/123456)
  └─ Container (accounts/123456/containers/7890)
      └─ Workspace (accounts/123456/containers/7890/workspaces/1)
          ├─ Tags
          ├─ Triggers
          ├─ Variables
          └─ Folders
      └─ Versions
      └─ Environments

Common Operations

List Containers

# Python
account_path = 'accounts/123456'
containers = service.accounts().containers().list(
    parent=account_path
).execute()

for container in containers.get('container', []):
    print(f"Container: {container['name']} ({container['containerId']})")

// JavaScript
const request = gapi.client.tagmanager.accounts.containers.list({
  parent: 'accounts/123456'
});

request.execute((response) => {
  response.container.forEach((container) => {
    console.log(`Container: ${container.name} (${container.containerId})`);
  });
});

Create a Workspace

# Python
container_path = 'accounts/123456/containers/7890'
workspace = service.accounts().containers().workspaces().create(
    parent=container_path,
    body={'name': 'API Workspace', 'description': 'Created via API'}
).execute()

Create a Tag

# Python
workspace_path = 'accounts/123456/containers/7890/workspaces/1'

ga4_tag = {
    'name': 'GA4 Config Tag',
    'type': 'gaawe',  # GA4 Configuration tag type
    'parameter': [
        {'key': 'measurementId', 'type': 'template', 'value': 'G-XXXXXXXXXX'}
    ]
}

tag = service.accounts().containers().workspaces().tags().create(
    parent=workspace_path,
    body=ga4_tag
).execute()

Create a Trigger

# Python
pageview_trigger = {
    'name': 'All Pages',
    'type': 'PAGEVIEW'
}

trigger = service.accounts().containers().workspaces().triggers().create(
    parent=workspace_path,
    body=pageview_trigger
).execute()

Link Tag to Trigger

# Python
tag_path = 'accounts/123456/containers/7890/workspaces/1/tags/5'

# Get existing tag
tag = service.accounts().containers().workspaces().tags().get(
    path=tag_path
).execute()

# Add trigger ID
tag['firingTriggerId'] = [trigger['triggerId']]

# Update tag
updated_tag = service.accounts().containers().workspaces().tags().update(
    path=tag_path,
    body=tag
).execute()

Create and Publish Version

# Python
workspace_path = 'accounts/123456/containers/7890/workspaces/1'

# Create version
version = service.accounts().containers().workspaces().create_version(
    path=workspace_path,
    body={'name': 'Version 1', 'notes': 'Initial setup'}
).execute()

# Publish version
published = service.accounts().containers().versions().publish(
    path=version['containerVersion']['path']
).execute()

API Patterns

Pagination

Some list operations return paginated results:

# Python
def list_all_tags(service, workspace_path):
    tags = []
    page_token = None

    while True:
        response = service.accounts().containers().workspaces().tags().list(
            parent=workspace_path,
            pageToken=page_token
        ).execute()

        tags.extend(response.get('tag', []))
        page_token = response.get('nextPageToken')

        if not page_token:
            break

    return tags

Error Handling

# Python
from googleapiclient.errors import HttpError

try:
    tag = service.accounts().containers().workspaces().tags().create(
        parent=workspace_path,
        body=tag_data
    ).execute()
except HttpError as error:
    if error.resp.status == 409:
        print("Tag already exists")
    elif error.resp.status == 403:
        print("Permission denied")
    else:
        print(f"An error occurred: {error}")

Rate Limiting

The API has the following quotas (default):

Queries per day: 1,000 (can be increased)
Queries per 100 seconds: 100

Implement retry logic with exponential backoff:

# Python
import time
from googleapiclient.errors import HttpError

def api_call_with_retry(func, max_retries=5):
    for attempt in range(max_retries):
        try:
            return func()
        except HttpError as error:
            if error.resp.status == 429:  # Rate limit exceeded
                wait_time = 2 ** attempt  # Exponential backoff
                time.sleep(wait_time)
            else:
                raise

    raise Exception("Max retries exceeded")

Resource Paths

All API operations use resource paths:

Account:    accounts/{account_id}
Container:  accounts/{account_id}/containers/{container_id}
Workspace:  accounts/{account_id}/containers/{container_id}/workspaces/{workspace_id}
Tag:        accounts/{account_id}/containers/{container_id}/workspaces/{workspace_id}/tags/{tag_id}

Use paths from API responses rather than constructing them manually when possible.

Best Practices

1. Use Workspaces

Always work within a workspace:

Create a new workspace for API changes
Make changes in the workspace
Create and publish a version when ready
Don't modify the default workspace

2. Test Before Production

# Create test workspace
test_workspace = service.accounts().containers().workspaces().create(
    parent=container_path,
    body={'name': 'API Test', 'description': 'Testing API changes'}
).execute()

# Make changes
# Test thoroughly
# Create version if satisfied
# Delete workspace if not needed

3. Version Everything

Always create versions with meaningful notes:

version = service.accounts().containers().workspaces().create_version(
    path=workspace_path,
    body={
        'name': 'Release 2.3.0',
        'notes': 'Added GA4 ecommerce tracking\n- Purchase event\n- Product views\n- Add to cart'
    }
).execute()

4. Handle Permissions

Check user permissions before operations:

try:
    containers = service.accounts().containers().list(
        parent='accounts/123456'
    ).execute()
except HttpError as error:
    if error.resp.status == 403:
        print("User lacks permission to access this account")

5. Use Batch Requests

For multiple operations, use batch requests:

from googleapiclient.http import BatchHttpRequest

def callback(request_id, response, exception):
    if exception:
        print(f"Error: {exception}")
    else:
        print(f"Created: {response['name']}")

batch = service.new_batch_http_request(callback=callback)

for tag_data in tags_to_create:
    batch.add(service.accounts().containers().workspaces().tags().create(
        parent=workspace_path,
        body=tag_data
    ))

batch.execute()

Example: Complete Workflow

# 1. List accounts
accounts = service.accounts().list().execute()
account_path = accounts['account'][0]['path']

# 2. Find container
containers = service.accounts().containers().list(parent=account_path).execute()
container = next(c for c in containers['container'] if c['name'] == 'My Site')
container_path = container['path']

# 3. Create workspace
workspace = service.accounts().containers().workspaces().create(
    parent=container_path,
    body={'name': 'API Changes', 'description': 'Automated setup'}
).execute()
workspace_path = workspace['path']

# 4. Create trigger
trigger = service.accounts().containers().workspaces().triggers().create(
    parent=workspace_path,
    body={'name': 'All Pages', 'type': 'PAGEVIEW'}
).execute()

# 5. Create tag
tag = service.accounts().containers().workspaces().tags().create(
    parent=workspace_path,
    body={
        'name': 'GA4 Config',
        'type': 'gaawe',
        'parameter': [{'key': 'measurementId', 'type': 'template', 'value': 'G-XXXXXX'}],
        'firingTriggerId': [trigger['triggerId']]
    }
).execute()

# 6. Create and publish version
version = service.accounts().containers().workspaces().create_version(
    path=workspace_path,
    body={'name': 'API Setup', 'notes': 'Automated GA4 configuration'}
).execute()

published = service.accounts().containers().versions().publish(
    path=version['containerVersion']['path']
).execute()

print(f"Published version: {published['containerVersion']['containerVersionId']}")

Limitations

No direct data layer access: API manages configuration, not runtime data
No real-time testing: Use Preview mode in GTM UI for testing
Version publishing is final: Cannot unpublish, only publish new versions
Rate limits apply: Be mindful of quota limits
Some features unavailable: Certain GTM features may not be available via API

12 KiB Raw Permalink Blame History