gtm-setup

GTM 设置 - 技术前置条件

自动完成整个 GTM API 设置流程，从安装依赖项到验证 API 访问权限。

工作流

阶段 1：前置条件检查

步骤 1.1：检查 Node.js 项目

Verify package.json exists:
- If missing → Error: "This must be run in a Node.js project"
- If exists → Continue

步骤 1.2：检查是否已有设置

Check for existing files:
- gtm-credentials.json → Already configured
- gtm-token.json → Already authorized
- gtm-config.json → Configuration exists

If all exist:
  → "GTM API already configured. Run validation to test connection."
  → Skip to Phase 6 (Validation)

If partial:
  → "Partial setup detected. Continuing from [step]..."

阶段 2：安装 googleapis

步骤 2.1：自动安装软件包

Run: npm install googleapis --save

Monitor output for:
✓ Success → Continue
✗ Error → Display error, suggest manual installation

步骤 2.2：验证安装

Check package.json dependencies:
- "googleapis": "^..." present → Success
- Missing → Retry or manual install

阶段 3：Google Cloud 项目设置

步骤 3.1：指导访问 Cloud Console

Present clickable URLs:

Step 1: Create/Select Google Cloud Project
→ https://console.cloud.google.com/projectcreate

Step 2: Enable Google Tag Manager API
→ https://console.cloud.google.com/apis/library/tagmanager.googleapis.com

Step 3: Create OAuth 2.0 Credentials
→ https://console.cloud.google.com/apis/credentials

Wait for user confirmation at each step.

步骤 3.2：配置 OAuth 凭据

Guide user through credential creation:

1. Click "Create Credentials" → "OAuth client ID"
2. Application type: "Desktop app"
3. Name: "GTM Automation Script"
4. Click "Create"
5. Download JSON file

Prompt: "Download the credentials JSON file and save it in your project root."

步骤 3.3：保存凭据

Ask user for downloaded file path:
→ "Where did you save the credentials file?"

Options:
a) File is in project root → Look for oauth2.keys.json or similar
b) User provides path → Copy to gtm-credentials.json
c) User pastes content → Write to gtm-credentials.json

Validate JSON structure:
- Has "installed" or "web" key
- Has "client_id", "client_secret", "redirect_uris"

If invalid → Error with specific issue
If valid → Save as gtm-credentials.json

阶段 4：GTM 账号和容器配置

步骤 4.1：收集 GTM 信息

Guide user to find GTM details:

"Open Google Tag Manager: https://tagmanager.google.com"

Q1: What is your GTM Account ID?
→ Hint: In GTM, go to Admin. Account ID is shown at top (format: 1234567890)

Q2: What is your GTM Container ID?
→ Hint: In GTM, select container. Container ID shown at top (format: GTM-XXXXXX)

Validate inputs:
- Account ID: Must be numeric
- Container ID: Must start with "GTM-"

步骤 4.2：创建配置文件

Generate gtm-config.json:

{
  "accountId": "[user input]",
  "containerId": "[user input]",
  "containerPublicId": "[user input]"
}

Save to project root.

注意：workspaceId 不会存储在 gtm-config.json 中。gtm-implementation 技能始终通过 GTM API 动态解析当前活动工作区。这样可以避免在 GTM UI 中发布版本后出错，因为发布操作会删除并重新创建工作区。

阶段 5：OAuth 授权

步骤 5.1：生成授权 URL

Using googleapis library, generate OAuth consent URL.

Present to user:
"
=== Authorization Required ===

Open this URL in your browser to authorize access:

[Long Google OAuth URL]

This will:
1. Ask you to sign in to Google
2. Show permissions requested (Read/Write GTM access)
3. Redirect to a localhost URL with an authorization code

After authorizing, you'll see a page that says:
'The authentication flow has completed. You may close this window.'

Copy the FULL URL from your browser address bar.
"

步骤 5.2：用授权码换取令牌

Prompt: "Paste the full redirect URL here:"

Extract authorization code from URL:
- URL format: http://localhost/?code=XXXX&scope=...
- Parse 'code' parameter

