Apple Ads MCP

Apple Ads MCP

Apple Ads MCP は、Apple Ads Platform API v1 向けのローカル優先の Model Context Protocol サーバーです。Codex、Claude、その他の MCP クライアントに、App Store 広告アカウントを調査、確認し、安全に運用するための型付きツールを提供します。

サーバーはデフォルトで読み取り専用です。認証情報はお使いのマシン内に保存され、アカウントに紐づく呼び出しでは明示的なプロファイルと広告アカウントを指定し、すべての変更操作にはプレビューと有効期間の短い使い捨てレシートが必要です。

Apple Ads MCP は独立したオープンソースソフトウェアです。Apple Inc. とは提携、推奨、または後援関係にありません。Apple Ads および App Store は Apple Inc. の商標です。

クイックスタート

macOS または Linux では、Homebrew を使ってリリース済みバイナリをインストールします。

brew install zelentsov-dev/tap/apple-ads-mcp
apple-ads-mcp version

ローカルに読み取り専用プロファイルを作成します。このコマンドは秘密鍵の絶対パスを保存します。秘密鍵をチャット、issue、ログ、リポジトリに貼り付けないでください。

apple-ads-mcp config init
apple-ads-mcp auth doctor --profile production-read-only
apple-ads-mcp accounts discover --profile production-read-only

デスクトップアプリや IDE 拡張機能が引き継いだシェルの PATH に依存しないよう、Homebrew の絶対パスを指定してサーバーを登録します。

Codex：

codex mcp add apple-ads -- "$(brew --prefix)/bin/apple-ads-mcp" serve --stdio
codex mcp list

Claude Code：

claude mcp add --scope user apple-ads -- "$(brew --prefix)/bin/apple-ads-mcp" serve --stdio
claude mcp get apple-ads

すでに起動しているデスクトップアプリ、CLI セッション、または IDE 拡張機能を再起動してから、新しい会話を開始します。安全な最初のリクエストは次のとおりです。

server_info を呼び出してから、明示的に指定したプロファイル、広告アカウント、アプリに対して account_health を実行してください。書き込みは有効にしないでください。

その他の読み取り専用で役立つ質問：

• 「広告を掲載できるアプリを一覧表示し、対象外となる要因があれば説明してください。」
• 「何も変更せずに、現在の Apple Ads キャンペーン構成を監査してください。」
• 「キーワードの機会を見つけ、Apple が示す根拠と推測を分けてください。」

現在のリリース

現在のリリースは v0.3.8 です。キャンペーンと広告グループの bidStrategy.bid スキーマおよび実行時検証を Apple Ads Platform API v1 に合わせています（キャンペーンでは TargetCpa、広告グループではデフォルトの Max CPT）。また、キャンペーンを MANUAL_CPT に切り替える際、Apple が以前の TargetCpa をクリアするよう "bid": null を明示的に送信し、operations_verify で小数の金額文字列を正規化します。v0.3.8 のリリースおよび移行に関するメモを参照してください。

v0.3.5 のバージョンを含む最終アーカイブの命名、v0.3.4 のフォーミュラ単位の信頼、v0.3.3 の正確なパス検証、v0.3.2 のワンコマンドによるオンボーディングも引き続き利用できます。

最適化が自動で実行されることはありません。サーバーにスケジューラーはなく、バックグラウンドで支出を変更することもありません。読み取り専用セッションでは、ベースラインの作成と計画ができます。計画の適用には引き続き、すべての書き込みゲート、有効な名前付きポリシー、1つのレシート、最新のレポートとインベントリのドリフト確認、項目単位の検証が必要です。

このリリースは、Apple が公開している次の4つの App Store 広告プレースメントに対応しています。

• 検索結果
• 検索タブ
• 今日のタブ
• プロダクトページ

プレースメントの利用可否は、選択したアカウント、アプリ、ストアフロント、クリエイティブ、および Apple による適格性判定によって異なります。利用できないプレースメントは not_eligible として報告され、サーバーが Apple の検証を回避しようとすることはありません。

