ads-manager

Adapty CLI を使った Apple Search Ads

読み取りと automations run --dry-run には費用がかかりません。それ以外の asa コマンドは数秒以内に Apple にアクセスし、実際に費用が発生します。また、作成したものは削除も取り消しもできません。ただし、asa segments は例外です。オーディエンスを Adapty に書き込み、Apple には一切触れません（ワークフロー 13）。

コマンドを実行する前に、ワークフローで指定されたリファレンスを開いてください。

• references/asa-management.md — キャンペーン、広告グループ、広告、キーワードとキーワードの推奨、除外キーワード、プロダクトページ、クリエイティブ、セグメント、自動化、変更履歴。
• references/asa-metrics.md — metrics、metrics overview、search-terms list、competitors summary。

話し方

ユーザーが読むすべての行で、次のようにします。

• 自分がすることには「私」、ユーザーがすることには「あなた」を使います。 数値や変更内容など、答えから始め、次の一手で締めくくります。前置きや依頼内容の言い直しはしません。
• 段落ごとの太字は最大 1 か所にします。 表の行では太字は不要です。
• 生の値を示すのは、ユーザーが入力するか、ほかで目にする場合だけです — Apple Ads で表示されるキャンペーン名、広告グループ名、キーワード名、通貨単位の金額、ユーザーが実行するコマンドなどです。エンティティ UUID はコマンド内でのみ使用します。
• 変更の前に、何がどう変わり、何が変わらないかを正確に示します — エンティティと変更前後の値を示してから、一度だけ確認を求めます。
• クリック可能な完全なリンクを使います。 ユーザーの言語で返答し、Apple Ads の名前は Apple Ads での表示どおりに記載します。

CLI

最初の asa 呼び出しの前に $ADAPTY を一度解決し、実行するすべてのコマンドでそれを使ってください。 グローバルの adapty は古いことがよくあります。asa トピックは 0.4.0 で追加されましたが、ad-groups create --automated と 5 つの --invoice-* フラグは 0.8.2 で、metrics のスコープフラグと automations のアクションフラグは 0.8.3 で、keywords recommend は 0.8.7 で追加されました。そのため、このスキルの最低バージョンは 0.8.7 としてください。asa segments は 0.9.3 より後に追加されており、最低バージョンの唯一の例外です。全員の最低バージョンを引き上げるのではなく、ワークフロー 13 の前に $ADAPTY asa segments --help で確認してください。古いインストールでは unknown command または未知のフラグのエラーが返ります。この場合、CLI が古いのではなく、コマンド自体が存在しないように見えてしまいます。

adapty --version                                   # >= 0.8.7 ?  ADAPTY="adapty", done
npm i -g adapty@latest >/dev/null 2>&1 \
  && ADAPTY="adapty" \
  || ADAPTY="npx --yes adapty@latest"              # fallback: prefix not writable

一度インストールし、呼び出しのたびに npx でラップしないでください。 ラッパーはインストール済みの場合の 0.07 秒に対し、呼び出しごとに約 1 秒かかります。最適化の処理では数十回の呼び出しを行います。グローバルのプレフィックスに書き込めない場合は npx の形式でも動作します。その場合、--yes は省略できません。指定しないと npx がインストールの許可を求めて停止し、ヘッドレス実行では誰も応答できません。

ユーザーにコマンドを書いて示す場合は、adapty をそのまま記述してください。 ユーザーのシェルには $ADAPTY がありません。以下の --yes と同様に、こちらが実行するコマンドには変数を、ユーザーが実行するコマンドにはコマンド名を使います。

macOS のデフォルトである zsh では、複数語からなる $ADAPTY は語に分割されないため、 command not found: npx --yes adapty@latest というエラーになります。同じシェルで setopt shwordsplit を一度実行するか、npx --yes adapty@latest を省略せずに記述してください。このエラーはシェルの問題であり、CLI やコマンドが見つからないことを示すものではありません。

--help に表示された場合に限り、asa コマンドを利用不可と判断してください。どこかで確認したバージョン番号だけを根拠にしてはいけません。このスキルは @latest を基準にしていますが、コマンドがベータ版にのみ存在し、リリース版には含まれていないことがあります。そのため、ルートが未リリースだと判断する前に、npx --yes adapty@beta asa <topic> --help を一度試してください。

