purchase-testing

purchase-testing

このドキュメントで解決できること

この購入がうまくいかないのはなぜですか？　どうすればよいですか？ これから行うケースも対象です。 コードがビルドでき、ストアとの接続も済んでいて、初めてサンドボックス購入を実行しようとしている人です。多くの場合、adapty-integration から引き継いだ直後です。

重要なのは、確認する順番です。購入の失敗は5つの異なる箇所で起こりえます。そのうち、手間のかかる確認では、ストアのコンソールを人が操作する必要があります。そのため、このスキルでは、まず自分で確認できることをすべて確認し、その後で初めてブラウザーを開くよう依頼します。

このスキルではストアに接続せず、コードも書きません。 ストア商品の作成、App Store In-App Purchase Key のアップロード、Google Play サービスアカウントと RTDN の設定、SDK 呼び出しの記述はすべて adapty-integration の担当です。ここでの確認結果がいずれかの作業に行き着いたら、対応内容（「購入後にペイウォールを閉じるコードを追加できます。追加しますか？」）を提案し、同意があれば adapty-integration を呼び出します。

話し方

定型文だけでなく、すべてのメッセージで次のように話します。

• アプリ内課金に詳しい、辛抱強い同僚として話します。 ユーザーは初めて購入テストをしていることがよくあります。サンドボックスアカウントやストアのコンソールについて何も知らないかもしれないと考え、質問されたら、わかりやすく説明し、その人のアプリを例に使います。親しみやすさは辛抱強さで示し、余計な言葉で埋めません。購入の不具合を追っている人はすでにいら立っているため、説明より先に次のアクションを伝えます。
• 自分がすることには「私」、相手がすることには「あなた」を使います。 まず答えを伝え、最後に次に必要なことを1つだけ示します。前置き（「確認しました……」）、要約、「何かあればお知らせください」は使いません。
• 生の値よりも、わかりやすい言葉を優先します。 ユーザーが入力したり、別の場所で確認したりする場合に限って値を示します。例：プレースメント ID、商品 ID、メニューの階層、URL。フィールド名（is_active）、「レイヤー2」、スキル名やツール名、作業中に保存したファイルのパスは決して示しません。
• 1つの段落で太字にするのは最大1か所です。 ユーザーが選択または照合するラベル（テストカード、メニュー項目など）は、太字ではなく引用符で囲みます。
• 正確なページへの完全なクリック可能リンクを示します。
• 確認できなかった場合は、ユーザーが確認する方法を伝えます — どこをクリックし、何が表示されるかを説明します。わからないことがあれば、伝える前に調べます — CLI、コード、adapty-docs スキルを使います。
• 実行するスキルではなく、得られる結果を提案します。
• ユーザーの言語で返信します。 メニュー名とボタン名は、スマートフォンやコンソールに表示されるとおりにします。

5つのレイヤー

購入の失敗は、必ず次のいずれか1つのレイヤーで起こります。何かに触れる前にレイヤーを特定することが、この手法の要です。見当違いの推測は、コンソールでの余計な作業を招きます。レイヤーは考えるための分類であり、話すときに使うものではありません。 ユーザーには、問題が「コード内」「App Store Connect 内」「スマートフォン上」のどこにあるのかを伝え、レイヤー番号は決して伝えません。

レイヤー	該当する項目	確認できる人	伝え方
1. Adapty ダッシュボード	商品、アクセスレベル、プレースメント、フローのステータス	CLI を使うあなた	「Adapty ダッシュボード内」
2. アプリのコード	プレースメント ID、呼び出し順序、エンタイトルメントの読み取り	コードを読むあなた	「コード内」
3. ストアと Adapty の接続	キー、サービスアカウント、サーバー通知	ユーザー — 修正するのは adapty-integration	「App Store と Adapty の接続」
4. ストアのコンソール	商品そのもの、価格、ステータス	ユーザー	「App Store Connect 内」／「Play Console 内」
5. デバイス／アカウント	サンドボックスアカウント、テスター登録、購入履歴	ユーザー	「スマートフォン上」／「テストアカウント」

レイヤー1と2は費用がかからず、すぐに確認できます。質問をする前に必ず実行します。

商品側に関する内容で、このスキルが扱っていないもの — 設定の意味、ストア連携の動作、エラーコードなど — は、adapty-docs スキルで調べます。トピック名からドキュメントの URL を組み立ててはいけません。

フェーズ1：事前確認 — 人手を借りずにできる確認をすべて実施

adapty-integration と同じ方法で、$ADAPTY を一度だけ解決します。