キーワードと除外キーワードは、検索結果のリソースです。Platform API は検索結果キャンペーンで Ad リソースを明示的に指定することを拒否するため、このプレースメントはキャンペーン、広告グループ、キーワード、プロダクトページ設定を通じて運用します。明示的な広告は、その他のプレースメントでは引き続き適格性の判定対象です。デフォルトのプロダクトページクリエイティブは、アプリと広告アカウントごとに一意です。そのため、重複を作成しようとせず、照会して再利用してください。

できること

領域	主なツール
アクセスと準備状況	auth_check、ad_accounts_list、ad_account_get、advertiser_resources_list、account_health
アプリとストアフロント	apps_search、apps_get、apps_eligibility、app_locale_details、supported_app_languages、app_store_geo_search
インベントリ	campaigns_query、ad_groups_query、keywords_query、negative_keywords_query、ads_query、creatives_query、shared_budgets_query、campaign_inventory
診断	却下理由、キャンペーンのステータス理由、変更履歴、アカウントとキャンペーンの監査
調査	キーワード、フレーズ、カテゴリ、目標 CPA の提案、検索人気度、インプレッションシェア
レポート	型付きのキャンペーン、広告グループ、広告、キーワード、検索語句レポート
キャンペーン操作	作成／更新、予算、国、スケジュール、一時停止、再開のプレビュー
広告グループ操作	作成／更新、スケジュール、ターゲティング、Search Match、入札、非推奨の CPA 上限、一時停止、再開のプレビュー
キーワード	個別および一括のターゲティング／除外キーワードの作成／更新、入札、一時停止、再開のプレビュー
広告とクリエイティブ	型付き App Store クリエイティブと広告の作成／更新、一時停止、再開のプレビュー
推奨事項	1 日の予算と目標 CPA の読み取り、適用プレビュー、却下プレビュー
最適化	名前付きのローカルポリシー、28 日間のベースライン、学習／アクティブプラン、複合プレビュー／適用／検証、範囲を限定した履歴
共有予算	非公開のローカル請求プロファイルを使用した、LOC のみの型付き作成／更新／割り当て／割り当て解除プレビュー
ライフサイクル	キャンペーン、広告グループ、キーワード、除外キーワード、広告、クリエイティブ、共有予算の削除プレビュー（それぞれ個別に制御）
検証	operations_inspect、operations_apply、operations_verify、リソースの直接読み戻し

各リストの上限は 200 件で、next ページネーションを使用します。レスポンスには簡潔なテキストと MCP structuredContent が含まれます。Apple の生のエンベロープや請求連絡先の PII は公開されません。

生のリクエストを送信するツール、アカウント／委任の変更、自動スケジューラー、Apple Maps の機能、従来の Campaign Management API v5 のサポートはありません。

安全モデル

書き込みが可能になるのは、以下のすべてのゲートを通過した場合のみです。

1. Apple API ユーザーに、互換性のある書き込みロールが割り当てられていること。
2. サーバーが --allow-writes を指定して起動していること。
3. 選択したプロファイルで allowWrites: true が設定されていること。
4. 専用の *_preview ツールが、アカウント、アプリ、ストアフロント、プレースメント、通貨、ペイロードを検証すること。
5. operations_apply が、同じ有効期限内のレシートを受け取ること。
6. 影響を受けるインベントリが、プレビュー時に取得した状態と引き続き一致していること。

