meta-ads

Meta 広告（Marketing API）

Meta（Facebook、Instagram、Messenger、Click-to-WhatsApp、Threads）から広告パフォーマンスデータを取得して分析を行い、明示的な確認を得たうえで変更を書き戻します（一時停止、予算変更、複製、画像とコピーを含むキャンペーンの完全な作成）。

このスキルを参照するタイミング

Meta 広告のパフォーマンス、クリエイティブの健全性、オーディエンス／配置の構成、キャンペーン管理に関する質問があった場合です。ユーザーがプラットフォームを指定せずに「広告の調子はどうですか」と尋ねた場合、デフォルトで決めつける前に、Meta と Google のどちらを指すのか確認してください。

スクリプトに触れる前に理解しておくべき3つのこと

1. スクリプトの実行場所が重要です。 スクリプトはオープンインターネット経由で graph.facebook.com を呼び出します。一部の実行環境（特定の構成における Claude の Linux サンドボックスを含む）では、プロキシによってこのエンドポイントへのアクセスがブロックされます。最初の呼び出しで ProxyError／Tunnel connection failed: 403 が発生した場合は、ユーザーのホストマシン（macOS、Windows、Linux）上で、そのマシンの Python を使ってスクリプトを実行してください。OS ごとのコマンドは次のとおりです。

• macOS: python3 scripts/auth_check.py、依存関係は python3 -m pip install --user requests でインストールします
• Windows: python scripts/auth_check.py（python が PATH にない場合は py scripts/auth_check.py）、依存関係は python -m pip install --user requests でインストールします
• Linux: python3 scripts/auth_check.py、依存関係は python3 -m pip install --user requests でインストールします（Debian／Ubuntu 22 以降では --break-system-packages を追加します）

スクリプト自体は純粋な Python で、依存関係は requests ひとつだけです。また、シェルや OS に依存しないため、依存関係をインストールすればどこでも同じように実行できます。

2. WhatsApp は独立した広告配信面ではありません。 Click-to-WhatsApp 広告は Facebook と Instagram の配置に表示されます。Marketing API では、destination_type=WHATSAPP を持つ通常の広告として表示され、コンバージョンイベントは actions の下に含まれます（onsite_conversion.messaging_conversation_started_7d などを確認してください）。ユーザーに「WhatsApp 広告ダッシュボード」があると案内しないでください。そのようなものはありません。

3. 読み取りは安全ですが、書き込みは安全ではありません。 インサイトエンドポイント（GET）は冪等で、無害です。一時停止／予算変更／複製の操作（POST）は実際の資金に影響します。references/write-actions.md に記載されている書き込みルールは厳守してください。書き込みを行う前に必ずこのファイルを読んでください。

37か月分のデータ制限

Meta のインサイト API で取得できるのは、過去37か月分のデータのみです。それより古いキャンペーンはエラー 3018 を返し、実質的に確認できません。ユーザーが「これまでで最も成果の良かったキャンペーンは何ですか」と尋ね、対象期間の活動がこの範囲より前である場合は、「API では確認できません。Ads Manager のアーカイブ済みレポート UI を確認してください」と回答してください。失敗するクエリを開始する前に、この制限を伝えてください。

何よりも先に：セットアップを確認してアカウントを特定する

最初の3つの呼び出しは必ず次のとおりです。

1. python scripts/auth_check.py — トークンは有効か、どの ID に解決されるか、広告アカウントはいくつ認識されるかを確認します。
2. python scripts/list_accounts.py --with-recent-spend — 現在実際に広告を配信しているアカウントはどれかを確認します（過去30日間の消化額、次に累計消化額の順に並びます）。これを使って META_AD_ACCOUNT_ID に設定するアカウントを決めます。
3. python scripts/list_campaigns.py — 適切なアカウントが見つかったら、そのアカウントにどのキャンペーンがあるかを確認します。