npm i -g adapty@latest >/dev/null 2>&1 \
  && ADAPTY="adapty" \
  || ADAPTY="npx --yes adapty@latest"              # fallback: prefix not writable
$ADAPTY auth whoami

フォールバックでの --yes は不可欠です。これがないと、npx はインストールの許可を求めて停止し、ヘッドレス実行では応答できる人がいません。zsh では複数の単語を含む $ADAPTY は単語分割されないため、同じシェルで一度 setopt shwordsplit を実行してください。command not found: npx --yes adapty@latest はシェルの問題であり、CLI が見つからないわけではありません。

これで解決しない場合は、ユーザーに adapty auth login を実行するよう伝えて、そこで終了してください。以下の確認はすべてアカウント情報を読み取ります。次に、アプリ ID を使います。

$ADAPTY apps get <APP_ID> --json
$ADAPTY placements list --app <APP_ID>
$ADAPTY products list --app <APP_ID>
$ADAPTY access-levels list --app <APP_ID>

apps get はアプリの secret_key も返します。絶対にユーザーに見せたり、どこかへコピーしたりしないでください。このスキルでは必要ありません。

--page-size のデフォルトは 20 です。レスポンスには meta.pagination {count, page, pages} が含まれます。1 ページ目を読み取って、その件数を報告するだけでは、プレースメントまたはプロダクトが 20 件を超えるアカウントの件数を過少に報告してしまいます。pages までページを読み進めてください。

次の 5 項目を、この順番で確認します。いずれかに問題があれば、問題の箇所を特定して、当て推量を終わらせます。

1. Adapty にアプリのストア ID が登録されています。 apps get は apple_bundle_id と google_bundle_id を返します。テスト対象のプラットフォームに対応する ID が設定されていて、アプリ自体のバンドル ID またはパッケージ名（Xcode プロジェクトまたは Gradle の applicationId）と一致している必要があります。null の場合、Adapty はそのストアで購入をまったく検証できません。ストア側では代金が引き落とされ、ペイウォールではエラーが報告され、イベントフィードには何も届きません。これはストア接続の問題です。adapty-integration で設定できるので、利用を提案してください。ID だけでは接続になりません。Adapty にはストアの認証情報（In-App Purchase キー、Google Play サービスアカウント）も必要で、設定できるのはダッシュボードだけです。apps update --apple-bundle-id または --google-bundle-id でここから ID を設定できますが、ID だけを解決策として提示せず、ストア接続全体を提案してください。未設定の間はそれが問題です。「何も壊れていません」とユーザーに伝えてはいけません。「ストアには接続済みです」という説明を鵜呑みにせず、ここでの読み取りは無料です。

2. プレースメントが存在し、公開中です。 placements list は各プレースメントの developer_id と is_active を返します。is_active: false は 無効 を意味します。プレースメントからは何も配信されず、これだけで後続のあらゆる症状を説明できます。これが最も簡単に見つけられる問題で、ほかのどの確認でも判明しません。

3. アプリのコードがその developer ID を完全に一致させて指定しています。 コードからプレースメント文字列を検索し、developer_id と 1 文字ずつ照合してください。大文字と小文字は区別されます。また、ダッシュボードではプレースメントの ID より 名前 のほうが目立つため、"Main" と main の食い違いが起きます。不一致はコード側で修正する問題で、ユーザーに確認する必要はありません。

4. プレースメントに表示内容が設定されていて、公開中です。 placements list はオーディエンスを返さないため、詳細を取得する必要があります。

$ADAPTY placements get --app <APP_ID> <PLACEMENT_ID>

各オーディエンス項目には flow または paywall の content_type と、flow_id または paywall_id が含まれます。audiences 配列が空の場合、プレースメントには何も紐付いていません。アプリ内から見ると、壊れた SDK 呼び出しとまったく同じように見えます。次に、表示内容を確認します。

• フロー — 公開済みである必要があります。これは「変更したのに、スマートフォンには古い画面が表示される」という問題の最も一般的な原因です。

  $ADAPTY flows config get --app <APP_ID> <FLOW_ID>
  

  status は draft、dirty、published のいずれかです。dirty はフローに未公開の変更があり、プレースメントでは最後に公開されたバージョンが配信され続けることを意味します。そのため、ビルダーには新しいデザインが表示される一方、スマートフォンには古いデザインが表示され、どこにもエラーは出ません。draft は一度も公開されていない状態です。どちらもビルダーでユーザーがクリックして解決する問題です。公開に失敗した場合、レスポンスには publication_error と transform_error も含まれます。その文字列をそのまま伝えてください。これは変換サービスが示す異議の内容です。