プレビューのレシートは10分後に期限切れとなり、適用時に一度だけ使用できます。全レシートレコードが削除された後も、期限切れ状態を明示的に保持するため、上限付きのトゥームストーンが保持されます。すべての変更レシートは、対象IDの正規化されたオブジェクトスコープに紐付き、読み取り時の正確なフィンガープリントを保持します。作成と親の削除では、影響を受けるインベントリと上限付きのカスケードスコープも紐付きます。そのため、重複するオブジェクトに対する汎用、一括、削除、レコメンデーション、共有予算、最適化の各検証は、同時に実行できません。独立した広告グループのインベントリは並列実行できます。一括レシートは、項目ごとに applied、failed、unknown の状態を返します。ターゲティングキーワードの一括レシートには、項目ごとに複数の広告グループを含めることができますが、Apple への一括リクエストは1回だけ送信します。Apple がバッチの一部のみを受け入れる場合があります。サーバーはロールバックを保証しません。最適化の適用結果が未解決の場合、サニタイズされた復旧手順が所有者のみアクセスできるローカル履歴に保存されます。これにより、プロセスの再起動後や通常のプレビュー削除後でも、operations_verify で提供されたレシートを照合できます。

同じインベントリスナップショットから作成された独立したプレビューは、最初の適用後に意図的に乖離します。関連するキーワード作成をひとまとまりとして適用する必要がある場合は、1つの一括プレビューにまとめてください。サーバーは、このフェイルクローズの不変条件を緩和しません。

タイムアウト後に変更リクエストを再試行することはありません。operations_verify と直接の読み戻しによって実際の状態が確認されるまでは、結果は committed_unverified、または項目ごとの unknown となります。

レコメンデーションの適用操作では、明示的な maximumAmount が必要です。レコメンデーションの通貨は広告アカウントと一致している必要があります。提案額は上限以内でなければならず、適用前にレコメンデーションとプロモーション対象のキャンペーンを再読み込みします。

取り消し不可能な削除には、さらに5つのゲートがあります。--allow-deletes、プロファイルの allowDeletes: true、セッション限定の APPLE_ADS_ALLOW_DELETES=true、オブジェクト名またはキーワードテキストの完全一致、専用の削除レシートです。キャンペーンと親オブジェクトは PAUSED でなければなりません。カスケードインベントリには上限があり、ハッシュ化されます。クリエイティブを参照する広告が存在してはならず、共有予算には割り当てがあってはなりません。結果が不明確な場合でも、DELETE は再試行されません。

リリースの検証

v0.3.8 のリリースには、完全な互換性テストスイート、MCP stdio コントラクトテスト、ユニットテストと HTTP テスト、レースディテクター、静的解析、脆弱性スキャンとシークレットスキャン、配布物の検証が必要です。クロスプラットフォーム CI は macOS、Linux、Windows で実行されます。

このリリースでは CI で合成的な受け入れテストを行います。Apple Ads API v1 のライブ環境での実行時確認は、別途オーナーが管理するゲートです。2026-08-31 に、v0.3.6 の P2 読み取り専用マトリックスと、個別に承認された PAUSED 状態のターゲティングキーワード一括フィクスチャ（項目数 2 および 28）が Apple Ads API v1 に対して合格しました。どちらの集約レシートも適用され、返されたすべてのキーワード ID が直接検証されました。書き込み受け入れテストの間、キャンペーンと広告グループは常に PAUSED のままでした。

以前の v0.3.x のライブ受け入れテストでは、読み取り専用の最適化ベースラインとプラン、PAUSED フィクスチャの作成と読み戻し、予算／入札額／戦略の更新、一時停止／再開、レシートの差分チェック、項目の検証、使い捨てのキャンペーン、広告グループ、キーワード、除外キーワードの削除を確認しました。保持されているすべてのフィクスチャは PAUSED の状態で、消費額はゼロでした。

アカウントに依存する経路には、明示的なエビデンス境界があります。

• 有効な最適化プランの適用と MAX_CONVERSIONS の変更は、このリリースでは自動テストで検証されます。オプティマイザーの推奨には既存の履歴の最低要件が必要です。明示的にユーザーが要求したプレビューでは、統計的な準備状況が確立されていないことを警告で示しつつ、コントラクト検証と書き込みゲートを維持します。
• 共有予算の作成／更新／割り当て／削除は、ライブ受け入れテスト用アカウントが PAYG を使用しているため、コントラクトテストと HTTP テストで検証されます。Apple は LOC を必須としています。
• デフォルトの Product Page 広告およびクリエイティブの削除は、Apple がこれらのリソースの個別削除を許可していないため、not_eligible と確認されています。

