zhongwei/gh-henkisdabro-wookstar-claude-code-plugins-gtm-suite
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:32:45 +08:00
commit c02dafae1d
41 changed files with 17283 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

470
skills/gtm-api/references/api-overview.md Normal file
View File

@@ -0,0 +1,470 @@
# GTM API Overview
**Sources**:
- https://developers.google.com/tag-platform/tag-manager/api/v2
- https://developers.google.com/tag-platform/tag-manager/api/v2/devguide
**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
1. **Create a Project** in Google Cloud Console
2. **Enable the GTM API** for your project
3. **Create OAuth 2.0 Credentials**:
- For web apps: OAuth 2.0 Client ID
- For server apps: Service Account
4. **Download credentials** JSON file
5. **Implement OAuth flow** in your application
### Python Example
```python
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
```javascript
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
# 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
// 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
# 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
# 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
# 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
# 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
# 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
# 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
# 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
# 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
```python
# 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:
```python
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:
```python
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:
```python
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
```python
# 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
## Resources
- [GTM API Reference](https://developers.google.com/tag-platform/tag-manager/api/v2/reference)
- [GTM API Developer Guide](https://developers.google.com/tag-platform/tag-manager/api/v2/devguide)
- [OAuth 2.0 Documentation](https://developers.google.com/identity/protocols/oauth2)
- [Python Client Library](https://github.com/googleapis/google-api-python-client)
- [JavaScript Client Library](https://github.com/google/google-api-javascript-client)
- [Tag Dictionary Reference](https://developers.google.com/tag-platform/tag-manager/api/v2/tag-dictionary-reference)
- [Variable Dictionary Reference](https://developers.google.com/tag-platform/tag-manager/api/v2/variable-dictionary-reference)