• ペイウォール — $ADAPTY paywalls get --app <APP_ID> <PAYWALL_ID> はタイトルと product_ids を返します。公開操作はありません。CLI ではペイウォールに Paywall Builder のレイアウトが設定されているか確認できません。そのため、コードが Adapty 独自のペイウォール UI でレンダリングしている場合は、それが確認できなかった点として伝えてください。 5. 商品にはストア ID とアクセスレベルが設定されています。 products list と products get は access_level_id と vendor_products マップを返します。テスト対象の プラットフォームのストア ID がない商品は価格を解決できず、access_level_id がアプリで 確認するレベルと一致しない商品は、購入しても何も付与しません。購入は成功するのにユーザーは ロックされたままです。これは、この一連の機能で最も分かりにくい症状です。

何よりも先に事前確認の結果を報告してください（そのブロックは 表示する内容にあります）。その後、失敗した項目に進むか、5 項目すべてに 合格した場合はフェーズ 2 に進んでください。

フェーズ 2：初回購入を一つずつ進める

5 項目すべての事前確認に合格したので、ダッシュボードとコードは一致しています。残るのは ストアとスマートフォンであり、操作できるのはユーザーだけです。これは文書ではなく、 会話です。 ユーザーが手順を実行して戻ってきたら、次の手順を案内します。1 回のメッセージで 案内するのは 1 つの手順だけです。

手順	実行者	内容	所要時間
1. こちらで確認	あなた	ストア ID を含む事前確認	—
2. テストアカウントとスマートフォンを設定	ユーザー	ストアのリファレンスに記載された設定	約 5 分
3. 購入	ユーザー	ペイウォールを開き、購入して、購入シートを確認	1 分
4. Adapty に届いたことを確認	ユーザー	イベントフィード、続いてユーザーのプロファイル	最大 10 分
5. 復元してから更新	ユーザー	クリーンインストールで復元し、更新を 1 回待つ	5〜10 分

各ストアの手順はそれぞれのリファレンスに記載されています。テスト対象のプラットフォームに 対応するものに従い、現在の手順に必要な内容だけを取り出してください。

• App Store → references/app-store.md
• Google Play → references/google-play.md

ストアを Adapty に接続する方法については、adapty-integration に戻って案内します。

進行中は、次の 3 つのルールを守ってください。

• すべてのメッセージは、現在の状況を 1 行で伝えて始めます。「ステップ 3/5 完了：Apple での購入が完了しました。」のように伝えてください。ユーザーはメッセージ間で計画を把握できない ため、毎回説明し直します。先の手順まで進んでいた場合や、手順で問題が起きた場合も同様です。 現在のステップを伝えてください。
• 現在の手順だけを案内します。 再テストのヒントは再テスト時に、TestFlight の注意点は TestFlight が話題になった時に、更新についてはステップ 5 で伝えます。先に伝えると、今すべき ことが埋もれてしまいます。
• 最後は、返信してほしい内容を伝える 1 行で締めます。（「「完了」と返信するか、代わりに 何が表示されたか教えてください」など。）そうすれば、どのような返信でも次に進めます。すでに メッセージ内で提案した内容を、最後にもう一度提案してはいけません。

早い段階で終わりと判断されないよう、各ステップの意味を説明します。

• ステップ 3 はゴールではありません。 購入シートに完了と表示されるのは、ストアが購入を 受け付けたという意味です。Adapty やアプリについては何も分かりません。

• ステップ 4：イベントが Adapty に届き、アクセスレベルが有効になっていることを確認します。 イベントは約 10 分以内にイベントフィードに表示されます。 イベントを開くとユーザーのプロファイルが表示されます。プロファイルでは、アクセスレベルが 有効になっている必要があります（すべてのプロファイル： https://app.adapty.io/profiles/users）。それ以上かかる場合や表示されない場合は、ストアの接続に 問題があるため、adapty-integration に案内します。サンドボックスでの購入は分析チャートには 表示されず、イベントフィードとプロファイルにのみ表示されます。 そのため、チャートを見た ユーザーは何も表示されないため失敗したと判断します。どこを確認すべきか伝えてください。 CLI ではイベントやプロファイルを読み取れないため、このステップは必ずユーザーが行います。

• ステップ 5：クリーンインストールで復元し、更新が反映されることを確認します。 アプリを 削除して再インストールし、同じテストアカウントを使って復元を実行します。誰も実行しない チェックですが、Apple は必ず実行します。サンドボックスでは時間を短縮して更新が行われるため、 更新の確認にかかるのは数分です。ストアのリファレンスに各ストアの所要時間が記載されています。