これらの境界によって、デフォルトの安全性モデルが弱まることはありません。未対応の操作やエビデンスが不十分な操作はフェイルクローズし、成功を示す空のレスポンスを返すことはありません。

インストール

プラットフォーム	Homebrew	GitHub アーカイブ	OCI イメージ
macOS arm64 / amd64	対応	.tar.gz	Linux コンテナのみ
Linux arm64 / amd64	対応	.tar.gz	対応
Windows arm64 / amd64	非対応	.zip	Linux コンテナのみ

Homebrew

公式 tap では、チェックサムが固定されたリリースバイナリをインストールします。

brew install zelentsov-dev/tap/apple-ads-mcp

以降のリリースにアップグレードするには、次を実行します。

brew update
brew upgrade apple-ads-mcp

GitHub リリース

お使いのプラットフォーム用のアーカイブをGitHub Releasesからダウンロードしてください。リリースには SHA-256 チェックサムと SPDX SBOM が含まれています。

Apple silicon の例：

curl -LO https://github.com/zelentsov-dev/apple-ads-mcp/releases/download/v0.3.8/apple-ads-mcp_darwin_arm64_0.3.8.tar.gz
curl -LO https://github.com/zelentsov-dev/apple-ads-mcp/releases/download/v0.3.8/checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
tar -xzf apple-ads-mcp_darwin_arm64_0.3.8.tar.gz
sudo install -m 0755 apple-ads-mcp /usr/local/bin/apple-ads-mcp

Windows ユーザーは checksums.txt を検証し、対応する ZIP を展開して、実行ファイルを絶対パスで登録してください。

OCI イメージ

docker pull ghcr.io/zelentsov-dev/apple-ads-mcp:0.3.8

このイメージはデフォルトで serve --stdio を実行します。accounts.json と、そこから参照される秘密鍵を読み取り専用でマウントしてください。

ソースからビルド

git clone https://github.com/zelentsov-dev/apple-ads-mcp.git
cd apple-ads-mcp
go build -trimpath -o ./apple-ads-mcp ./cmd/apple-ads-mcp

Go 1.26.10 以降が必要です。

Apple API の設定

Apple Ads API へのアクセスは、App Store Connect へのアクセスとは別です。Apple Ads のアカウント管理者が、適切なロールを持つ API ユーザーを追加する必要があります。キャンペーンの変更が必要になるまでは、API Account Read Only を使用してください。

ES256 キーペアをローカルで生成します。

umask 077
openssl ecparam -name prime256v1 -genkey -noout -out apple-ads-private-key.pem
openssl ec -in apple-ads-private-key.pem -pubout -out apple-ads-public-key.pem
chmod 600 apple-ads-private-key.pem

Apple Ads には公開鍵のみをアップロードしてください。秘密鍵をエージェントとの会話、issue、ログ、リポジトリに貼り付けないでください。Apple による鍵の登録後、Apple Ads UI に表示されるクライアント ID、チーム ID、キー ID を記録してください。

設定

対話形式でプロファイルを作成します：

apple-ads-mcp config init

デフォルトの設定パスは ~/.config/apple-ads-mcp/accounts.json です：

{
  "profiles": [
    {
      "name": "production-read-only",
      "clientId": "SEARCHADS.example-client-id",
      "teamId": "SEARCHADS.example-team-id",
      "keyId": "EXAMPLEKEY",
      "privateKeyPath": "/absolute/path/to/apple-ads-private-key.pem",
      "defaultAdAccountId": "123456789",
      "allowWrites": false,
      "allowDeletes": false
    }
  ]
}

POSIX システムでは、設定ファイルと秘密鍵のアクセス権を所有者のみに制限する必要があります：

chmod 600 ~/.config/apple-ads-mcp/accounts.json /absolute/path/to/apple-ads-private-key.pem