アカウント情報

• $ADAPTY asa whoami — 会社、アクセスの付与方法、Apple 接続状態、limits に表示される会社の実効リクエスト予算を確認できます。最初に実行してください。access_source: trial はトライアル終了まではサブスクリプションと同様に機能し、終了後はすべてのデータコマンドが 402 を返します。
• $ADAPTY asa connect [--no-wait] — Apple の認証リンクを表示して待機します。--no-wait を指定すると、すぐに戻ります。
• $ADAPTY asa orgs list — ASA の組織を一覧表示します。各行には、相互に置き換えられない 2 つの識別子があります。internal_id は UUID で、campaigns create では --org に、スコープフィルターを受け付けるリストでは --campaign-group に指定します。org_id は Apple の数値 ID で、どちらのオプションも受け付けません。--org は campaigns create にのみ存在し、これを受け付けるリストはありません。各行の payment_model（LOC／PAYG）によって、その組織のキャンペーンで「Invoicing Options」が必要かどうかが決まります。
• $ADAPTY asa apps list — Apple Search Ads でプロモーションされているアプリを一覧表示します。各行には、相互に置き換えられない 2 つの識別子があります。Apple の数値 adam-id（--adam-id）と、ASA アプリの UUID（--app）です。
• この 2 つのコマンドと automations list では、ページネーションのみ指定できます。スコープフィルターはありません。
• スコープはトークンの会社です。スコープの選択に --app を使う asa コマンドはありません。--app はリストのフィルターにのみ使用します。例外は asa segments です。ここでの --app は、セグメントの書き込み先となる Adapty アプリを指定するもので、$ADAPTY apps list から取得します。asa apps list が表示する UUID は指定しません。
• 402 ads_manager_subscription_required — Ads Manager のサブスクリプションがありません。404 — 対象が自分のものではないか、存在しません。
• 読み取り時の機械可読な出力には --json を指定します。書き込みコマンドで --json を指定すると拒否され、終了コード 2 で終了します。すべてのリストで --page（デフォルト 1）、--page-size（デフォルト 100、最大 1000）を指定できます。ページネーションループより、大きなページを 1 つ指定する方法をおすすめします。
• ADAPTY_ASA_API_URL は ADAPTY_API_URL とは独立して、ASA のベース URL を上書きします。

2 つのテンプレート

すべてのスロットを埋めてください。読み取りから埋められないスロットは、省略せずに質問してください。

$ADAPTY asa <topic> list --<filter-from-that-list-s-matrix-row> <id-from-a-previous-list> [--status <enum>]
$ADAPTY asa <topic> <create|update|add> [<id>] <field flags> --idempotency-key <key>

スコープフィルターは必須のスロットであり、その情報源はマトリックスだけです — references/asa-management.md の ## Scope filters にある、そのリスト自身の行を読み、そこからスロットを埋めてください。create コマンドで見かけたフラグや、別のリストにあるフラグは、今回のフィルターではありません。--org は campaigns create に属し、スコープフィルターを受け取るリストでの同等の指定は --campaign-group です。セッションで最初に実行するリストでも、5 つ目に実行するリストでも必須です。フィルターはサーバーが順位付けするクエリを変える一方、ページサイズは誤った結果をどれだけ見るかを変えるだけだからです。

ユーザーが別々に指定した 2 つのエンティティは、別々に検索します。 「最も成績の良いキャンペーン」と「ブランドの広告グループ」は、ユーザーがそう述べていない限り、親と子の関係ではありません。それぞれを名前で解決し（ad-groups list --search <name>）、一方の解決で得た ID を使って、もう一方の検索範囲を指定してはいけません。そのフィルターは、ユーザーが述べていない関係を前提とするものであり、後続の書き込みはもっともらしく見える誤った場所に、エラーもなく適用されます。一致する結果が複数ある場合は、選ぶのではなく質問してください。

