mcpField
G
google-ads-scripts

google-ads-scripts

github.com/henkisdabroマーケティング・グロース93114 回インストール4 週間前に更新
リポジトリ

google-ads-scripts について

AdsApp API を使った Google Ads Scripts 開発のガイドスキルです。広告主や開発者が JavaScript でキャンペーン、入札、レポート、予算を自動管理する方法を扱います。

主な機能

  1. 01キャンペーン作成と一括更新
  2. 02キーワードと入札額の管理
  3. 03レポート作成と Sheets 出力
  4. 04予算の監視と配分
  5. 05キャンペーンの自動最適化
  6. 06エラー処理と監査ログ

活用シーン

  1. 01品質スコアが低く費用の高いキーワードの停止
  2. 02ROAS または CPA 目標に基づく入札調整
  3. 03広告指標の Google Sheets への出力
  4. 04支出が上限に達した際のキャンペーン停止

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/henkisdabro/wookstar-claude-plugins --skill google-ads-scripts

インストール後、Claude Code で/google-ads-scriptsを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

assets/
bid-manager-template.js
campaign-optimizer-template.js
references/
ads-api-reference.md
best-practices.md
examples.md
patterns.md
scripts/
validators.py

詳細

Google Ads Scripts

概要

AdsApp API を使用して Google Ads Scripts を開発するためのガイダンスです。Google Ads エディタで実行される JavaScript を通じて、キャンペーン管理、入札の最適化、パフォーマンスレポート、一括操作を自動化します。

主な機能

1. キャンペーン操作

キャンペーンの作成、変更、ステータス変更、一括更新をプログラムで管理します。条件を指定して AdsApp.campaigns() を使用し、ステータス、予算、名前のパターン、種類で絞り込みます。整理のためにラベルを適用します。

2. キーワードと入札の管理

パフォーマンスに基づいて、キーワードのターゲティングと入札調整を自動化します。品質スコアで絞り込み、ROAS／CPA の目標に基づいて上限 CPC 入札単価を調整し、除外キーワードを追加・削除して、入札最適化アルゴリズムを実装します。

3. パフォーマンスレポート

キャンペーン、広告グループ、キーワード、広告の統計情報を使用してカスタムレポートを作成します。カスタムの日付範囲で指標を取得し、派生指標（CTR、CPC、コンバージョン率）を計算して、データを Google Sheets にエクスポートします。

4. 予算管理

支出を管理し、キャンペーン間で予算を配分します。キャンペーンの日予算を取得・設定し、しきい値に対する支出を監視して、上限に達したキャンペーンを一時停止し、パフォーマンスに基づいて予算を配分します。

5. 自動ルールと最適化

自動的な意思決定を通じて、キャンペーン管理にインテリジェンスを組み込みます。パフォーマンスの低いキーワードを一時停止し、パフォーマンスの高いキーワードの入札単価を引き上げ、曜日ごとの傾向に基づいて予算を調整します。

6. エラー処理と回復性

API の上限、割り当ての問題、実行時エラーに対して堅牢なエラー処理を実装します。try-catch ブロック、null チェック、監査証跡用のシートベースのログ記録を使用します。実行時間の上限が 30 分であることに注意してください。

クイックスタート

最も一般的なパターンは、品質スコアが低く、支出が多いキーワードを一時停止することです。

function pauseLowQualityKeywords() {
  const keywords = AdsApp.keywords()
    .withCondition('ad_group_criterion.status = "ENABLED"')
    .withCondition('ad_group_criterion.quality_info.quality_score < 4')
    .withCondition('metrics.cost_micros > 100000000') // 100 in account currency
    .forDateRange('LAST_30_DAYS')
    .get();

  let count = 0;
  while (keywords.hasNext()) {
    keywords.next().pause();
    count++;
  }
  Logger.log(`Paused ${count} low-quality keywords`);
}

ベストプラクティス

  • 一括操作 - まずエンティティを収集してから処理します。ループ内で個別に API を呼び出すのは避けてください。
  • API レベルでの絞り込み - JavaScript で絞り込むのではなく、.withCondition() を使用します。
  • エラー処理 - 操作を try-catch で囲み、エラーをシートまたはメールに記録します。
  • 実行時間の上限 - 大規模なアカウントでは .withLimit() と一括処理を使用します（タイムアウトは 30 分）。
  • マイクロ単位の変換 - 通貨の値はマイクロ単位です（表示するには 1,000,000 で割ります）。
  • 監査ログ - 変更をすべてタイムスタンプとともに Google Sheets に記録します。

各プラクティスの詳しいコード例については、references/best-practices.md を参照してください。

他のスキルとの連携

  • google-apps-script - Google Sheets のレポート、Gmail 通知、Drive のファイル管理、トリガーの設定に使用します。
  • google-analytics - GA4 Measurement Protocol と組み合わせて、スクリプトによってトリガーされたイベントを追跡します。
  • google-tagmanager - 包括的なトラッキングを実現するため、GTM の設定と連携します。

検証とテスト

デプロイ前のチェックには、scripts/ 内の検証スクリプトを使用します。

  • scripts/validators.py - 変更を適用する前に、キャンペーンデータ、入札値、予算額を検証します。

トラブルシューティング

よくある問題：

  1. 実行タイムアウト - .withLimit() で対象を絞るか、バッチで処理します。
  2. 割り当て超過 - API 呼び出しの頻度を下げ、キャッシュしたデータを使用します。
  3. 型エラー - 通貨の値はマイクロ単位に変換することを忘れないでください。
  4. null 値 - プロパティにアクセスする前に、必ず null かどうかを確認してください。

デバッグには Logger.log() を使用します。ログはスクリプトエディタの「表示」>「ログ」から確認できます。

参考資料

詳細なドキュメントは必要に応じて読み込んでください。

  • references/ads-api-reference.md - セレクター、メソッド、条件、統計、エンタープライズ向けのパターンを含む AdsApp API の完全なリファレンス
  • references/examples.md - 詳細なコード例：品質の低いキーワードの一時停止、ROAS に基づく入札単価の最適化、キャンペーンのパフォーマンスの Sheets へのエクスポート
  • references/best-practices.md - コードブロック付きのベストプラクティス：一括操作、API フィルタリング、エラー処理、マイクロ単位への変換、監査ログ
  • references/patterns.md - 再利用可能な自動化パターン：条件に基づく入札単価の調整、品質スコアのモニタリング

コメント

Markdown 対応