認証を検証し、アクセス可能な広告アカウントを検出します：

apple-ads-mcp auth doctor --profile production-read-only
apple-ads-mcp accounts discover --profile production-read-only

設定の優先順位は、--config、APPLE_ADS_MCP_CONFIG、デフォルトのファイル、単一プロファイル用の APPLE_ADS_* 環境変数の順です。単一プロファイルでサポートされる環境変数は、APPLE_ADS_PROFILE、APPLE_ADS_CLIENT_ID、APPLE_ADS_TEAM_ID、APPLE_ADS_KEY_ID、APPLE_ADS_PRIVATE_KEY_PATH、APPLE_ADS_AD_ACCOUNT_ID、APPLE_ADS_ALLOW_WRITES、APPLE_ADS_ALLOW_DELETES です。ファイルで設定されたプロファイルの場合、環境変数によって書き込みや削除の権限が暗黙に付与されることはありません。

MCP クライアントを接続する

サーバーは stdio を使用し、MCP JSON-RPC のみを stdout に書き込みます：

apple-ads-mcp serve --stdio

CLI を備えたクライアントでは、絶対パスのバイナリを使用してください。

Codex のグローバル設定：

codex mcp add apple-ads -- "$(brew --prefix)/bin/apple-ads-mcp" serve --stdio
codex mcp list

Codex Desktop、Codex CLI、IDE 拡張機能は同じホスト設定を共有します。サーバーを追加した後、起動中のクライアントを再起動し、新しい会話を開始してください。

Claude Code のユーザー設定：

claude mcp add --scope user apple-ads -- "$(brew --prefix)/bin/apple-ads-mcp" serve --stdio
claude mcp get apple-ads

Claude のプロジェクト設定では、リポジトリの .mcp.json を使用できますが、ユーザーが承認するまで、各ワークスペース／サーバーが保留中のままになる場合があります。承認後、/mcp から再接続するか、Claude Code を再起動してください。

登録コマンドがないクライアント向けの汎用 MCP 設定：

{
  "mcpServers": {
    "apple-ads": {
      "command": "apple-ads-mcp",
      "args": ["serve", "--stdio"]
    }
  }
}

クライアントが Homebrew またはシェルの PATH を引き継がない場合は、apple-ads-mcp を実行ファイルの絶対パスに置き換えてください。Apple silicon でのデフォルトの Homebrew パスは /opt/homebrew/bin/apple-ads-mcp です。Intel macOS では通常、/usr/local/bin/apple-ads-mcp です。

プラグインとスキルのバンドル

リリースアーカイブには .codex-plugin/plugin.json、.mcp.json、apple-ads-operator スキルが含まれています。これらのファイルは、対応するプラグインローダー向けにサーバーと安全な運用ワークフローを記述したものですが、実行ファイルのインストール、MCP サーバーの登録、Apple Ads へのアクセス権の付与を単独で行うものではありません。このリポジトリは現在、公開 Codex プラグインマーケットプレイスでは配布されていません。サポート対象の公開セットアップ手順は、Homebrew とクライアントへの登録です。

接続を確認する

クライアントを再起動した後、apple-ads が有効または接続済みであることを確認し、server_info の呼び出しを指示してください。ローカルの認証情報を準備した後、明示したプロファイルとアカウントを使って auth_check、ad_accounts_list、account_health を実行してください。

セットアップの検証はすべて読み取り専用で行う必要があります。インストールや認証のトラブルシューティング中に、--allow-writes、--allow-deletes、allowWrites、allowDeletes を追加しないでください。

トラブルシューティング

