snapchat-ads

Snapchat 広告キャンペーン

Snapchat Marketing API v1 を介して Snapchat 広告を管理するための戦略ガイドです。このツールキットは生の HTTP クライアントのため、パラメーターの型はドキュメントどおりに正確に指定する必要があります。文字列は文字列、整数は整数として送信し、金額はすべてマイクロ通貨単位で指定してください。

要件

• Hyper MCP がインストールされ、接続されていること。 https://app.hyperfx.ai/mcp
• Snapchat Ads の連携が接続されていること（広告アカウントへのアクセス権がある Snap Business アカウント）。https://app.hyperfx.ai/apps。

search("snapchat_ads_list_organizations") で snapchat_ads_list_organizations が見つからない場合は、そこで作業を止め、Hyper MCP を有効にして Snapchat Ads を接続するようユーザーに伝えてください。広告スクワッドの作成や広告配信には、広告アカウントに有効な資金源も必要です。キャンペーン、メディア、クリエイティブは、資金源がなくても作成できます。

このスキルのツールの実行方法

このスキルの各ツールには、正式なツール名が付いています。利用する環境で指定される呼び出し方法を使って実行してください。

環境	ツールを探す	実行する
MCP クライアント（Claude、Cursor、Codex、ChatGPT）	search("<what you want to do>")、続いて describe("<name>")	call("<name>", {...})
Hyper CLI	hyperai search "<what you want to do>"、続いて hyperai describe <name>	hyperai call <name> --json '{...}'

ツールが見つからない場合、その連携はワークスペースに接続されていないか、有効になっていません。作業を止め、接続する連携をユーザーに伝えてください。

対象外 — 他のスキルに引き継いでください

• クリエイティブの生成（広告コピー、画像、動画）→ ad-creative-generation / video-generation。
• 複数プラットフォームでのキャンペーン開始 → Snapchat にはこのスキルを使用し、その後 meta-ads / tiktok-ads を個別に呼び出してください。

重要なルール

CRITICAL：すべての予算と入札額はマイクロ通貨単位です。$1.00 = 1,000,000 マイクロです。$50/日 = 50000000 です。ドルの金額をそのまま渡さないでください。キャンペーンの1日あたりの最低予算／生涯支出上限は $20（20000000）です。

CRITICAL：キャンペーン、広告スクワッド、広告は status="PAUSED" で作成してください。ユーザーが明示的に確認する前に、配信を開始しないでください。すべてデフォルトで PAUSED のため、キャンペーン全体を作成してから削除しても費用は発生しません。デモに最適です。

CRITICAL：更新はJSON-Patch による部分更新です。変更するフィールドだけを渡し、親エンティティを指定してください。snapchat_ads_update_campaign には ad_account_id が必要です。snapchat_ads_update_ad_squad には campaign_id（ad_account_id ではありません）が必要です。snapchat_ads_update_ad には ad_squad_id が必要です。

CRITICAL：アカウントレベルの統計（entity_type="adaccounts"）でサポートされるのは fields="spend" のみです。インプレッション／スワイプ／コンバージョンについては、キャンペーン、広告スクワッド、広告、クリエイティブ、またはメディアレベルでクエリしてください。

CRITICAL：time_range のプリセット（例：LAST_30_DAYS）はありません。start_time と end_time（ISO 8601）を渡してください。両方を省略すると、直近の期間ではなく生涯の合計が返されます。

CRITICAL：広告スクワッドの billing_event は常に IMPRESSION です。bid_strategy="LOWEST_COST_WITH_MAX_BID" と "TARGET_COST" では bid_micro が必須です。"AUTO_BID" では省略してください。

IMPORTANT：広告スクワッドを作成するには、広告アカウントに有効な資金源が必要です。アカウントが PENDING／資金未入金の場合、広告スクワッドの作成は失敗します。これは請求ステータスによるもので、バグではありません。

IMPORTANT：クリエイティブには top_snap_media_id（アップロード済みメディア ID）と headline（34 文字以内）が必要です。brand_name は 32 文字以内です。