いずれかが失敗した場合は、作業を止めて references/setup.md に沿ってユーザーを案内してください。認証情報を推測して対処しようとしないでください。

初めてのユーザー向けセットアップガイド

references/setup.md は、操作を1つずつ案内する手順書です。ユーザーがまだ認証情報を持っていない場合：

1. 一度に1つの手順だけ案内します。 ドキュメント全体を一度に提示しないでください。まず使用している OS を尋ね、その OS に対応する前提条件のブロックを提示します。次に進む前に、ユーザーから「完了」と報告されるまで待ちます。
2. パスの選択を確認します。 チャットで手順 0 の判断に関する質問を一緒に確認します。決めつけないでください。特に「Instagram から投稿を宣伝していますか？」は誤って判断しやすい質問です。
3. 貼り付けられた内容を読み返します。 トークン、App ID、広告アカウント ID を共有してもらったら、内容を読み返し（トークンは先頭8文字だけ残して伏せます）、次に進む前に正しいことを確認します。これにより、セットアップで最も多い不具合、つまり広告アカウント ID の欄にシステムユーザー ID を貼り付けてしまう問題を防げます。
4. 次に進む前に検証します。 .env に値を入力したら、すぐに auth_check.py を実行します。検証結果が ok: true になるまで、分析コマンドを実行させないでください。「レポートが空です」という問題は、すべて不完全な .env が原因です。
5. すべてのコマンドでユーザーの OS に合わせます。 「Windows を使っています」と言われた場合は、python3 ではなく python または py を案内します。「Mac」と言われた場合は、python3 を使用します。setup.md には OS ごとのブロックがあるので、該当するものをチャットにコピーします。

必須の環境変数（セットアップ時にユーザーが一度だけ入力します）：

• META_ACCESS_TOKEN — 長期間有効なユーザートークン（パス B、60日間）またはシステムユーザートークン（パス A、期限なし）のいずれかです。詳しくは以下の判断ツリーを参照してください。
• META_AD_ACCOUNT_ID — デフォルトの広告アカウント。形式は act_1234567890 です（スクリプトでは、呼び出しごとに上書きするための --account-id を指定できます）。
• META_API_VERSION — デフォルトは v25.0 です（2026年初頭時点の現行バージョン。v26.0 は 2026年9月頃に予定されています）。

ユーザーはこれらを作業ディレクトリの .env ファイルに記述するか、シェルでエクスポートします。スクリプトは .env がある場合、自動的に読み込みます。assets/env.template を参照してください。

パス A とパス B：どちらのトークンを使うか？

セットアップで最も多い失敗の原因です。最初に正しいパスを選びましょう。

次の場合はパス A（システムユーザートークン）を使用します：

• 自分が管理している Meta ビジネスマネージャ内で広告を配信している。
• 分析したい広告アカウントが、その BM に所有されている。
• 期限のないトークンが必要である。

次の場合はパス B（長期間有効なユーザートークン）を使用します：

• Instagram アプリから投稿を宣伝している（その場合、BM の外に個人用広告アカウントが作成されることがよくあります。そのアカウントは、どれだけ権限を付与してもシステムユーザートークンからは見えません）。
• 広告アカウントが BM ではなく、個人の Facebook プロフィールに紐付けられている。
• 個人の Facebook ログインでアクセスできるすべての広告アカウントを確認したい（通常、最も広範囲を確認できます）。

どちらかわからない場合： パス B から始めます。パス B では、パス A で確認できるアカウントをすべて確認できます。重要なアカウントを特定したら、必要に応じて BM に移し、恒久的に使えるパス A に切り替えられます。

両方のパスの詳しいセットアップ手順：references/setup.md。

ワークフロー：読み取り操作

読み取りリクエストでは、次の手順に従ってください。