• 実行ファイルが見つからない場合： クライアント設定では、コマンド名のみを指定する代わりに "$(brew --prefix)/bin/apple-ads-mcp" を使用してください。
• サーバーがすでに存在する場合： そのクライアントに登録されている既存の apple-ads エントリのみを削除し、絶対パスを指定して再度追加してください。
• Claude で承認待ちと表示される場合： プロジェクトの MCP サーバーを承認し、/mcp から再接続して、新しい会話を開始してください。
• 起動中のクライアントにツールが表示されない場合： MCP 設定を変更した後、デスクトップアプリ、CLI セッション、または IDE 拡張機能を完全に再起動してください。
• 認証に失敗する場合： ローカルで apple-ads-mcp auth doctor --profile <profile> を実行し、ファイルのアクセス権と、秘密情報ではない識別子を確認してください。秘密鍵をチャットに貼り付けないでください。
• Homebrew がダウンロードしたローカルの Formula を拒否する場合： 信頼できる Tap から brew install zelentsov-dev/tap/apple-ads-mcp を実行してインストールしてください。

エージェント主導のセットアップ

エージェントがインストールの診断や実行を行うのは、ユーザーの承認がある場合に限ります。バイナリを確認し、絶対パスを使用して、対象のクライアントスコープに登録し、クライアントを再起動して、読み取り専用のヘルスチェックが済んだ時点で停止する必要があります。秘密鍵の内容を要求したり、変更を可能にするゲートを暗黙に有効にしたりしてはなりません。

1 回のセッションで書き込みを有効にする

永続プロファイルは読み取り専用のままにしてください。明示的に許可されたオペレーターセッションでは、両方のローカルゲートを有効にします。

APPLE_ADS_PROFILE=production-read-only \
APPLE_ADS_ALLOW_WRITES=true \
apple-ads-mcp serve --stdio --allow-writes

これだけでは何も変更されません。すべての変更には、引き続き明示的な profile、adAccountId、専用のプレビュー、レシートの適用、検証が必要です。

オンデマンド最適化を設定する

名前付きのローカルポリシーを作成します。

apple-ads-mcp optimization policy init
apple-ads-mcp optimization policy validate --name mature-product-balanced
apple-ads-mcp optimization doctor --policy mature-product-balanced

ポリシーは、モード 0600 で ~/.config/apple-ads-mcp/optimization-policies.json に保存されます。各ポリシーでは、1 つのプロファイル、1 つの広告アカウント、1 つのプロモート対象アプリ、および最大 20 個のキャンペーン ID を指定します。learning モードではビジネスターゲットは不要で、エビデンスのみを返します。active モードでは targetInstallCPA、合計およびキャンペーンごとの 1 日あたりの予算上限、さらに予算、入札額、戦略、一時停止、再開、再テストに関する明示的な権限が必要です。入札額の変更を許可するポリシーでは、アカウント通貨で正の値を指定した maxBid も設定する必要があります。1 日あたりの予算上限が入札額の上限として再利用されることはありません。

balanced プリセットでは、昨日で終わる連続した完了済み UTC 日付がちょうど 28 日分必要です。直近の 7 日間とその前の 7 日間を比較し、72 時間のクールダウンを適用し、通常は 10% の変更を提案します。また、1 回の実行で 20% を超えることはありません。レポートエビデンスが欠落、重複、未来の日付、不正な形式、または上限超過の場合は、安全側に処理を停止します。Search Results Search Match インベントリについて、14 日間の平均タップインストール数が 1 日あたり 5 件以上の場合に限り、MAX_CONVERSIONS を提案できます。削除を提案することはありません。

一般的なエージェントのフロー：

1. 読み取り専用サーバーで optimization_baseline と optimization_plan を呼び出します。
2. Apple の推奨事項と計算されたアクションを個別に確認します。
3. 書き込みが許可されたセッションを開始し、optimization_plan_preview を呼び出します。
4. OperationImpact を確認し、同じレシートを 1 回適用してから、operations_verify を呼び出します。
5. ~/.local/share/apple-ads-mcp/optimization/ に保存された、範囲が限定されたローカル履歴を確認します。

