search

search — アプリの検索＋追跡

最初に using-appfollow を読んでください（セッション開始、書き込みの手順、エラーコード）。

入力

• query：アプリ名（自由入力の検索キーワード）。
• store：短縮ストアコード — 検索では as（App Store）または gp（Google Play）。add_app では10種類すべてのコードを使用します（using-appfollow → references/tool-map.md）。
• country（既定値は us）、collection（名前。新しい場合は作成されます）、locale。

フロー

0. セッション： whoami（using-appfollow を参照）。
1. 入力を正規化します。 検索に使えるのは自由入力のキーワードのみです。ASO 検索エンドポイントは ストア URL や ext_id を受け付けません。検索前に、クエリをアプリ名に整えます（貼り付けられた URL がある場合は、 アプリ名／タイトルだけを残します）。
2. 検索（読み取り専用、すべてのプランで利用可能）。 aso_search_results を呼び出します（任意で aso_search_suggestions、12 cr）。候補を番号付きで提示します。タイトルが完全一致する候補が1つだけの場合に限り自動選択し、 それ以外はユーザーに選んでもらいます。
3. コレクションを解決します。 list_collections を実行します。対象のコレクションが新規の場合は、 add_collection_preview → ユーザーの承認 → add_collection の順に実行します。
4. 重複を確認します（読み取り専用）。 list_apps を実行します（apps_id = 対象コレクションの collectionId）。 アプリの extId がすでにある場合は、skipped_existing に記録して追加をスキップします。list_apps が返す store は 長い名称です（itunes = as、googleplay = gp）。
5. 追加（書き込み — プランによって制限される場合があります）。 add_app_preview → ユーザーの明示的な承認 → 同一の引数で add_app を実行します：store（短縮コード）、ext_id、apps_id、locale（2文字の国コード）。 ユーザーがそのアプリを競合相手だと言った場合に限り is_competitor: true を渡します（既定値：ユーザー自身のアプリ）。
6. 確認します。 もう一度 list_apps を実行し、アプリの extId が表示されることを確認します。コレクションの apps_id はアプリと一緒に保持してください。レポートスキルは apps_id と ext_id でアプリを指定します。
7. 出力します（以下の JSON ブロック）。

読み取り専用の代替手順（書き込みがプランによって制限される場合）

add_collection には Advanced API / Custom プランが必要です。add_collection と add_app のどちらにも 機能ゲートはありません。そのため、プランによるブロックが FEATURE_DISABLED として返されることはありません。 代わりに ACCESS_DENIED、VALIDATION_ERROR（add_app でアプリまたは競合相手の上限に達した場合）、または UPSTREAM_ERROR が返される可能性があります。したがって：

• 検索と重複確認は必ず完了してください（読み取り専用のため、すべてのプランで利用できます）。
• add_* の確認を試みてください。
• 追加時にエラーコードが返された場合は、特定のコードを断定しないでください。見つかった候補の参照情報を報告し、 追加を完了できなかったこと（プランの制限である可能性が高い）を明確に伝えます。見つかった参照情報を not_added に列挙し、 レポートスキルがそれらを対象にできるようにしてください（すでに追跡済みの場合があります）。

出力（フェンス付き JSON）

{
  "added": [{"store": "as", "ext_id": "389801252", "apps_id": 12345, "collection": "Core apps", "locale": "us", "title": "Example App"}],
  "skipped_existing": [],
  "not_added": [],
  "collection_created": null,
  "credits_spent_estimate": 13
}