1. 適切なスクリプトを選びます。 一から作り直さないでください。同梱スクリプトでよくあるケースに対応できます。

   • auth_check.py — トークンを検証し、閲覧可能なアカウントを簡潔に一覧表示します
   • list_accounts.py — すべての広告アカウントを検出し、ステータスをデコードして、累計支出額とオプションの直近の支出額を表示します
   • list_campaigns.py — アカウント内のキャンペーンをステータスフィルター付きで表示します
   • fetch_insights.py — 主力スクリプトです。日付範囲、内訳（publisher_platform、age、gender、country、placement、device_platform）、レベル（account/campaign/adset/ad）、カスタムフィールドリストに対応します。実行する前に --help を読んでください。
   • creative_fatigue.py — 広告レベルでフリークエンシーとCTRの低下を分析します
   • anomaly_detect.py — 日付範囲を直前の同等期間と比較し、大きな変化を検出します
   • exchange_token.py — パス B 専用：有効期間の短いユーザートークンを、60日間有効な長期トークンに交換します

   書き込みスクリプト（停止／予算／複製／作成 — まず write-actions.md を読んでください）：

   • pause_ad.py — 単一のキャンペーン、広告セット、または広告を停止／再開します
   • update_budget.py — 1回あたりの安全上限を2倍として、日予算または通算予算を変更します
   • duplicate_ad.py — 広告、広告セット、またはキャンペーン全体を新しいコピーとして複製します
   • create_campaign.py — 仕様 JSON からキャンペーン全体（キャンペーン + 広告セット + クリエイティブ + 広告）を作成します。画像のアップロードとインタレストの解決に対応します。references/campaign-creation.md を参照してください。
   • rollback_creation.py — 状態ファイルを使用して、create_campaign.py の実行で作成されたすべてのオブジェクトを停止または削除します

2. 実行して、JSON 出力を取得します。 すべてのスクリプトは、標準出力に構造化された JSON を出力します。人が読む形式のテキストを解析しようとしないでください。そのような出力はありません。ユーザーが生データを保存したい場合は、ファイルにパイプしてください。例：python scripts/fetch_insights.py ... > insights.json

3. プレイブックを使って分析します。 データを取得したら、該当するパターン（疲労、ファネル、オーディエンス構成、異常）について references/analysis-playbooks.md を参照してください。プレイブックには、重要な閾値と推奨事項が記載されています。

4. ユーザーの希望する言語で提示します。 ユーザーがヘブライ語で書いた場合は、ヘブライ語で回答してください。指標名は英語（CTR、CPA、ROAS）のままにして、Ads Manager と照合しやすくしてください。ドキュメント／ダッシュボードを求められた場合は、設定済みのデザインシステムスキルに従ってください。

ワークフロー：書き込み操作（停止、予算、複製）

これらは危険な操作です。例外なく、毎回次の手順に従ってください。

1. 実行前に、操作とその影響をわかりやすく説明します。 例：「広告 Campaign_v3（ID 120214...）を停止します。この広告は過去7日間で ₪47 を消費し、CTR は0.8%でした。よろしいですか？」
2. チャットで明示的な yes／confirm、またはユーザーの言語で同等の確認が得られるまで待ちます。 会話内で以前に「進めて」と言われていても、確認は引き継がれません。書き込み操作ごとに個別の確認が必要です。
3. デフォルトでは、一度に1つの操作だけを行います。 ユーザーが広告12件の一括停止を希望した場合は、番号付きリストを提示し、「12件すべてを停止」のような明示的な確認を一度に得てください。ただし、呼び出しはそれぞれ個別に記録します。
4. スクリプトが対応している場合は、必ず最初にドライランを実行します（--dry-run フラグは、API を呼び出さずに変更内容を表示します）。
5. 1回の呼び出しで予算を自動的に+50%を超えて変更しないでください。 ユーザーが3倍への増額を希望する場合は、毎回確認を得ながら段階的に実施します。大幅な予算変更を行うと、Meta の学習フェーズもリセットされます。

ルールと例外については、references/write-actions.md に詳しく記載されています。pause_ad.py、update_budget.py、duplicate_ad.py、create_campaign.py のいずれかを実行する前に、必ず読んでください。