Apple への最初の書き込みの直前に、サーバーはプロセス間ファイルロックの下で、レシートハッシュに紐付けられた applying インテントと、サニタイズ済みの型付き検証レシピを永続的に保存します。POSIX ではコミット時に格納ディレクトリを同期します。Windows では write-through を使用した置換セマンティクスを使用します。結果が不明な場合、検証が確定できない場合、または履歴の更新が中断された場合は、operations_verify によって影響を受けたすべての項目が確実に照合されるまで、後続の最適化プランはブロックされます。復旧処理はプロセスの再起動後や通常のメモリ内レシートの有効期限切れ後も継続されますが、オペレーターが元の不透明なレシートを保持している必要があります。照合結果が matched または matched_after のアクションは、元のインテント／適用時刻からクールダウンを開始します。matched_before の場合は開始しません。検証済みの最適化処理による一時停止が、同じ Apple の modificationTime のままである場合に限り、キャンペーンは自動再開できます。その後に手動で変更が加えられると、この権限は取り消されます。レシート、認証情報、生の Apple エンベロープ、請求先連絡先は最適化履歴に保存されません。

共有予算とライフサイクル操作

共有予算の変更が利用できるのは、Apple がアカウントの支払いモデルを LOC として報告した場合のみです。作成および更新操作では、予算は明示的に選択した広告アカウントのみに紐付けられます。キャンペーン割り当てツールは、既存の無関係な割り当てを維持します。また、アカウントをまたぐ共有予算の操作は安全側に失敗します。非公開の請求データはローカルで初期化してください。

apple-ads-mcp billing profile init

~/.config/apple-ads-mcp/billing-profiles.json の権限は 0600 にしてください。MCP 入力に含めるのは、ローカルの billingProfile 名だけです。購入者名やメールアドレスは、ツールの出力、ログ、履歴、領収書のプレビューには返されません。PAYG アカウントでは、書き込みを試みずに not_eligible が返されます。

明示的に許可された破壊的なメンテナンスセッションでは、次のようにします。

APPLE_ADS_ALLOW_WRITES=true \
APPLE_ADS_ALLOW_DELETES=true \
apple-ads-mcp serve --stdio --allow-writes --allow-deletes

選択したファイルベースのプロファイルには、あらかじめ allowDeletes: true が設定されている必要があります。allowWrites は、APPLE_ADS_ALLOW_WRITES=true を指定して現在のプロセスに限り有効にできます。サーバーとセッションの削除ゲートは、それぞれ独立しています。専用の *_delete_preview を使用し、カスケードによる影響全体と期待される正確なテキストを比較してから、一度だけ適用し、deleted: true を確認してください。最適化計画の一環としてライフサイクル操作を使用しないでください。

運用上の制限

• Apple には公開 Ads API サンドボックスがありません。実環境での変更受け入れテストは手動で明示的に有効化し、名前から判別できる PAUSED フィクスチャを使用します。自動 CI では決して実行しません。
• 対応状況、提案、人気度、レコメンデーション、レポート、クリエイティブのサポートは、アカウントやストアフロントによって異なります。
• コールド状態のアカウントには、目標 CPA や日予算のレコメンデーションがない場合があります。
• キャンペーン名とオブジェクト名は Apple によって検証されます。Web UI と API で、異なる句読点が受け付けられる場合があります。
• Apple はキャンペーン名に縦棒文字（|）を使用することを拒否します。代わりに、ハイフンを使った読みやすい名前を使用してください。広告グループの作成には、広告アカウントのタイムゾーンにおける ISO 8601 形式の startTime が必要です。
• レポートには遅延が発生することがあり、配信が始まるまで空のままの場合があります。
• Apple は Default Product Page を使用する広告の個別削除を拒否します（CAN_NOT_DELETE_DPP_CREATIVE_AD）。サーバーはプレビュー時に not_eligible を返します。ライフサイクル削除は、破棄可能な Custom Product Page の広告とクリエイティブにのみ使用してください。
• トライアルとサブスクリプションのアトリビューションは、お使いのアトリビューションスタックで扱います。Apple Ads Platform API だけでは、キーワードからトライアルへのアトリビューションを証明できません。

既知の Apple API レスポンス