Exchange code for access/refresh tokens using OAuth2 client.

Save tokens to gtm-token.json:
{
  "access_token": "...",
  "refresh_token": "...",
  "scope": "...",
  "token_type": "Bearer",
  "expiry_date": 1234567890
}

Success message:
"✓ Authorization complete! Tokens saved to gtm-token.json"

阶段 6：验证与测试

步骤 6.1：测试 API 连接

Using saved credentials and token, make test API call:

GET /tagmanager/v2/accounts/{accountId}/containers/{containerId}

Expected responses:
✓ 200 OK → Success! Container details returned
✗ 401 Unauthorized → Token invalid, re-authorize
✗ 403 Forbidden → Missing permissions, check API enable
✗ 404 Not Found → Wrong account/container ID
✗ Other → Display error details

步骤 6.2：验证权限

Check API response for required permissions:

Required GTM API scopes:
- tagmanager.edit.containers
- tagmanager.readonly

If missing scopes:
→ Error: "Insufficient permissions. Re-authorize with correct scopes."
→ Restart Phase 5

步骤 6.3：最终确认

Display success summary:

"
=== GTM API Setup Complete ===

✓ googleapis installed
✓ OAuth credentials configured (gtm-credentials.json)
✓ Access token obtained (gtm-token.json)
✓ GTM configuration saved (gtm-config.json)
✓ API connection validated

Account: [accountId]
Container: [containerPublicId]

Files created:
- gtm-credentials.json (OAuth credentials)
- gtm-token.json (Access token - DO NOT commit to git)
- gtm-config.json (GTM account/container info)

Next steps:
→ Add gtm-token.json to .gitignore
→ Invoke gtm-implementation skill to implement tracking

Ready to implement tracking? Invoke gtm-implementation skill.
"

脚本

自动执行以下步骤时，请使用这些脚本：

scripts/install-googleapis.js

// Auto-install googleapis package
const { execSync } = require('child_process');

try {
  console.log('Installing googleapis...');
  execSync('npm install googleapis --save', { stdio: 'inherit' });
  console.log('✓ googleapis installed successfully');
} catch (error) {
  console.error('✗ Installation failed:', error.message);
  process.exit(1);
}

scripts/validate-prerequisites.js

// Validate existing setup files
const fs = require('fs');
const path = require('path');

const files = {
  'package.json': { required: true, description: 'Node.js project' },
  'gtm-credentials.json': { required: false, description: 'OAuth credentials' },
  'gtm-token.json': { required: false, description: 'Access token' },
  'gtm-config.json': { required: false, description: 'GTM configuration' }
};

console.log('Validating prerequisites...\n');

let allValid = true;
let setupStatus = {
  credentials: false,
  token: false,
  config: false
};

for (const [filename, config] of Object.entries(files)) {
  const exists = fs.existsSync(path.join(process.cwd(), filename));

  if (filename === 'gtm-credentials.json' && exists) setupStatus.credentials = true;
  if (filename === 'gtm-token.json' && exists) setupStatus.token = true;
  if (filename === 'gtm-config.json' && exists) setupStatus.config = true;

  const status = exists ? '✓' : (config.required ? '✗' : '○');
  console.log(`${status} ${filename} - ${config.description}`);

  if (config.required && !exists) {
    allValid = false;
  }
}

console.log('\nSetup status:');
if (setupStatus.credentials && setupStatus.token && setupStatus.config) {
  console.log('✓ Complete setup detected');
  console.log('→ Run test-connection.js to validate');
} else if (setupStatus.credentials || setupStatus.token || setupStatus.config) {
  console.log('○ Partial setup detected');
  if (!setupStatus.credentials) console.log('  Missing: OAuth credentials');
  if (!setupStatus.token) console.log('  Missing: Access token');
  if (!setupStatus.config) console.log('  Missing: GTM configuration');
} else {
  console.log('○ No setup detected');
  console.log('→ Start from Phase 3 (Google Cloud setup)');
}

process.exit(allValid ? 0 : 1);

scripts/oauth-authorize.js