--idempotency-key は必須のスロットであり、連鎖する書き込みごとに、また書き込み内のバッチごとに異なるキーが必要です。CLI の自動キーがカバーするのは、1 回の実行内でのネットワークリトライです。曖昧な結果のあとにユーザーが create の手順を再実行するケースはカバーしません。新しい実行では新しいキーが必要となり、2 つ目のキャンペーンが作成されます。詳細は 422 cli_idempotency_key_reuse と 409 cli_idempotency_in_progress を含め、references/asa-management.md の ## Writes and idempotency を参照してください。asa segments create|update はキーを受け取りません。その場合、このスロットは読み取りで埋めます。毎回、create の直前に asa segments list --campaign|--ad-group <id> を実行してください。

--yes はテンプレートに含まれていません。コマンドを誰が実行するかによって、付けるべきかどうかが決まるためです。

• ユーザーが実行する場合 — ユーザーが実行できるよう、コマンドを記述しています。--yes は省略してください。ユーザーのターミナルでは、CLI がリクエスト本文全体を表示して待機します。そのプロンプトがユーザーの確認であり、それをなくす唯一のフラグが --yes です。周囲の文章ではその確認を復元できないため、警告、STOP ブロック、明示した前提のいずれも、フラグを付けないことの代わりにはなりません。
• 自分が実行する場合 — このセッションで実行します。まず質問して明示的な同意を得てから、実行するコマンドに --yes を追加してください。

metrics、metrics overview、search-terms list、competitors summary は、企業ごとに 1 つの同時実行プール（whoami の limits.metrics_inflight_limit）を共有します。429 cli_analytics_busy はプールが満杯、429 cli_rate_limit_exceeded はウィンドウ内の上限に到達、429 cli_cooldown_active は段階的に延長される 5m → 30m → 3h のロックアウトを意味します。503 cli_upstream_unavailable は Adapty のサービスが停止していることを示し、コマンドが誤っているという意味ではありません。references/asa-metrics.md の ## The analytics pool を参照してください。

1つの質問に、1回の呼び出し

サーバーが集計し、サーバーが順位付けします。実行する前に、質問に答える1つの呼び出しを決めてください。メトリクスの利用上限は会社ごとに設定されています。whoami から limits.metrics_limit_per_minute を読み取ってください。デフォルトは1分あたり15回、10秒あたり最大5回です（references/asa-metrics.md）。

• 合計：metrics overview を1回呼び出します。
• 上位または下位N件：metrics --metric <m> --order-by <metric> --page-size N を1回呼び出します。最下位を取得するには --order asc を指定します。
• 推移または期間比較：1回呼び出します。期間ごとの系列に両方の期間がすでに含まれています。
• エンティティ数のカウント：メトリクスの呼び出しは不要です。--page-size 1 を指定した任意のリストで meta.pagination.count が返されます。
• metrics では --metric が必須で、指定したすべてのメトリクスはエンティティ全体に対して計算されます。読み取る列を指定してください。（metrics overview では引き続き任意です。）
• metrics の呼び出しは --app、--campaign、または --ad-group でスコープを絞り込んでください。UUIDは複数回指定でき、呼び出しを軽くする唯一の方法です。コストはページサイズではなく集計対象のエンティティ数に応じて決まるためです。subscribers、paid_subscribers、arppu、arpas は、--campaign または --ad-group でスコープを指定しないと拒否されます。metrics overview はスコープフラグを受け付けません。エンティティレベルと期間で絞り込み、スコープを指定したリストから取得したIDと行を照合してください。
• バケットに対して期間が広すぎる場合は、分割ではなく粒度を粗くして解決してください。また、日単位の粒度では2つのコマンドの上限が異なります。metrics：日単位でグループ化する場合は28日、期間でグループ化しない場合は90日、週単位では180日、月単位以上では365日です。metrics overview：日単位では90日で、それ以降は同じです。1年分のデータは --group-by month（または --period-unit month）を指定した1回の呼び出しで取得してください。90日ずつ4回呼び出してはいけません。
• metrics の1ページあたりの内訳行数（エンティティ × 国 × 期間）は、limits.max_breakdown_rows_per_page（デフォルトは5000）で上限が定められており、これを超えると呼び出しは 422 cli_response_too_large で失敗します。粒度を粗くするか、絞り込むか、スコープを指定してください。小さいページに分けて繰り返し呼び出してはいけません。日単位の粒度で拒否された場合、収まる page[size] が示されるので、その数を使い、自分で計算しないでください。
• **--by-days の期間が meta.max_valid_day を超えている場合、その日付にはまだ到達していません。**直近の実績値が繰り返し表示されます。これを横ばいと報告してはいけません。また、すべての行が到達している期間の範囲でのみ比較してください。
• **金額の通貨は米ドルではなく、キャンペーングループの通貨です。**金額を示したり比較したりする前に、orgs list から通貨を読み取ってください。

