aso-analysis

aso-analysis

（セッション、書き込み手順、エラーコードについて）まず using-appfollow を読んでください。

入力

• 対象範囲： アプリ、コレクション全体、または1つのコレクションからユーザーが選んだ一部のアプリ（例：「自分の から、この3つのアプリだけ」）。一部のアプリを対象とする場合：list_collections でコレクションを特定し、list_apps でそのアプリを一覧表示してから、選択されたアプリのみの ASO データを収集します。scope.type: "collection_subset" を出力し、collection_name を設定して、apps には選択された一部のアプリ（コレクション全体ではなく）を指定します。1つのレポートで複数のコレクションを対象とすることには、まだ対応していません（後回し）。
• 国： 既定では主要な国を1つ。
• デバイス： App Store → iphone、ipad、Google Play → android。
• キーワードシード（任意）。

既定の深度

概算 ≈ A×C×D×[S×P×12 (list_keywords) + S×12 (get_rankings)] + A×C×[K_seed×12 (suggestions) + K_serp×12 (search)] + A(as)×12 (search_ads) + A×12 (aso report, optional)。既定値 = deep： トレンドのサンプル日付は最大 S=4（今日／−7日／−14日／−28日）、K_serp=10。deep でキーワードページが1つ、シード候補が10個の場合、1つのアプリ／国／デバイスあたり約 360 cr です（トレンドの全サンプリングと ASO レポートを含む）。quick／standard はユーザーから明示的にリクエストされた場合のみ使用します（S を4→2、K_serp を10→5に減らします）。

トレンドセクション — 検証ゲートあり（スモークゲート iv）

トレンド機能（S = today, −7d, −14d, −28d におけるサンプル日ごとのキーワード順位とカテゴリ順位）は、date=<past> を指定した list_keywords／get_rankings が実際の過去のスナップショットを返すことに依存します。これはスモークゲート iv で判定されます。ゲート iv を通過した場合のみ、トレンドセクションを作成してください。通過しなかった場合は、現在のスナップショットのみを出力します（TOP3／TOP10／TOP30／TOP100／UNRANKED の区分、有効性の段階、競合との差）。HTML／手法のフッターには、過去データを取得できるエンドポイントがないため、時系列トレンドを利用できないことを明記します。過去の日付のラベルを付けて、今日のデータを決して再取得しないでください。

キーワード追加ループ（唯一の書き込み経路）

1. 候補キーワードを最大15個、表で提案します。ユーザーが明示的に選択します（自動追加はしません）。
2. edit_keywords は (apps_id, country, device) の追跡対象キーワードセットを置き換えます。CSV に含まれないキーワードはすべて削除されます。新しい候補だけを送信してはいけません。
3. (country, device) ごとに、list_keywords({ext_id, country, device}) で現在のセットを読み取ります（date なし＝今日）。ページングが終わるまで続けます。プレビューの前には、以前の読み取りがあっても必ず最新の状態を読み取ってください。同じ (apps_id, country, device) に対して edit_keywords を実行した後は、以前の読み取り結果は古くなり、その編集で追加されたキーワードが削除されるためです。現在のセットには、レスポンスに含まれる追跡対象キーワードをすべて含めます。順位付きと順位なし（no_pos）の両方が対象です。順位なしのキーワードを削除すると、REPLACE によってそのキーワードも削除されます。ページの読み取りに失敗した場合は中止し、書き込みは行いません。
4. CSV = 現在のセット ∪ 選択されたキーワード（重複を除去、大文字・小文字を区別しない）。 edit_keywords_preview({country, device, keywords CSV, apps_id}) — apps_id は常に明示的に指定します（省略するとアカウント内の最初のコレクションが既定値になり、誤ったコレクションに書き込む危険があります）。サイズ制限による拒否（バイト上限を示す VALIDATION_ERROR）が発生した場合は中止し、ユーザーに伝えます。セットを複数の呼び出しに分割してはいけません（各呼び出しでセット全体が置き換えられるため、最後のチャンクだけが残ります）。また、ユーザーが削除するキーワードを指定しない限り、サイズに収めるために現在のキーワードを削ってはいけません（削除する場合は、削除対象として一覧表示します）。
5. 呼び出しによって置き換えられる内容を提示します。コレクション、保持される現在のキーワード（件数）、追加リスト、削除なし。list_keywords は ext_id で読み取りますが、どのコレクションから読み取ったかは示しません。list_collections と list_apps を確認してください。アプリが複数のコレクションに含まれている場合、現在のセットは別のコレクションのものである可能性があります。その場合、削除なしとは断言せず、その旨を伝え、ユーザーが明示的に承認した場合にのみ書き込みます（そうでなければ中止します）。承認を得てください。
6. edit_keywords の前に、手順3と同じ方法で list_keywords を再読み取りします（上流のリビジョン確認機能はありません）。手順3以降にセットが変わっていた場合は、手順4に戻り、再構築、再プレビュー、再承認を行います。その後、引数をそのまま使い、トークンとともに edit_keywords を実行します。CONFIRMATION_REQUIRED が返された場合は、再度プレビューします。
7. edit_keywords は Keywords-Edit アクションであり、Advanced の制限対象ではありません。そのため、Keywords-Edit プランで利用できます。順位は次の解析サイクルで表示されます。最大3個のキーワードを対象とする任意のライブ SERP 抜き取り確認を提案します。適用済みのバッチには status:"applied" の findings を記録します。