2026-08-25 時点で、このサーバーが使用する文書化済みの v1 リクエスト形式では、実環境での受け入れテスト中に、上流で次の 2 つの再現性のある挙動が確認されています。

• phrase_suggestions と category_suggestions は、同じ所有アプリで keyword_suggestions と target_cpa_suggestions が正常に動作する場合でも、SUGGESTION クエリに対して Apple の HTTP 500 を返すことがあります。
• impression_share は、コールド状態または完全に一時停止中のアカウントで、Apple の HTTP 400 を返すことがあります。アカウント所有者が管理する受け入れテスト用アカウントでは、コードも診断情報も提示されませんでした。公開されている再現例でも、コード INVALID_VALUE が報告されています。直近の配信がないことが関係している可能性はありますが、Apple が確認した必須条件や回避策ではありません。

サーバーは、これらを制限付きの構造化 Apple エラーとして返し、空の結果や成功結果には変換しません。4xx では、安全な Apple のコード、メッセージ、詳細フィールドを保持します。リクエスト本文、認証情報、任意のフィールド、5xx の本文は返しません。リクエスト形式は、現在の Apple Ads Platform API および公式の Apple Java クライアントに準拠しています。同様の公開 v1 再現例は、App Store Connect CLI PR #2057 と PR #2020 に記録されています。Apple が API を変更した後、またはアカウントに十分な配信履歴ができた後に、再確認してください。

互換性

v0.3では、v0.2.1のすべてのツール名とスキーマを維持したうえで、最適化、共有予算の変更、入札戦略、ライフサイクルの各ツールを追加しています。v0.3.1では、入札権限が有効な場合に必須となるmaxBidと、フェイルクローズの照合ルールを追加しています。詳しくは、v0.3.1の移行ノートをご覧ください。v0.3.2で変更されたのは、配布とオンボーディングのみです。v0.3.3ではリリース検証を正確なtap数式のパスに切り替え、v0.3.4ではHomebrew 6向けに数式スコープの信頼を追加し、v0.3.5ではアーカイブ名の末尾にセマンティックバージョンを配置してHomebrewのバージョン検出を明確化しています。v0.3.6では既存のツール名と互換性のある従来の入力を維持しながら、型付きエイリアス、クエリーのショートカット、診断機能、より厳格な必須スコープを追加しています。詳しくは、v0.3.6のノートをご覧ください。v0.3.7では、ヘッダーに応じたリクエストのペーシング、コンテキストに応じた入札の検証、レポートのグループ化の修正、プレビュー警告の永続化を追加しています。詳しくは、v0.3.7のノートをご覧ください。v0.3.8では、キャンペーンと広告グループのbidStrategy.bid要件を分離し、キャンペーンをMANUAL_CPTに切り替える際に"bid": nullでTargetCpaをクリアし、operations_verifyで小数の金額文字列を正規化します。詳しくは、v0.3.8のノートをご覧ください。古いクライアントをお使いの場合は、v0.3のノートとv0.2のノートもご確認ください。

公開ツールスキーマは、v1.0より前の段階では固定されていません。APIファミリーのスコープと操作のステータスは、機械可読な操作マトリックスで管理されています。公式JavaクライアントのベースラインとApp Storeエンドポイントの一覧は、upstream-baseline.jsonで管理されています。

開発

gofmt -w cmd internal
go test ./...
go test -race ./...
go vet ./...
go run honnef.co/go/tools/cmd/[email protected] -checks 'all,-ST1000,-ST1005' ./...
go run golang.org/x/vuln/cmd/[email protected] ./...
go run github.com/zricethezav/gitleaks/[email protected] dir --no-banner --redact .
go run github.com/goreleaser/goreleaser/[email protected] check
go run github.com/rhysd/actionlint/cmd/[email protected]
npx --yes [email protected] '**/*.md'
python3 scripts/validate_distribution.py
python3 scripts/audit_upstream.py

CONTRIBUTING.md、SECURITY.md、ロードマップをご覧ください。

ライセンス

MIT