カスタムペイウォールとホスト型Paywallを併用する設計ガイド
自社で作り込んだペイウォール画面を残しつつ、購入と権限管理だけをサブスクリプション基盤に任せたい——そんな構成は、表示の自由度とサブスクリプション基盤の整合性を両立させます。この記事では、2種類のペイウォールを1つのアプリで運用するときの責務の分け方、SDK呼び出しの流れ、PlacementとOffering metadataによる出し分け、そしてmetadataが未設定でも壊れない分岐の作り方を順に整理します。
併用が向くケースと、向かないケース
ホスト型Paywallのドキュメントでは、Paywallはネイティブビューとして描画され、ダッシュボードからデザインの作成・変更・テストができると説明されています。ストアへの再申請なしで改善を回せる点が利点として挙げられ、提供元のドキュメントでは新規アプリにはこの構成が推奨されています。一方、次のような事情があるとカスタムUIを並走させたくなります。
- 段階移行:長年運用してきた自作ペイウォールを、一度に置き換えず少しずつホスト型Paywall側へ寄せたい。
- 比較実験:ハードコードされた既存画面と、ホスト型Paywallで組んだ新画面の成果を比べたい。
- セグメント別オファー:特定のユーザー層向けに、独自の価格表示やプロモーション表現が必要。
- 複雑なジャーニー:オンボーディングの分岐など、アプリ固有のロジックを画面に織り込みたい。
逆に、ペイウォールの見た目に強いこだわりがなく、更新頻度も高くないなら、ホスト型Paywall単体のほうが運用は軽くなります。併用は「UIは自前、それ以外は委任」という分担が成立するときだけ意味を持ちます。
どちらの画面を出すかをアプリ側が決めても、購入処理は必ずサブスクリプションSDKを通します。この一点を守ることで、価格の二重管理やエンタイトルメントの取りこぼしを避けられます。
エンドツーエンドの流れ
2種類のペイウォールを持つアプリでは、表示の判断と購入の実行が1本の経路に収まっていることが重要です。ユーザーがオンボーディング完了や機能ゲート、プロモーション入口といった分岐点に立つと、アプリはまず「ジャーニーのどこで見せるか」を示すPlacementを添えてOfferingsを要求します。サブスクリプション基盤はターゲティング規則に従ってOfferingを返し、同じPlacementでもユーザーによって中身が変わり得ます。
受け取ったOfferingのmetadataをアプリが読み、ホスト型PaywallとカスタムUIのどちらを描画するかを決めます。ユーザーがプロダクトを選ぶ段階では、価格やプロダクト情報は常にサブスクリプション基盤から取得した値を使います。購入はサブスクリプションSDK経由で開始し、UIがどちらでも購入フローは同一です。購入後はサブスクリプション基盤がエンタイトルメントを更新し、アプリはCustomerInfoを見てコンテンツを解放または制限します。
表示だけを差し替え、購入と権限の経路を1本に保つことが、この構成の要点です。提供元のドキュメントでは、Experiment機能によって異なるPlacementやペイウォール間のコンバージョン成果をテスト・比較できると説明されています。
責務の分担:どこまで自前で持つか
併用構成では、画面の見た目と分岐の判断はアプリ側、プロダクト情報・購入・権限はサブスクリプション基盤側に置きます。次の表を設計レビューのチェックに使ってください。
| 領域 | 自前で持つ | サブスクリプション基盤に委ねる |
|---|---|---|
| ペイウォールのレイアウト・コピー | ○ | — |
| どのUIを出すかの条件分岐 | ○ | — |
| プロダクト一覧・価格・初回オファー | — | ○ |
| 購入トランザクションの実行 | — | ○ |
| エンタイトルメントの付与・更新 | — | ○ |
| コンテンツ解放の判定材料(CustomerInfo) | 参照する | 生成する |
| ペイウォールのデザイン変更 | リリースが必要 | ダッシュボードで完結 |
カスタムUIを選ぶ動機として分かりやすいのが、アプリ固有の文脈を画面に持ち込むケースです。たとえばゲーミフィケーションアプリなら、途切れた連続記録をペイウォール上に描き、「購読すれば記録を修復できる」と伝えられます。こうした表現はアプリの状態に依存するため、汎用テンプレートだけでは作りにくい部分です。
ステップ1:プロダクト情報を取得する
カスタムUIに正しい選択肢・価格・初回オファーを並べるには、まずサブスクリプション基盤からOfferingsを取得します。SwiftではPurchases.shared.getOfferings()、KotlinではPurchases.sharedInstance.getOfferingsWith()を使い、得られたOfferingから必要なパッケージを取り出します。取得したOfferingオブジェクトには、表示に必要なプロダクト詳細が含まれています。
以下はSDK呼び出しの形を示す契約モジュールです。実際のプロジェクトでは、エラー時の表示や空のパッケージリストの扱いを併せて設計してください。
- Swift版の取得例:code0001
- Kotlin版の取得例:code0002
プロダクト表示の詳細な手順は、公式のDisplaying Productsドキュメント(link0010)を参照してください。
ステップ2:購入処理を実行する
ユーザーがカスタム画面上でパッケージを選んだら、サブスクリプションSDKで購入を開始します。iOSはPurchases.shared.purchase(package:)、AndroidはPurchases.sharedInstance.purchaseWith()です。購入完了後の処理と、起こり得るエラーのハンドリングを必ず実装します。
- Swift版の購入例:code0003
- Kotlin版の購入例:code0004
購入結果からエンタイトルメントの有効状態を確認し、成功時のみコンテンツを解放する流れにします。購入フローの詳細は公式のMaking Purchasesドキュメント(link0011)にあります。
ステップ3:エンタイトルメントを管理する
どちらのペイウォールを使っていても、権限の管理はサブスクリプション基盤が担います。購入が成功するとCustomerInfoが更新されるので、アプリはそれを参照してプレミアム機能の解放・制限を決めます。SwiftではPurchases.shared.getCustomerInfoで最新のCustomerInfoを取得できます。
- Swift版の取得例:code0005
- Kotlin版の取得例:code0006
「購入が成功したか」と「エンタイトルメントが有効か」は別の判定です。購入完了イベントだけを根拠に画面を解放すると、復元や更新のタイミングで不整合が起きます。表示の可否は必ずCustomerInfoのエンタイトルメント状態を基準にしてください。
表示を切り替える2つの手段:PlacementとOffering metadata
どのペイウォールを出すかは、PlacementとOffering metadataの組み合わせで制御できます。両者は役割が異なります。
- Placement:ジャーニー上の表示位置を表し、位置ごとに別のOfferingを配信する。
- Offering metadata:Offeringに付随する追加情報。アプリ側が読むことで、カスタムUIかホスト型Paywallかを切り替えられる。
Placementだけで「どこで見せるか」は決まりますが、「どちらのUIで見せるか」はmetadata側の判断になります。両方を併用すると、位置とUIの選択を独立して運用できます。
Placementの例としては、オンボーディング終了時(onboarding_end)、有料機能を使おうとしたとき(feature_gate)、セール実施中(sale_offer)などが考えられます。設計の出発点は、理想のカスタマージャーニーをどう補完するかを描くことです。セール中であれば、初回ユーザーと既存ユーザーで見せるオファーやコピーが変わるかもしれません。その場合はsale_offerというPlacementを切ります。
アプリがPlacementを指定してOfferingsを取得すると、サブスクリプション基盤はそのPlacementとユーザーに応じたOfferingを返します。
- Swift版のPlacement指定:code0007
- Kotlin版のPlacement指定:code0008
Offering metadataの設定と読み取り
カスタムUIに何を表示するかを柔軟に変える鍵がOffering metadataです。ダッシュボードで対象のOfferingを開き、「Edit」または「Configure metadata」からMetadataフィールドに有効なJSONを追加します。たとえば次のような形式です。
- metadata設定例:code0009
このmetadataは、SDKでOfferingsを取得したときにOfferingデータへ紐づきます。アプリ側で値を読めば、表示方法を動的に切り替えられます。
metadataの値は本質的に任意です。ダッシュボードで未定義の場合でもアプリとペイウォールが正常に動くよう、必ずフォールバックを用意してください。
分岐ロジックの組み立て方
最後のステップは、カスタムUIとホスト型Paywallのどちらを描画するかを決める判定です。判定は1か所にまとめ、表示関数から切り離しておくと、テストや差し替えがしやすくなります。
判定の設計で押さえる点は次のとおりです。
- metadataの
custom_paywallのような真偽値は、未設定時にfalseへ倒す。 - 判定関数は「カスタムUIを出すか」だけを返し、実際の描画は別関数に任せる。
- どちらの分岐でも、プロダクト情報と購入処理は同じサブスクリプション基盤経路を通す。
判定と表示を分けた実装パターンは、次の契約モジュールに示しています。
- Swift版の分岐例:code0012
- Kotlin版の分岐例:code0013
metadataを読む段階の実装例はcode0010(Swift)とcode0011(Kotlin)にありますが、これらは公開用の契約モジュールではありません。実装時はSDKの現在のAPIシグネチャを公式ドキュメントで確認してください。
公開前チェックリスト
併用構成をリリースする前に、次の項目を確認してください。
- [ ] 価格・プロダクト名・初回オファーはすべてサブスクリプション基盤から取得した値で表示している。
- [ ] 購入はカスタムUIからもサブスクリプションSDK経由で実行している。
- [ ] コンテンツ解放の判定はCustomerInfoのエンタイトルメント状態を基準にしている。
- [ ] metadataが未設定のOfferingでも、既定のUIにフォールバックする。
- [ ] Placement名がダッシュボード側の設定と一致している。
- [ ] 購入キャンセル・エラー・復元の各経路で表示が破綻しない。
- [ ] A/Bテストを行う場合、比較対象のUIと計測指標を事前に決めている。
この分担を守れば、フロントエンドの表現は自社でコントロールしつつ、サブスクリプション基盤の処理をサブスクリプションSDKに委ねられます。iOSとAndroidの両方で同じ方針を適用すれば、プラットフォーム間の挙動のずれも抑えられます。
Frequently asked questions
カスタムペイウォールだけを使い、ホスト型Paywallを一切使わなくてもよいですか?
可能です。プロダクト取得・購入・エンタイトルメント管理をサブスクリプションSDKに任せれば、UIは完全に自前で構いません。併用構成は、ホスト型Paywallを比較対象や移行先として残したい場合に意味を持ちます。
PlacementとOffering metadataはどちらを使えばよいですか?
「ジャーニーのどこで見せるか」を分けたいならPlacement、「どのUIで見せるか」を切り替えたいならOffering metadataです。両方を組み合わせると、位置ごとに別のOfferingを配信しつつ、そのOfferingごとにUIの種類を指定できます。
metadataに値が入っていないOfferingがあると、アプリは壊れますか?
未設定時の既定値を決めておけば壊れません。たとえばcustom_paywallが存在しない場合はfalseとして扱い、ホスト型Paywall側にフォールバックする実装にします。metadataは任意の追加情報という前提で設計してください。
購入が成功したのにコンテンツが解放されないことがあるのはなぜですか?
購入完了とエンタイトルメントの有効化は別の判定です。画面の解放は購入コールバックの成否ではなく、CustomerInfoのエンタイトルメント状態を確認して決めてください。復元や更新のタイミングでも同じ判定を使うと、不整合を避けられます。
{
"custom_paywall": true,
}