メタデータ最適化 — 誠実な読み取り順（提案のみ。メタデータを書き込む機能はありません）

最後の項目ほど信頼性が高くなります。

1. get_app_metadata — セッションで利用可能と示されている場合に限ります（事前確認）。確認が取れるまでは、未検証のパススルーとして扱います。
2. aso_search_results による自社 SERP カード（タイトル／サブタイトル／ジャンル。説明は含まれません） — こちらも未検証です。
3. ユーザーによる貼り付け — 現時点で、現在のメタデータを確実に確認できる唯一の方法です。 App Store のキーワード欄はデベロッパーだけが確認できます。必ず貼り付けてもらうか、確認を省略します。

各フィールドの出力：CURRENT → SUGGESTED ＋ 増減するキーワード ＋ 根拠 ＋ ローカライズのリスク ＋「App Store Connect / Play Console で適用」。

キーワードの効果ティア（フッターには実際の定義をそのまま記載）

追跡対象の各キーワードを、実際の list_keywords.effectiveness フィールドのみでティア分けします。有望 （effectiveness > 20）と対象外（effectiveness <= 20）に分け、各ティア内では effectiveness の降順に並べます。effectiveness（0～100）は、人気度と競合状況を考慮した AppFollow のキーワード効果指数です。20 を超えるキーワードはアプリのタイトル／サブタイトルに入れる価値があります（下記のサポート記事を参照）。

popularity と difficulty は参考情報の列としてのみ表示し、ティア分けには使用しません。

• 人気度（0～100）：検索トラフィックのスコアです。尺度は指数的で非線形です。AppFollow は、スコアが約 20 未満のキーワードを推奨していません。
• 難易度（0～100）：キーワードで Top-10 にランクインする難しさです。数値が高いほど難しくなります。

公開されている合成式はありません。 effectiveness、popularity、difficulty は AppFollow が算出した値であり、list_keywords からそのまま取得したものだとレポートにはっきり記載します。各スコアの意味については、次のサポート記事を案内してください： https://support.appfollow.io/hc/en-us/articles/360020831817-Keyword-Tracking.

list_keywords.score（通常は null で、仕様が公開されていない副次的な「AF score」）は副次的な表示値としてのみ示し、ティア分けには一切使用しません。すべての分析結果には、expected_impact{metric, direction, magnitude, confidence, basis:"effectiveness-v1"} および再現可能な evidence[]{source:"mcp:<tool>", args, observed, at} を含めます。

任意のツール

aso_featured_apps は、ext_id スキーマの修正が反映されるまで HOLD とします（それまでは VALIDATION_ERROR が予想されるため、該当セクションを n/a と記載してください）。get_aso_report_app_store／get_aso_report_gdc_google_play は任意です。エラーが発生した場合は、該当セクションを「n/a」と記載します。

出力

aso-analysis-<scope>-<date>.html（references/report-template.html を埋めて作成）と findings.json（appfollow.toolkit.findings/v1、report_type:"aso"）を出力します。書き込む前に schemas/findings.schema.json に照らして検証してください。Claude Code では成果物を公開します。Codex ではファイルを書き込み、保存先を伝えます。ユーザーには、ユーザー自身が接続しているエージェントから調査結果をトラッカーに登録できることを伝えてください。