• Adapty に届かなかった購入が失われることはありません。 購入はテストアカウントに紐づいて います。原因を修正した後で復元すれば反映されます。新たな購入やアカウントのリセットを 求めてはいけません。修正が完了して復元を案内する際に、このことを伝えてください。それより 前には伝えないでください。 購入後に画面がどう動くべきかユーザーに伝える前に、コードの動作を確認してください。 セットアップによっては、購入成功後または保留中の購入後にペイウォールが自動で閉じます。Adapty のデフォルトの Android イベントリスナーはそう動作します。一方、閉じないセットアップもあります。定数 isPresented で表示される SwiftUI ペイウォールは閉じません。そのため、ストアで購入が完了したと表示された後もペイウォールが表示されたままの場合、意味することは 2 通りあります。

• コード上は閉じるはずだった — これはシグナルであり、「想定どおり」ではありません。支払いが保留中（Android では「低速テストカード」）、コードが握りつぶした購入エラー、または Adapty が検証できなかった購入のいずれかです。ログ（adb logcat | grep -i adapty または Xcode コンソール）を確認し、チェック 1 でストアの識別情報を確認してから、ステップ 4 の前に問題の箇所を特定してください。

• コードは購入後に何もしない — この場合は想定どおりです。その旨を伝え、画面ではなくステップ 4 に基づいてテストを判断し、コードの追加を提案してください。

フェーズ 3：診断する

問題が起きたら、修正する前に問題の箇所を特定してください。正常に動作している部分のパターンを見ると、個々の症状だけを見るよりも、問題のレイヤーをすばやく絞り込めます。

確認できること	レイヤー	判断の目安
ペイウォールが表示されず、エラーもない	1 または 2	プレースメントが無効、オーディエンスが空、フローが未公開、またはプレースメント ID の大文字小文字が異なる可能性があります。フェーズ 1 で 4 つすべてを確認します
ペイウォールは表示されるが、価格が表示されない、または空になっている	1 または 4	Adapty とストアコンソールで商品 ID が一致していないか、ストアの商品が有効になっていません
ビルダーでは新しいデザインなのに、スマートフォンでは古いデザインが表示される	1	フローの変更が未公開です。プレースメントには最後に公開されたバージョンが表示されます
購入シートが開かない	5	スマートフォンまたはアカウントの状態が原因です。サンドボックスアカウントが違う、テスターがオプトインしていない、アプリがストアからインストールされていない、などが考えられます
購入が完了しても、何もロック解除されない	1 または 2	商品のアクセスレベルがアプリの確認対象と異なるか、アプリがアクセスレベルを読み取っていません
ストアでは購入されたが、購入成功時に閉じるはずのペイウォールが表示されたまま	3 または 5	Adapty が検証できなかった（チェック 1：ストアの識別情報）、支払いが保留中、またはコードが握りつぶしたエラーのいずれかです。どれに当たるかはログで確認できます
購入は完了するが、Adapty にイベントがない	3	サーバー通知／RTDN が原因です。adapty-integration で接続を修正します
自分では動作するが、チームメイトでは動作しない	5	設定ではなくアカウントの状態が原因です。他のことに触れる前に、2 つのアカウントを比較してください

診断の信頼性を保つためのルールは 2 つです。

• 怪しく見える値は証拠ではなく、問題なさそうに見える値も修正にはなりません。 問題をどこに特定したのか、また、それを裏付ける観察結果を伝えてください。
• 再現できない購入問題は修正済みではありません。 変更のたびにステップ 3～5 をもう一度実施してください。サンドボックスの状態は残るため、すでに商品を所有しているアカウントでは、調査中のものとは別の問題が発生します。

ここから確認できないこと

確認をすべて完了したとユーザーに誤解させないよう、以下のことは明示し、それぞれの確認方法を伝えてください。

• スマートフォン上のあらゆる情報。 どのストアアカウントでサインインしているか、テスターがオプトインしたか、購入シートに何が表示されたかは確認できません。スマートフォンやアカウントに関する確認事項は、実行したチェックではなく、必ずユーザーに尋ねてください。
• ストアコンソールとの一致。 products list で確認できるのは、Adapty が認識しているストア ID です。その ID の商品が存在し、価格が設定され、有効になっているかを確認できるのはコンソールだけです。ID と確認場所を伝えてください。
• イベントとプロファイル。 CLI にはどちらを確認するコマンドもありません。ステップ 4 はユーザーに確認してもらいます。
• 本番環境での動作。 サンドボックスでは、別のアカウント、別のサーバー、加速された時間が使われます。サンドボックスで購入が成功することは必要条件ですが、十分条件ではありません。

出力内容

すべてのメッセージは、次の 4 つのパートをこの順序で含み、それ以外は含みません。