ワークフロー：キャンペーンをゼロから作成する

create_campaign.py を使うと、仕様 JSON からキャンペーンツリー全体（キャンペーン → 広告セット → クリエイティブ → 広告）を一度に作成できます。命名規則を統一し、作成履歴を監査可能にしたうえで、まったく同じ構成の A/B 配信を行いたい場合に便利です。

スクリプトを実行する前に、次の点を確認してください。

1. ユーザーがピクセルを持っているか確認します。 ピクセルがない場合は、objective: OUTCOME_TRAFFIC と optimization_goal: LINK_CLICKS を必ず設定してください。コンバージョンを計測できないアカウントでコンバージョンキャンペーンを作成しないでください。Meta に対し、実際には発生を確認できないイベントに向けた最適化を行うために費用を支払うことになります。この点をユーザーに伝え、ピクセルの設置を待つか、トラフィック目的で計測なしのまま配信を開始するか判断してもらいます。
2. アカウント残高を確認します。 広告アカウントのステータスコードが 3（UNSETTLED）の場合、オブジェクトは作成できますが、残高が精算されるまで配信は始まりません。作成を止める必要はありませんが、ユーザーが広告費の利用を想定する前に伝えてください。
3. 適切なページと Instagram ID を特定します。 ユーザーが複数のページを所有していることはよくあります。/me/accounts と /act_.../promote_pages を照会し、そのページで過去に成果を上げた広告を配信していたか照合してください（最近の広告をいくつか取得し、creative.effective_object_story_id を確認すると、先頭部分からページ ID を特定できます）。
4. すべて PAUSED をデフォルトにします。 作成時には、キャンペーン、広告セット、広告をすべて PAUSED にしてください。ユーザー自身がクリエイティブを確認したうえで、Ads Manager から ACTIVE に切り替えます。これは最後の安全策です。
5. 必ず最初にドライランを実行します。 create_campaign.py --spec foo.json --dry-run を実行すると、解決済みの興味関心 ID、通貨に合わせて修正された予算、ターゲティングの概要を含む完全な計画が表示されます。--confirm の実行を求める前に、ドライランの内容をわかりやすくユーザーに説明してください。

write-actions.md に従い、同じセッション内でユーザーが計画をすでに承認していても、--confirm の実行には改めて明示的な確認が必要です。その確認では、一般的な「ok」ではなく、実行する操作を明記する必要があります（例：「作成を確認します」、「בצע יצירה」）。

完全な仕様形式、フィールドのリファレンス、通貨の処理、興味関心の解決、状態ファイル、ロールバックの詳細については、references/campaign-creation.md を参照してください。

create_campaign.py を使用しない場合

• 既存の広告セットに広告を 1 件追加する場合 — 広告エンドポイントを直接呼び出すか、UI を使用してください。広告 1 件のために仕様を作成して実行するのは大げさです。
• 成果の出た広告を複製する場合 — duplicate_ad.py のほうが速く、学習シグナルも保持されます。
• ダイナミッククリエイティブ、カタログ広告、コレクション広告 — v1 ではサポートされていません。このスクリプトが扱うのは link_data を使った単一画像のリンク広告のみです。必要に応じて拡張するか、派生スクリプトを作成してください。

スクリプトがすでに処理している注意点