クライアント側でページの値を合計してはいけません。期間ごとに呼び出してはいけません。また、ユーザーが求めていない比較を追加してはいけません。代わりに、回答の中で提案してください。

禁止事項

• 優劣を自分で決めてはいけません。「最もパフォーマンスが高い」「成果が悪い」「ROAS がひどい」といった表現は、クエリ結果ではなくビジネス上の定義です。指標と対象期間を明示し、その定義についてユーザーの同意を得てから実行してください。
• チャットで変更内容を先に明示せずに書き込みを行ってはいけません — 対象のキャンペーン、予算、キーワードの数を明示してください。
• 1 回の keywords add または negative-keywords add 呼び出しに、15 個を超えるキーワードを含めてはいけません。上限は 100 個ですが、実際には 15 個を目安にしてください。
• 429 でループしてはいけません。CLI は正確な Retry-After の時間だけすでに待機し、1 回再試行しています。そのため、こちらに届いた 429 は、利用枠が本当に尽きたことを意味します。呼び出し回数を減らすか、ユーザーに再試行のタイミングを伝えてください。
• 指標名を推測したり、試しに指定したりしてはいけません。使用できる名称は references/asa-metrics.md に記載されています。誤った名称を指定すると、有効な名称がすべて一覧表示されるため、タイプミスは呼び出しを 1 回無駄にします。動作する名称を確かめるために呼び出しを使うのは失敗です。コホート指標は展開後の名称で並べ替えてください。--order-by roas ではなく、--order-by gross_roas を指定します。
• ID、adam-id、予算、入札額を捏造してはいけません。対応する一覧から読み取るか、ユーザーに確認してください。
• ユーザーが実行するコマンドに --yes を指定してはいけません。ユーザーが確認するはずのプレビューが表示されなくなります。--yes は、明示的な同意を得た後に自分で実行するコマンドにのみ指定してください。
• Max Conversions キャンペーンには、必ず自動広告グループを設定してください。また、LOC 組織でキャンペーンを開始する際は、必ず 5 つの --invoice-* フラグを指定してください。どちらもエラーなく作成されるものの、その後配信されません。誰かが serving_status を確認するまでは、正常に開始できたように見えてしまいます。
• 変換したテンプレートを送信する前に、必ず --preview を確認してください。また、一括操作がタイムアウトしたからといって再送信してはいけません。--timeout が終了するのはポーリングであり、操作自体ではありません。再送信すると同じ構成が 2 回作成されます。また、asa トピックにはどちらの複製も削除する方法がありません。
• 削除処理を書いてはいけません。asa トピックに削除機能はなく、元に戻す方法もありません。停止する方法は --status PAUSED のみです。
• 一覧を確認する前にセグメントを作成してはいけません。asa segments create には冪等性キーがないため、結果が不明瞭な状態で再実行すると、同じユーザーに配信する [ASA] Campaign: <name> が 2 つ目に作成されます。その結果、どちらをカウントするかについてプレースメント間で不一致が生じます。
• ユーザーから依頼されていない [ASA] セグメントの名前を変更してはいけません。この接頭辞によって、ダッシュボードと asa segments list でセグメントを見つけられます。接頭辞を外すと、どちらからも見つからなくなります。

正当化の例

エージェントが自分に言い聞かせたこと	実際のところ
「40 個のキーワードは CLI の 1 回あたり 100 個というバッチ上限未満なので、ループではなく 1 回の呼び出しで済む。」	上限未満であることと、安全であることは同じではありません。40 個の項目を含む応答で 9 行が却下されると修正作業になりますが、15 個の呼び出しなら再実行で済みます。
「デフォルトの『最もパフォーマンスが高い』の定義には直近の期間の ROAS を使い、ステップ 5 の前にユーザーに確認して必要なら変更してもらうつもりですが、答えを出すコマンドはこちらです。」	コマンドを渡しても、先に得る必要があると言った承認は得られません。定義の確認が必要なら、定義の段階で止めてください。