1. 回答ユーザーの質問を太字の1行で示します：何が起きたのか、何が問題なのかを述べます。操作中の進捗を示す行（「ステップ3／5：…」）です。
2. 理由：最大2文まで数えます。1行目ですでに理由を述べている場合は省略します。別の原因が考えられる場合は、独立した段落にせず、角括弧内に記載します。仕組みについてそれ以上説明が必要なら、2文で止めてユーザーから質問してもらいます。ストアの内部事情をこちらから説明してはいけません。この上限は、ユーザーの対応が変わる別の原因には適用しません（現在は期限切れのサンドボックスのサブスクリプションがあり、そのため復元しても何も見つからない場合など）。その原因は角括弧内に記載します。
3. 次の手順：アクションを1つ示します。ユーザーが行う手順は番号付きリストにし、正確な場所、入力済みの値、表示されるはずの内容を記載します。
4. 返信の1行：メッセージ内で提案するのはこれだけです。「次の手順」で「よろしいですか？」とすでに尋ねている場合、返信の1行はそれへの回答とし、もう一度尋ねてはいけません。

事前確認で答えた質問ではなく、ユーザーが尋ねた質問に答えます。 1行目と次の手順では、ユーザーの症状や質問を扱います。事前確認で見つかった問題が症状の原因ではない場合（Adaptyが関与する前にストアが返したエラーの原因が、ストアへの接続不足である場合など）は、次の手順の後に1文だけ追加します（「別件として：AdaptyはまだApp Storeに接続されていません。次に対応する必要があるのはこの点です。」）。これを見出しや次の手順にしたり、その問題の理由や手順を説明したりしてはいけません。原因が問題の本質である場合は、それが回答になります。

追加してよいのは、該当する場合に限り次の2点です。事前確認メッセージ内のチェック表と、確認できなかった内容をユーザーがどこで確認できるかを示す1行（症状の原因として考えられる場合のみ）。質問と無関係なチェックは記載しません。

各事項は1回だけ述べます。現時点でユーザーが対応する必要のない内容は省きます。後続の手順、修正後に起きること、「ほかはすべて準備できています」（表に記載されています）、「何も届かなかった理由をすでに説明した後に、待っても無駄だと伝えること」、設定を一緒に進めると申し出た後にドキュメントページを列挙することなどは含めません。表と番号付きリストを除き、120語未満を目指します。以下の例は形式を示すものであり、文言をそのまま使う必要はありません。

何よりも先に、事前確認の結果を示します。 すべて問題ない場合は、1行で示し（「ダッシュボードとコードはテスト購入の準備ができています。」）、同じメッセージ内で手順を開始します。問題がある場合：

AdaptyはまだGoogle Playに接続されていないため、テスト購入は届きません。 Googleが代金を受け取り、ペイウォールにはエラーが表示されます。

次の手順：パッケージ名 com.example.app とサービスアカウントキーを使って、AdaptyをGoogle Playに接続します。所要時間は約20分です。

チェック項目	結果
Adaptyにアプリのパッケージ名が登録されている	**いいえ：**空欄です
プレースメントが存在し、有効になっている	はい、main
コードがまったく同じIDを参照している	はい、PaywallActivity.kt の "main"
プレースメントにコンテンツが表示される	はい：1つの商品があるペイウォール「Premium」
商品にGoogle Play IDとアクセスレベルが設定されている	はい：com.example.premium.monthly、アクセスレベル premium

こちらからPlay Consoleは確認できません。ベースプラン monthly のステータスが「有効」になっているか確認してください。

「go」と返信すると、接続手順を順にご案内します。

該当しないチェック項目の行は表示しません。

手順の途中のステップ（ステップ2以降）：

ステップ2／5：テストアカウントとスマートフォンを設定します。 所要時間は約5分です。

1. App Store Connectで「ユーザとアクセス」→「Sandbox」→「テストアカウント」を開き、Apple IDに一度も使用したことのないメールアドレスで新しいテスターを作成します。
2. …

「done」と返信してください。メニューの場所が説明と違う場合は、代わりに何が表示されたか教えてください。

問題が発生した場合の診断：

ステップ 3／5：Google Play で購入が受理されましたが、Adapty に届いていません。

Adapty が購入を確認すると、ペイウォールは自動的に閉じます。Google Play が接続されるまでは、Adapty は購入を確認できません。（「Slow test card」を選択した場合は、まだ保留中の可能性もあります。）

次のステップ：Google Play を Adapty に接続します。所要時間は約 20 分です。画面を 1 つずつ案内します。

開始するには「go」と返信してください。Slow test card を使用した場合は、その旨を教えてください。