• 通貨の最小単位。 amount_spent、balance、spend_cap、daily_budget、lifetime_budget は、Meta から最小単位（アゴラ／セント／ペンス）の文字列として返されます。list_accounts.py と list_campaigns.py は、これらを _major または小数表記のフィールドで基本通貨単位に変換します。小数点以下の単位がない通貨（JPY、KRW、VND、ISK、TWD など）は除算されません。
• アカウントステータスコード。 スクリプトは 1→ACTIVE、2→DISABLED、3→UNSETTLED、7→PENDING_RISK_REVIEW などにデコードします。
• ページネーション。 すべてのスクリプトは meta_client.paginate() を使って自動的にページネーションします。
• レート制限。 meta_client._request() はサブコード 1487742 / 2446079 / 1487390 に対してバックオフして再試行します。
• 非同期インサイト。 fetch_insights.py は、同期クエリがタイムアウトする場合に非同期ジョブへ自動的にフォールバックします（または --async を指定して強制できます）。
• DELETED キャンペーン。 Meta のキャンペーンエンドポイントでは、DELETED を指定するとエラー 1815001 が返されます。このスクリプトの --status の選択肢には、意図的に DELETED を含めていません。削除済みキャンペーンを確認するには、Ads Manager の UI を使用してください。

同梱スクリプトで対応できないこと

• 初回の認証／トークン生成（手動で行います。references/setup.md を参照してください）。
• Pixel／Conversions API イベントの取り込み（別の API が必要です）。
• ダイナミッククリエイティブ／カタログ／コレクション広告フォーマット（単一画像のリンク広告のみ対応しています）。
• カスタムオーディエンスの作成（既存のオーディエンスは参照できますが、ここから新規作成することはできません）。
• 配信中のクリエイティブをそのまま編集すること（create_campaign.py で新しいクリエイティブを作成します。既存のクリエイティブの編集には別の API 形式が必要です）。

スクリプトで対応できないことが必要な場合は、書き込み可能なコピー内でスキルを拡張して再パッケージ化してください。書き込みスクリプトのパターンについては、create_campaign.py が確立しているものを references/campaign-creation.md で確認してください。ユーザーの作業ディレクトリに個別の使い捨てスクリプトを作成せず、スキルに統合して次回の実行にも活用できるようにしてください。

参考ファイル

すべてを最初に読むのではなく、必要に応じて読んでください。

• references/setup.md — 初回セットアップ：Path A と Path B の選択ツリー、アプリの作成方法、トークンの取得方法、アカウント ID の確認方法。ユーザーに認証情報がない場合、または auth_check.py が失敗した場合に読んでください。
• references/insights-fields.md — フィールド用語集、内訳のオプション、一般的な指標の定義、注意点（アトリビューション期間、action_attribution、重複排除）。カスタムインサイトクエリを作成する際に読んでください。
• references/analysis-playbooks.md — クリエイティブの疲弊、オーディエンス分析、ファネル診断、異常への対応パターン。データの取得だけでなく分析を求められた場合に読んでください。
• references/write-actions.md — 書き込みを伴う操作の前に必ず読んでください。確認フロー、安全性のしきい値、ロールバックのパターンが記載されています。create_campaign.py を使用する前に、キャンペーン作成のセクションも確認してください。
• references/campaign-creation.md — create_campaign.py の仕様形式、フィールドリファレンス、通貨の扱い、興味・関心の解決方法、状態ファイル、ロールバックの詳細。キャンペーンの開始、A/B テスト、または新しい広告配信をゼロから作成するよう求められた場合に読んでください。
• references/troubleshooting.md — よくある失敗の原因（サンドボックスプロキシ、SU トークンでは IG のブーストが表示されない、requests モジュールの不足、エンコーディングの問題、37 か月の上限など）。スクリプトが ok: false を返すか、予期しない動作をした場合に読んでください。

個人利用を超えて拡張する場合

このスキルは、1 人のユーザー、1 組の認証情報、少数の広告アカウント向けに作られています。マルチテナント／クライアント代理店での利用（1 人のオペレーターが数十社のクライアント BM を管理する形態）は、別の構築が必要です。

• クライアントごとの認証情報の保存（全員のトークンを 1 つの .env に保存しない）。
• 各クライアントが、自分の BM から独自の System User トークンを発行する。
• すべての書き込み操作について、実行者と対象アカウントを含む監査ログを記録する。

個人向けのスキルをマルチテナント向けに改修しようとしないでください。これは別の構築が必要だとユーザーに伝えてください。