// OAuth authorization flow
const { google } = require('googleapis');
const fs = require('fs');
const path = require('path');
const readline = require('readline');

const SCOPES = ['https://www.googleapis.com/auth/tagmanager.edit.containers'];
const TOKEN_PATH = path.join(process.cwd(), 'gtm-token.json');
const CREDENTIALS_PATH = path.join(process.cwd(), 'gtm-credentials.json');

// Load credentials
const credentials = JSON.parse(fs.readFileSync(CREDENTIALS_PATH, 'utf8'));
const { client_secret, client_id, redirect_uris } = credentials.installed || credentials.web;

const oAuth2Client = new google.auth.OAuth2(client_id, client_secret, redirect_uris[0]);

// Generate auth URL
const authUrl = oAuth2Client.generateAuthUrl({
  access_type: 'offline',
  scope: SCOPES,
});

console.log('\n=== GTM API Authorization ===\n');
console.log('Open this URL in your browser to authorize:\n');
console.log(authUrl);
console.log('\nAfter authorization, copy the full redirect URL from your browser.\n');

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
});

rl.question('Paste the redirect URL here: ', (redirectUrl) => {
  rl.close();

  // Extract code from URL
  const url = new URL(redirectUrl);
  const code = url.searchParams.get('code');

  if (!code) {
    console.error('✗ No authorization code found in URL');
    process.exit(1);
  }

  // Exchange code for token
  oAuth2Client.getToken(code, (err, token) => {
    if (err) {
      console.error('✗ Error retrieving access token:', err);
      process.exit(1);
    }

    // Save token
    fs.writeFileSync(TOKEN_PATH, JSON.stringify(token, null, 2));
    console.log('\n✓ Token saved to', TOKEN_PATH);
    console.log('\n=== Authorization Complete ===\n');
    console.log('You can now use the GTM API.');
    console.log('\nIMPORTANT: Add gtm-token.json to .gitignore\n');
  });
});

scripts/test-connection.js

// Test GTM API connection
const { google } = require('googleapis');
const fs = require('fs');
const path = require('path');

const TOKEN_PATH = path.join(process.cwd(), 'gtm-token.json');
const CREDENTIALS_PATH = path.join(process.cwd(), 'gtm-credentials.json');
const CONFIG_PATH = path.join(process.cwd(), 'gtm-config.json');

// Check files exist
if (!fs.existsSync(CREDENTIALS_PATH)) {
  console.error('✗ gtm-credentials.json not found');
  process.exit(1);
}

if (!fs.existsSync(TOKEN_PATH)) {
  console.error('✗ gtm-token.json not found. Run oauth-authorize.js first.');
  process.exit(1);
}

if (!fs.existsSync(CONFIG_PATH)) {
  console.error('✗ gtm-config.json not found');
  process.exit(1);
}

// Load files
const credentials = JSON.parse(fs.readFileSync(CREDENTIALS_PATH, 'utf8'));
const token = JSON.parse(fs.readFileSync(TOKEN_PATH, 'utf8'));
const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));

const { client_secret, client_id, redirect_uris } = credentials.installed || credentials.web;

// Create OAuth client
const oAuth2Client = new google.auth.OAuth2(client_id, client_secret, redirect_uris[0]);
oAuth2Client.setCredentials(token);

// Create GTM client
const tagmanager = google.tagmanager({ version: 'v2', auth: oAuth2Client });

console.log('\n=== Testing GTM API Connection ===\n');
console.log(`Account ID: ${config.accountId}`);
console.log(`Container ID: ${config.containerPublicId}\n`);

// Test API call
const path_url = `accounts/${config.accountId}/containers/${config.containerId}`;