危険信号 — 停止してください

• スコープフィルターのない list。最初のものや、「ちらっと見るだけ」のものも含みます
• orgs list、apps list、automations list にスコープフィルターを付けること
• そのリスト自身の行をマトリックスで確認していないフィルター。--org のような作成フラグや、別のリストのフィルターは該当しません
• ユーザーに渡すコマンドに --yes を付けること。ユーザーが読むはずだったプレビューが削除されます
• ユーザーが別々に指定したエンティティを解決して得た ID でスコープを絞った検索
• 依存関係のある作成が連なる中で、--idempotency-key が固定されていない作成
• 1 回の keywords add または negative-keywords add 呼び出しでキーワードが 15 個を超えること。この上限は bulk-create の構造には適用されません。代わりにプレビューで確認します
• プレビューを読まずに送信する bulk-create --from-file、または数値の org_id ではなく internal_id の UUID を指定した --org-id
• 「最適」「負けている」「ひどい」という独自の定義で対象を選んだ書き込み
• 同じ呼び出し内に対応する --by-days の期間がない --order-by-day
• asa apps list からコピーした asa segments の --app。これは Adapty 側ではなく Apple 側のアプリです
• 直前に同じエンティティに対する asa segments list を実行していない asa segments create
• 既存のすべての項目を渡し戻さずに、セグメントのオーディエンスを追加するプレースメントの update
• ルールを述べた後、3 つのコマンドを実行したところで、何も言わずに例外を適用すること

このスキル自体のベースラインではなく、CLI 側のセッションで確認された事項：

• overview の呼び出し 1 回または大きなページ 1 つではなく、合計を出すために --page 1..4 をループすること
• 有効なメトリクス名を調べるために呼び出しを 1 回使うこと
• ユーザーが求めていない期間比較を追加すること
• 推測した sleep の後に再試行し、Retry-After の値を使わずに 429 を再試行すること

これらはすべて、停止して、まず読み、確認する必要があることを意味します。

ワークフロー

1. 状況を把握します。 whoami → Apple が未接続なら connect → orgs list → apps list。 以下すべての前提条件です。→ references/asa-management.md、 ## Account and discovery。

2. パフォーマンスを報告します。 合計と傾向には最初の形式を使い、最良または最悪の N 件には 2 つ目の形式を使います。最悪のものには --order asc を指定します。どちらも日付が必須で、 metrics には --metric も必要です。指定しないと、コマンドは Apple に到達する前に終了します。 ID を指定できる場合は、--app、--campaign、または --ad-group で metrics のスコープを絞ります。 subscribers、paid_subscribers、arppu、arpas は、--campaign または --ad-group がないと拒否されます。 件数を数えるためのメトリクス呼び出しは不要です。--page-size 1 を指定したリストなら、どれでも meta.pagination.count を取得できます。--by-days は 1 回の呼び出しにつき最大 16 個の期間を指定でき、 --order-by-day に指定できるのは、その値のうち 1 つだけです。→ references/asa-metrics.md、## Cohort windows。

$ADAPTY asa metrics overview --entity <level> --date-from <YYYY-MM-DD> --date-to <YYYY-MM-DD> [--period-unit <bucket>]
$ADAPTY asa metrics --entity <ad|ad-group|campaign|keyword> --date-from <YYYY-MM-DD> --date-to <YYYY-MM-DD> --metric <metric> [--campaign <uuid>] --order-by <metric> --page-size <n>

3. キャンペーンを開始します。 まず orgs list から --org を、apps list から --adam-id を読み取ります。 その後、各作成コマンドでは、直前のコマンドが出力した ID を使います。順序もキーも省略できません。 起動ごとに <run> を 1 回生成し、2 回目の起動と重複しないようにします。キャンペーンを PAUSED で作成し、 構成を確認してから、ワークフロー 6 で有効にします。有効にするまでは何も費用が発生しません。 --match-type は自分で設定します。デフォルトは最も幅広く、最も高額なターゲティングである BROAD です。 ユーザーからキーワードリストが提供されていない場合は、まず次のコマンドで候補を 1 つ取得します。 keywords recommend --adam-id <adam-id> --type <brand|generic|competitor> — 同じ --adam-id を使います — そして追加する語句をユーザーに提示します。候補には入札額もマッチタイプも含まれないため、どちらも ユーザーが決める必要があります。→ references/asa-management.md、## Keywords および ## Writes and idempotency。