IMPORTANT：LOWEST_COST_WITH_MAX_BID／TARGET_COST の場合、bid_micro を推測しないでください。snapchat_ads_get_bid_estimate を使って Snapchat の推奨範囲を取得してください（作成前にターゲティング仕様を指定するか、作成後に ad_squad_id を指定します）。作成前に snapchat_ads_get_audience_size を使って同様にオーディエンスの規模を確認してください。

IMPORTANT（顧客リスト）：snapchat_ads_add_segment_users には、正規化して SHA-256 でハッシュ化済みの識別子が必要です（メールアドレスはハッシュ化前に前後の空白を削除して小文字に変換、電話番号は国番号付きの数字のみ、モバイル広告 ID はハイフンを含む小文字）。1 回の呼び出しにつきスキーマタイプは 1 種類（EMAIL_SHA256、PHONE_SHA256、MOBILE_AD_ID_SHA256）で、ID の上限は 100,000 件です。未加工の PII は決して送信しないでください。マッチングは非同期で行われ、処理後にセグメントサイズが更新されます。

ツール一覧

グループ	ツール
組織とアカウント	snapchat_ads_list_organizations, snapchat_ads_list_ad_accounts, snapchat_ads_get_ad_account
キャンペーン	snapchat_ads_list_campaigns, snapchat_ads_get_campaign, snapchat_ads_create_campaign, snapchat_ads_update_campaign, snapchat_ads_delete_campaign
広告セット	snapchat_ads_list_ad_squads, snapchat_ads_get_ad_squad, snapchat_ads_create_ad_squad, snapchat_ads_update_ad_squad, snapchat_ads_delete_ad_squad, snapchat_ads_estimate_ad_squad_outcomes
広告	snapchat_ads_list_ads, snapchat_ads_get_ad, snapchat_ads_create_ad, snapchat_ads_update_ad, snapchat_ads_delete_ad
クリエイティブ	snapchat_ads_list_creatives, snapchat_ads_get_creative, snapchat_ads_create_creative
メディア	snapchat_ads_list_media, snapchat_ads_create_media, snapchat_ads_upload_media
レポート	snapchat_ads_get_stats, snapchat_ads_create_stats_report, snapchat_ads_get_stats_report
コンバージョン	snapchat_ads_list_pixels, snapchat_ads_list_custom_conversions
オーディエンス	snapchat_ads_list_segments, snapchat_ads_get_segment, snapchat_ads_create_segment, snapchat_ads_update_segment, snapchat_ads_delete_segment, snapchat_ads_add_segment_users, snapchat_ads_remove_segment_users
プランニングの予測	snapchat_ads_get_audience_size, snapchat_ads_get_bid_estimate, snapchat_ads_get_audience_insights
ターゲティング	snapchat_ads_search_targeting

参照ファイルはすべて references/ にあります。 references/<file> の形式で読み込んでください（例：references/discovery.md）。

ルーティング表

ユーザーの目的	まず読むファイル
Snapchat キャンペーンを開始する	references/discovery.md → references/campaign-creation.md
メディアをアップロードする／クリエイティブ、広告セット、広告を作成する	references/campaign-creation.md
ターゲティング（地域、デモグラフィック、興味、デバイス）を解決する	references/targeting.md
カスタムオーディエンス、類似オーディエンス、オーディエンスインサイトを作成する	references/targeting.md
オーディエンスサイズを予測する／推奨入札額を取得する	references/campaign-creation.md
Snap Pixel／カスタムコンバージョンを設定する	references/conversions-and-reporting.md
統計情報を取得する／非同期レポートを作成する／エンティティを更新または削除する	references/conversions-and-reporting.md
目標がまだ明確でない	references/discovery.md — ディスカバリーで目標を明確にします

キャンペーンのワークフロー

組織／アカウントを確認 → アカウントを監査 → 調査（目的、オーディエンス、予算、アセット） → 戦略を確認 → キャンペーンを作成（PAUSED） → メディアをアップロード → クリエイティブを作成 → 広告セットを作成 → 広告を作成 → ユーザーと内容を確認 → 有効化（update_* で ACTIVE に設定）。