tagmanager.accounts.containers.get({ path: path_url })
  .then(response => {
    console.log('✓ Connection successful!\n');
    console.log('Container details:');
    console.log(`  Name: ${response.data.name}`);
    console.log(`  Public ID: ${response.data.publicId}`);
    console.log(`  Usage Context: ${response.data.usageContext.join(', ')}\n`);
    console.log('=== Setup Verified ===\n');
    console.log('Ready to use GTM API!\n');
  })
  .catch(error => {
    console.error('✗ Connection failed\n');

    if (error.code === 401) {
      console.error('Error: Unauthorized (401)');
      console.error('→ Token may be expired. Run oauth-authorize.js again.\n');
    } else if (error.code === 403) {
      console.error('Error: Forbidden (403)');
      console.error('→ Check that GTM API is enabled in Google Cloud Console.\n');
    } else if (error.code === 404) {
      console.error('Error: Not Found (404)');
      console.error('→ Check account ID and container ID in gtm-config.json.\n');
    } else {
      console.error('Error:', error.message, '\n');
    }

    process.exit(1);
  });

参考资料

• references/google-cloud-setup.md - Google Cloud Console 设置详细指南，含截图

重要指南

安全最佳实践

1. 切勿提交令牌：

   • 将 gtm-token.json 添加到 .gitignore
   • 令牌包含敏感的访问凭据

2. 凭据文件安全：

   • 可以提交 gtm-credentials.json（Desktop app 类型不包含机密信息）
   • 但建议将其添加到 .gitignore，以提高安全性

3. 令牌刷新：

   • 令牌在 1 小时后过期
   • 刷新令牌（已包含）可自动续期
   • googleapis 会自动处理刷新

常见问题

问题：“googleapis not found” → 解决方案：运行 npm install googleapis --save

问题：“Invalid redirect URI” → 解决方案：确保 OAuth 客户端类型为“Desktop app”，而非“Web application”

问题：“403 Forbidden” → 解决方案：在 Google Cloud Console 中启用 GTM API

问题：“404 Not Found” → 解决方案：确认账号 ID 和容器 ID 正确

问题：“Token expired” → 解决方案：再次运行 oauth-authorize.js 以获取新令牌

问题：“Workspace not found” / 技能意外创建了新工作区 → 原因：GTM 会在发布后删除工作区。已存储的工作区 ID 会失效。 → 解决方案：技能现在会动态解析工作区。无需采取任何操作。

测试

设置完成后，使用以下内容验证：

node scripts/test-connection.js

预期输出：

✓ Connection successful!

Container details:
  Name: My Website
  Public ID: GTM-XXXXXX
  Usage Context: web

=== Setup Verified ===

执行检查清单

• 存在 package.json（Node.js 项目）
• 已安装 googleapis
• 已创建 Google Cloud 项目
• 已启用 GTM API
• 已创建并下载 OAuth 凭据
• 已保存 gtm-credentials.json
• 已获取 GTM 账号 ID
• 已获取 GTM 容器 ID
• 已创建 gtm-config.json
• 已完成 OAuth 授权
• 已保存 gtm-token.json
• 已成功测试 API 连接
• 已将 gtm-token.json 添加到 .gitignore

支持文件

• examples/sample.md - 设置会话示例，展示各阶段的输出和创建的文件

输出文件

• gtm-credentials.json - OAuth 2.0 客户端凭据
• gtm-token.json - 访问令牌和刷新令牌（敏感信息）
• gtm-config.json - GTM 账号和容器配置

后续交接

设置成功后：

✓ GTM API configured and validated

Next step: Invoke gtm-implementation skill to:
- Implement dataLayer events in your code
- Create GTM variables, triggers, and tags via API

Ready to implement? Invoke gtm-implementation skill.

常见问题

问：我可以在多个项目中使用相同的凭据吗？ 答：可以。将 gtm-credentials.json 复制到其他项目即可。每个项目都需要自己的令牌（gtm-token.json）。

问：如果我有多个 GTM 容器怎么办？ 答：分别为每个容器运行设置。创建不同的 gtm-config.json 文件，或使用不同的项目目录。

问：我需要 Google Cloud 结算账号吗？ 答：不需要。GTM API 可免费使用，无需结算账号。

问：我之后可以撤销访问权限吗？ 答：可以。前往 https://myaccount.google.com/permissions，撤销对“GTM Automation Script”的访问权限。

问：此请求需要哪些范围？ 答：tagmanager.edit.containers - 对 GTM 容器的读写权限。这允许创建或更新变量、触发器和标记。