$ADAPTY asa campaigns create --org <id> --adam-id <adam-id> --name <name> --country <country-code> --daily-budget <amount> --status PAUSED --idempotency-key <run>-camp
$ADAPTY asa ad-groups create --campaign <id> --name <name> --default-bid <amount> --idempotency-key <run>-ag
$ADAPTY asa creatives list --app <app-uuid>   # → --creative-id; no creatives create exists
$ADAPTY asa ads create --ad-group <id> --creative-id <id> --name <name> --idempotency-key <run>-ad
$ADAPTY asa keywords add --ad-group <id> --text <keyword> --match-type <EXACT|BROAD> --idempotency-key <run>-kw-1   # ≤15 per call, fresh key per batch

orgs list の 2 つの情報によって、実行前にキャンペーン作成の内容が変わります。payment_model が LOC の場合、5 つの --invoice-* フラグが必須です。1 回の呼び出しで 5 つすべてを指定しないと、キャンペーンは作成されても配信されません。また、--bidding-strategy MAX_CONVERSIONS を指定すると、最初の 2 つの書き込みが 1 つの単位になります。このキャンペーンは、--automated を指定して作成した広告グループを持つまで配信されません。--automated では --default-bid も --start-time も指定しません。請求に必要な値はユーザーに確認し、決して推測しないでください。→ references/asa-management.md、### Max Conversions campaigns および ### Line of credit organizations。

4. キーワードを収集します。 search-terms list --ad-group <id> --date-from <YYYY-MM-DD> --date-to <YYYY-MM-DD> を読み取り（日付のデフォルトは今日なので、必ず指定します）、コンバージョンにつながった検索語句を keywords add --ad-group <id> で追加し、無駄な語句を negative-keywords add --ad-group <id> で除外します。1 回の呼び出しにつき 15 件までで、呼び出しごとに個別のキーを指定します。→ references/asa-metrics.md の ## The analytics pool および references/asa-management.md。

5. 最適化を実施します。 metrics --entity keyword --date-from <YYYY-MM-DD> --date-to <YYYY-MM-DD> --metric roas --metric spend --ad-group <id> --by-days 7 --by-days 90 --order-by gross_roas --order-by-day 90 を読み取ります。--order asc を指定すると、同じ呼び出しで勝者ではなく敗者を取得できます。また、ID を確認するために keywords list --ad-group <id> --status ACTIVE を読み取ります。書き込みを行う前に、必ずユーザーに基準値を確認してください。その後、勝者には keywords update <ids> --bid <amount>、敗者には keywords update <ids> --status PAUSED を実行し、支出を移すには campaigns update <id> --daily-budget <n> を実行します。それぞれに独自の --idempotency-key を指定します。予算と入札額は別々に確認してください。これらは別個の判断です。→ references/asa-metrics.md の ## Cohort windows および references/asa-management.md。

6. 一時停止または再開します。 キャンペーン、広告グループ、広告の場合： update <id> --status ENABLED|PAUSED --idempotency-key <key>。キーワードの場合： update <id> [<id>…] --status ACTIVE|PAUSED --idempotency-key <key>。キーワードの列挙値は他のすべてのエンティティと異なり、このインターフェースに DISABLED は存在しません。ID は、まず対象を絞った一覧から取得します。→ references/asa-management.md の ## Status。

7. カスタム商品ページから広告を作成します。 product-pages sync [--adam-id <adam-id>] --idempotency-key <key> を実行します。これは書き込み処理で、完了を待たずにキューに入れられます。続いて product-pages list --app <app-uuid> → creatives list --app <app-uuid> → ads create --ad-group <id> --creative-id <id> --name <name> --idempotency-key <key> を実行します。→ references/asa-management.md。