既知の制限事項

問題	回避策
クリエイティブの作成に失敗する（以前はエラーが表示されず null になっていました）	ほとんどの場合、profile_properties.profile_id がありません（すべてのクリエイティブタイプで必須です）。list_creatives から取得してください。現在は、null の「成功」ではなく、明確なエラーが表示されます。
広告の作成に型の不一致で失敗する	type を省略し、クリエイティブから導出されるようにしてください（WEB_VIEW → REMOTE_WEBPAGE など）。
予測で OE101 / UNSUPPORTED_DELIVERY_CONSTRAINT が返される	ツールは delivery_constraint を自動で追加します。それでも解決しない場合、そのアカウントタイプ（多くの場合 PARTNER）では成果予測を利用できません。Ads Manager のリーチプランナーを使用してください。
DAY 粒度の統計で期間が拒否される（E1008）	自動で処理されます。get_stats／create_stats_report に ad_account_id を渡すと、ツールはアカウントのタイムゾーンにおける午前0時と時間境界に合わせます。
メディアが E2601（「いずれのクリエイティブタイプの作成にも使用できません」）で拒否される	ファイルが仕様を満たしていません。1080×1920（9:16）の PNG／JPG（5 MB 以下）画像、または 1080×1920 の MP4／MOV を使用してください。適切なサイズでアセットを再生成して再アップロードし、media_status が READY であることを確認してください。
file_path／内部 URL でのアップロードに失敗する（Errno 2／DNS エラー）	代わりに file_id（Hyper ファイル ID）を渡してください。ストレージから直接読み取ります。サーバーのローカルパスや内部 files.* URL は使用しないでください。
アカウントレベルの統計で spend 以外のフィールドが拒否される（エラー E1008）	他の指標は、キャンペーン／広告セット／広告／クリエイティブ／メディアのレベルでクエリしてください。
time_range／日付プリセットがない	start_time と end_time を渡してください。これらを省略すると、全期間の合計が返されます。
資金がないアカウントで広告セットの作成に失敗する	資金源を追加してください。キャンペーン／メディア／クリエイティブは、資金源がなくても機能します。
AUTO_BID 以外の入札戦略で bid_micro が必須	LOWEST_COST_WITH_MAX_BID／TARGET_COST では bid_micro を指定してください。
メディアが 32 MB を超える	自動で処理されます（最大 1 GB までのチャンク分割アップロード）。
部分更新	正しい親 ID を指定して更新ツール（PATCH）を使用してください。オブジェクト全体を再送信しないでください。
顧客リストのアップロードは「成功」するが、セグメントが小さいまま	識別子はアップロード前に正規化し、SHA-256 でハッシュ化する必要があります。マッチングは非同期で行われ、Snapchat ユーザーと一致したハッシュのみがカウントされます。処理後にセグメントの approximate_number_users を確認してください。
類似オーディエンスの作成が拒否される	類似オーディエンスには、十分な数のユーザーが一致した FIRST_PARTY セグメント、countries（ISO-2）、および retention_in_days ≤ 180 からなる、正常なシードが必要です。

安全ルール

絶対にしないでください：

• 組織、広告アカウント、キャンペーン、メディア、またはクリエイティブの ID を推測する。検索するか、ユーザーに確認してください。
• アカウントの監査フェーズを省略する。
• ユーザーの明示的な承認なしに、キャンペーン、広告セット、または広告を作成する。
• ユーザーの同意なしに、何かを ACTIVE に設定する。
• マイクロ通貨ではなく、ドル建て金額を渡す。
• adaccounts レベルで spend 以外の指標をクエリする。
• time_range プリセットを使用する。常に start_time／end_time を渡してください。
• bid_micro なしで LOWEST_COST_WITH_MAX_BID／TARGET_COST を使用する。
• 更新ツールに誤った親 ID を渡す（広告セット → campaign_id、広告 → ad_squad_id）。