8. 配信されない広告や、開始されなかったキャンペーンを診断します。 ads get <id> を実行し、 serving_state_reasons を確認します。それで原因が分からない場合は、上位へたどり、ad-groups get <id> のステータス、次に campaigns get <id> のステータスと日予算を確認します。キャンペーンにも serving_status と serving_state_reasons があり、ここに表示される理由のうち 2 つには診断ではなく既知の修正方法があります。 AUTOMATED_KEYWORDS_REQUIRED_AD_GROUP_MISSING の場合は ad-groups create --automated が必要です。 MISSING_BO_OR_INVOICING_FIELDS の場合は campaigns update に 5 つの --invoice-* フラグを指定する必要があります。すべて読み取り処理です。 → references/asa-management.md。

9. ルールによる自動化。 automations create --file rule.json --idempotency-key <key> → automations run <id> --dry-run → automations runs <id> の順に実行して、実行される内容を確認します。その結果をユーザーが確認してから、automations update <id> --start を実行してください。入札額または予算に影響するルールは、必ずドライランしてください。add-as-keyword-to ルールでは、actions[0].params を手動で記述するのではなく、アクションフラグを指定してください。--target-ad-group、--match-type、--cpt-bid-type はすべて必須で、API にデフォルト値はありません。手書きのブロックでキーの位置を 1 つ間違えても 200 が返されますが、キーワードは何も追加されません。update では、アクションフラグを指定するとルールを読み直してアクション全体を書き込むため、その間にダッシュボードで行われた編集が上書きされます。事前にそのことを伝えてください。→ references/asa-management.md の ### The add-as-keyword action flags。 10. 競合他社を確認する。 competitors summary --app-ids <adam-id>,<adam-id> — Apple App Store ID を 1～5 個指定します。直近の完了月について、すべての国が対象です。期間や国を指定するフラグはありません。読み取り専用で、分析プールを共有するため、キャッシュが空の状態では時間がかかります。→ references/asa-metrics.md。

11. 複数のキャンペーンを一度に開始する。 構造全体（キャンペーン → 広告グループ → キーワード／除外キーワード／広告）を作成するには、ワークフロー 3 を繰り返す代わりに bulk-create を 1 回実行します。Apple Ads のテンプレートを使う場合は、まず変換して読み込んでください。プレビューで内容を確認します。取り消しはできず、正しくない部分がある構造を作成した場合も削除できません。JSON を使う場合は、--file - で構造を標準入力から渡します。

$ADAPTY asa campaigns bulk-create --from-file <template.xlsx|keywords.csv> --org-id <numeric-org-id> --preview
$ADAPTY asa campaigns bulk-create --file <structure.json> --idempotency-key <run>-bulk
$ADAPTY asa campaigns bulk-status <operation-id>

--org-id は orgs list で取得する数値の org_id です。campaigns create --org が受け取る UUID の internal_id ではありません。この機能の中で、Apple の数値 ID を必要とするのはこのコマンドだけです。このコマンドは success、partial、failed のいずれかになるまでポーリングします。partial の場合、成功したオブジェクトはそのまま残り、残りのオブジェクトと Apple による理由が示されます。--timeout はポーリングを終了するだけで、処理自体は終了しません。そのため、再送信せずに bulk-status で状態を確認してください。→ references/asa-management.md、### Bulk operations。

12. 誰が変更したか。 「誰がこれを一時停止したのか」「入札額が変わった理由は何か」「先週何が変わったのか」などを確認するときは、自動化や Apple のせいだと推測する前に変更履歴を読み取ります。1 回の呼び出しで指定できるのは 1 つの組織、最大 14 日間です。CLI 0.9.4 が必要です。ID フィルターには行に表示される Apple の数値 ID を指定します。UUID は使えません。modified_by は Apple ユーザー ID であり、メールアドレスではありません。すべて読み取り専用です。→ references/asa-management.md、## Change history。

$ADAPTY asa change-history list --campaign-group <uuid> --date-from <YYYY-MM-DD> --date-to <YYYY-MM-DD> [--entity-type Campaign] [--event-type UPDATE] [--fields]
$ADAPTY asa change-history get <detail-id> --campaign-group <uuid>

13. キャンペーンごとに専用のペイウォールを設定する。 あるキャンペーン、広告グループ、またはキーワードから来たユーザーに別のペイウォールやフローを表示します。そもそもセグメントを作成する理由はここにあるため、セグメントの作成で止めず、依頼をプレースメントまで進めてください。→ references/asa-management.md、## Segments。

1. 対象のエンティティ。 ユーザーが名前を指定した場合は、名前でそれぞれを検索します（campaigns list --search）。 パフォーマンスに基づいて選ぶ場合（「最も成果の高いキャンペーン」など）は、最上級の表現です。指標と期間を確認し、ユーザーの了承を得てから、ランキング形式の metrics 呼び出し 1 回分から ID を取得します（ワークフロー 2）。キーワードを指定するには、その広告グループが必要です。--keyword で検索できるのは、--ad-group をちょうど 1 つ指定した場合に限られます。

2. セグメントは 1 つか、複数か。 プレースメントでできることが変わるため、確認してください。キャンペーンごとに 1 つのセグメントを作ると、各キャンペーンにそれぞれ専用のペイウォールを設定できます。複数のキャンペーンにまたがる 1 つのセグメント（--campaign a --campaign b）を作ると、すべてのキャンペーンで同じペイウォールが使われます。ユーザーが「それぞれ」と指定した場合は、エンティティごとに 1 つ作成します。

3. Adapty アプリ。 $ADAPTY apps list を使います。asa apps list ではなく、Adapty アプリを指定します。複数ある場合は、ユーザーに確認してください。

4. 確認してから作成します。セグメントごとに確認してください。リストが空なら作成を進めます。一致するセグメントがあれば、それを再利用するセグメントとして伝え、同じものを新たに作成しないでください。

   $ADAPTY asa segments list --app <adapty-app-uuid> --campaign <campaign-uuid>
   $ADAPTY asa segments create --app <adapty-app-uuid> --campaign <campaign-uuid>
   

   作成するセグメントの数とタイトルをチャットで伝えてから、まとめて一度だけ承認を求めます。 デフォルトの [ASA] … タイトルを使ってください。

5. 応答を正しく読み取る。 新しいセグメントの profile_count: 0 は想定どおりです。Adapty は後から一致するプロファイルをカウントします。その後もカウントが 0 のままなら、フィルターが間違っているのではなく、Adapty にそのユーザーの Apple Ads アトリビューションがないことがほとんどです。セグメントを作り直すのではなく、ユーザーに https://adapty.io/docs/apple-search-ads を案内してください。

6. audiences スキルでルーティングする。 セグメントをプレースメントに追加する処理を担当します。新しいオーディエンスを既存のセグメントと比べてどこに配置するか、エントリーの形式、ユーザーが確認する変更前／変更後の表を扱います。セグメント ID とプレースメントを渡してください。そのオーディエンス用のペイウォールやフローがまだない場合は、先に flow-generator で作成します。

作成時の 405 は、サーバーでセグメントへの書き込みがまだ有効になっていないことを意味します。ユーザーに https://adapty.io/docs/ads-manager-create-segments を案内し（ダッシュボードから同じセグメントを作成できます）、取得した ID を使って手順 6 から続けてください。

ここに記載されていない内容

1. このファイルと、参照先の2つのファイルが、asa の仕様に関する信頼できる情報源です。
2. $ADAPTY asa <topic> <command> --help — インストール済みバージョンの正確なフラグ構文です。
3. CLI リポジトリ（https://github.com/adaptyteam/adapty-cli）のデフォルトブランチにある README.md、続いて skills/adapty-cli/references/cli-commands.md — どちらもインストール済みの CLI より情報が古い場合があります — 次に src/commands/asa/** を確認します。コマンド独自の static flags 宣言は、どの表よりも優先され、説明文とコマンドの食い違いを解決します。

フラグ、コマンド、URL パスを推測しないでください。3つの情報源のいずれにも確認できない場合は、その旨を伝えてください。

asa の仕様にまったく関係しない Adapty の質問（ダッシュボードにおける Apple Ads の概念、アトリビューション、分析などのプロダクト側の内容）については、ウェブを検索するのではなく、adapty-docs スキルを使って該当ページを探してください。