Capacitor SDKでカスタムペイウォールとプロダクトを取得する

カスタムペイウォールを表示する前に、それらに関する情報を取得する必要があります。このトピックはカスタムペイウォールに関するものです。Flow & Paywall Builder や old Paywall Builder でカスタマイズしたフローやペイウォールの取得については、フローとペイウォールおよびその設定を取得するを参照してください。

モバイルアプリでフローとプロダクトの取得を始める前に（クリックして展開）

1. Adapty ダッシュボードでプロダクトを作成する。

2. Adapty ダッシュボードでフローまたはペイウォールを作成し、プロダクトを追加する。

3. Adapty ダッシュボードでプレースメントを作成し、フローまたはペイウォールをプレースメントに追加する。

4. モバイルアプリに Adapty SDK をインストールする。

フローの情報を取得する

Adapty では、プロダクトはApp StoreとGoogle Play両方のプロダクトを組み合わせたものです。これらのクロスプラットフォームのプロダクトはフローやペイウォールに統合されており、モバイルアプリ内の特定のプレースメントで表示できます。

プロダクトを表示するには、getFlow メソッドを使って、いずれかのプレースメントから AdaptyFlow を取得する必要があります。

try {
  const flow = await adapty.getFlow({ 
    placementId: 'YOUR_PLACEMENT_ID', 
    params: {
      fetchPolicy: 'reload_revalidating_cache_data', // Load from server, fallback to cache
      loadTimeoutMs: 5000 // 5 second timeout
    }
  });
  // the requested flow
} catch (error) {
  console.error('Failed to fetch flow:', error);
}

パラメーター	必須/任意	説明
placementId	必須	プレースメントの識別子。Adapty ダッシュボードでプレースメントを作成する際に指定した値です。
params.fetchPolicy	任意 デフォルト: 'reload_revalidating_cache_data'	fetchPolicy は、SDK がキャッシュを使用できるかどうかではなく、どのレイヤーを最初に読み取るかを設定します。デフォルトでは、SDK はまずサーバーにアクセスし、リクエストが失敗した場合にキャッシュデータを返します。ユーザーが常に最新のデータを取得できるため、このオプションを推奨します。 ただし、ユーザーが不安定なインターネット環境にあると思われる場合は、'return_cache_data_else_load' の使用を検討してください。この設定は順序を逆にして、まずキャッシュを読み取り、キャッシュがない場合にのみサーバーにアクセスします。ユーザーは必ずしも最新のデータを取得できるわけではありませんが、インターネット接続が不安定な場合でも高速な読み込みを実現できます。キャッシュは定期的に更新されるため、ネットワークリクエストを避けるためにセッション中に使用しても安全です。 3つ目のポリシー 'return_cache_data_if_not_expired_else_load' は、両者の中間に位置します。キャッシュのコピーが一緒に渡す maxAgeSeconds より新しい間はキャッシュを最初に読み取り、古くなったらサーバーにアクセスします。 キャッシュはアプリを再起動しても保持され、アプリのアンインストール時または手動でクリアした場合にのみ消去されます。 Adapty SDK はフローとペイウォールを2つのレイヤーに保存します。上記の定期更新されるキャッシュとフォールバックペイウォールです。また、フローとペイウォールをより高速に取得するために CDN を使用し、CDN に到達できない場合に備えてスタンドアロンのフォールバックサーバーも使用します。このシステムは、インターネット接続が不安定な場合でも信頼性を確保しながら、常にフローの最新バージョンを取得できるよう設計されています。
params.loadTimeoutMs	任意 デフォルト: 5000 ms	この値は、このメソッドのタイムアウト（ミリ秒単位）を制限します。タイムアウトに達した場合、キャッシュデータまたはローカルフォールバックが返されます。 このメソッドは、内部で異なるリクエストで構成される場合があるため、loadTimeoutMs で指定した時間よりわずかに遅れてタイムアウトすることがまれにあります。

プロダクト ID をハードコードしないでください！フローはリモートで設定されるため、利用可能なプロダクト、プロダクトの数、特別オファー（無料トライアルなど）は随時変更される可能性があります。コードがこれらのシナリオに対応できるようにしてください。

たとえば、最初に 2 つのプロダクトを取得した場合、アプリはその 2 つを表示する必要があります。その後 3 つのプロダクトを取得した場合は、コードを変更することなく 3 つすべてを表示できるようにしてください。ハードコードする必要があるのはプレースメント ID だけです。

レスポンスパラメーター：

パラメーター	説明
Flow	プレースメント、識別子（id、variationId）、名前、ペイウォールのバリアント（paywalls）、および設定済みロケールごとに1エントリの remoteConfigs 配列を含む AdaptyFlow オブジェクト。フローのプロダクトを取得するには、getPaywallProducts({ flow }) を呼び出してください。

プロダクトの取得

フローを取得したら、それに対応するプロダクトの配列を取得できます。

try {
  const products = await adapty.getPaywallProducts({ flow });
  // the requested products list
} catch (error) {
  console.error('Failed to fetch products:', error);
}

レスポンスパラメーター:

パラメータ	説明
Products	AdaptyPaywallProduct オブジェクトのリストで、プロダクト識別子、プロダクト名、価格、通貨、サブスクリプション期間、その他のプロパティが含まれます。

独自のペイウォールデザインを実装する際には、AdaptyPaywallProduct オブジェクトから以下のプロパティにアクセスする必要があります。よく使用されるプロパティを以下に示しますが、利用可能なすべてのプロパティの詳細については、リンク先のドキュメントを参照してください。

プロパティ	説明
Title	プロダクトのタイトルを表示するには、product.localizedTitle を使用します。ローカライズはデバイスのロケールではなく、ユーザーが選択したストアの国に基づきます。
Price	ローカライズされた価格を表示するには、product.price?.localizedString を使用します。このローカライズはデバイスのロケール情報に基づきます。product.price?.amount を使うと、数値として価格を取得することもできます。値はローカル通貨で提供されます。関連する通貨記号を取得するには、product.price?.currencySymbol を使用します。
Subscription Period	サブスクリプション期間（週・月・年など）を表示するには、product.subscription?.localizedSubscriptionPeriod を使用します。このローカライズはデバイスのロケールに基づきます。サブスクリプション期間をプログラムで取得するには、product.subscription?.subscriptionPeriod を使用します。ここから unit プロパティにアクセスすると、期間の単位（'day'・'week'・'month'・'year'・'unknown'）を取得できます。numberOfUnits の値で期間の単位数を取得できます。たとえば四半期ごとのサブスクリプションの場合、unit プロパティは 'month'、numberOfUnits は 3 となります。
Introductory Offer	サブスクリプションに初回オファーが含まれているかどうかをバッジなどで示すには、product.subscription?.offer?.phases プロパティを確認してください。これは最大2つの割引フェーズ（無料トライアルフェーズと初回価格フェーズ）を含むリストです。各フェーズオブジェクトには以下の便利なプロパティがあります： • paymentMode：'free_trial'・'pay_as_you_go'・'pay_up_front'・'unknown' のいずれかの値を持つ文字列です。無料トライアルは 'free_trial' タイプになります。 • price：数値としての割引価格です。無料トライアルの場合は 0 になります。 • localizedNumberOfPeriods：オファーの期間をデバイスのロケールでローカライズした文字列です。たとえば3日間のトライアルオファーの場合、このフィールドには '3 days' と表示されます。 • subscriptionPeriod：オファー期間の個別の詳細を取得するには、このプロパティを使用します。オファーに対しても、前のセクションで説明したのと同じように機能します。 • localizedSubscriptionPeriod：ユーザーのロケールに合わせてフォーマットされた割引のサブスクリプション期間です。

デフォルトオーディエンスのフローでフロー取得を高速化する

通常、フローはほぼ瞬時に取得されるため、この処理を高速化することを心配する必要はありません。ただし、オーディエンスやプレースメントの数が多く、ユーザーの通信環境が悪い場合は、フローの取得に想定以上の時間がかかることがあります。そのような状況では、何も表示しないよりも、デフォルトのフローを表示してスムーズなユーザー体験を提供したい場合があるでしょう。

この問題に対処するには、getFlowForDefaultAudience メソッドを使用できます。このメソッドは、指定されたプレースメントの All Users オーディエンスのフローを取得します。ただし、推奨されるアプローチは getFlow メソッドでフローを取得することである点を十分に理解してください。詳細は上記のフロー情報の取得セクションを参照してください。

try {
  const flow = await adapty.getFlowForDefaultAudience({ 
    placementId: 'YOUR_PLACEMENT_ID', 
    params: {
      fetchPolicy: 'reload_revalidating_cache_data' // Load from server, fallback to cache
    }
  });
  // the requested flow
} catch (error) {
  console.error('Failed to fetch default audience flow:', error);
}

パラメーター	必須/任意	説明
placementId	必須	プレースメントの識別子。Adapty ダッシュボードでプレースメントを作成する際に指定した値です。
params.fetchPolicy	任意 デフォルト: 'reload_revalidating_cache_data'	fetchPolicy は、SDK がどのレイヤーを最初に読み取るかを設定するもので、キャッシュを使用できるかどうかを設定するものではありません。デフォルトでは、SDK はまずサーバーにアクセスし、そのリクエストが失敗した場合にキャッシュされたデータを返します。ユーザーが常に最新のデータを取得できるため、この設定を推奨します。 ただし、ユーザーが不安定なインターネット環境に置かれていると思われる場合は、'return_cache_data_else_load' の使用を検討してください。この設定は順序を逆にし、まずキャッシュを読み取り、キャッシュに何もない場合にのみサーバーにアクセスします。最新のデータが得られない可能性はありますが、インターネット接続が不安定な場合でも、より速いロード時間を実現できます。キャッシュは定期的に更新されるため、ネットワークリクエストを避けるためにセッション中にキャッシュを使用しても安全です。 3 番目のポリシー 'return_cache_data_if_not_expired_else_load' は、その中間に位置します。キャッシュされたコピーが一緒に渡す maxAgeSeconds より新しい間はキャッシュを最初に読み取り、古くなるとサーバーにアクセスします。 キャッシュはアプリを再起動しても保持され、アプリを再インストールするか手動でクリーンアップした場合にのみ消去されます。

カスタムペイウォールを表示する前に、それらに関する情報を取得する必要があります。このトピックはカスタムペイウォールに関するものです。ペイウォールビルダーでカスタマイズされたペイウォールの取得方法については、ペイウォールビルダーのペイウォールとその設定を取得するを参照してください。

モバイルアプリでペイウォールとプロダクトの取得を開始する前に（クリックして展開）

1. Adapty ダッシュボードでプロダクトを作成する。

2. ペイウォールを作成し、プロダクトをペイウォールに組み込む（Adapty ダッシュボード内）。

3. プレースメントを作成し、ペイウォールをプレースメントに組み込む（Adapty ダッシュボード内）。

4. Adapty SDK をインストールする（モバイルアプリ内）。

ペイウォール情報の取得

Adapty では、プロダクトはApp StoreとGoogle Playの両方のプロダクトを組み合わせたものです。これらのクロスプラットフォームのプロダクトはペイウォールに統合されており、モバイルアプリの特定のプレースメント内で表示できます。

プロダクトを表示するには、getPaywall メソッドを使ってプレースメントのいずれかからペイウォールを取得する必要があります。

try {
  const paywall = await adapty.getPaywall({ 
    placementId: 'YOUR_PLACEMENT_ID', 
    locale: 'en',
    params: {
      fetchPolicy: 'reload_revalidating_cache_data', // Load from server, fallback to cache
      loadTimeoutMs: 5000 // 5 second timeout
    }
  });
  // the requested paywall
} catch (error) {
  console.error('Failed to fetch paywall:', error);
}

パラメーター	必須/任意	説明
placementId	必須	プレースメントの識別子。Adapty ダッシュボードでプレースメントを作成する際に指定した値です。
locale	任意 デフォルト: en	ペイウォールのローカライズの識別子。このパラメーターは、マイナス（-）文字で区切られた1つ以上のサブタグで構成された言語コードである必要があります。最初のサブタグは言語を、2番目のサブタグは地域を表します。 例: en は英語、pt-br はブラジルポルトガル語を表します。 ロケールコードとその推奨される使用方法については、ローカライズとロケールコードをご覧ください。
params.fetchPolicy	任意 デフォルト: 'reload_revalidating_cache_data'	fetchPolicy は、SDKがどのレイヤーを最初に読み込むかを設定するものであり、キャッシュを使用できるかどうかを制御するものではありません。デフォルトでは、SDKは最初にサーバーにアクセスし、そのリクエストが失敗した場合にキャッシュデータを返します。ユーザーが常に最新のデータを取得できるため、この設定を推奨します。 ただし、ユーザーがインターネット接続の不安定な環境にいる場合は、'return_cache_data_else_load' の使用を検討してください。この設定では順序が逆になり、最初にキャッシュを読み込み、キャッシュに何もない場合のみサーバーにアクセスします。ユーザーが最新のデータを取得できない場合がありますが、インターネット接続が不安定でも高速な読み込みを体験できます。キャッシュは定期的に更新されるため、ネットワークリクエストを避けるためにセッション中に使用しても安全です。 3つ目のポリシー 'return_cache_data_if_not_expired_else_load' は、両者の中間に位置します。キャッシュされたコピーが一緒に渡す maxAgeSeconds より新しい間はキャッシュを最初に読み込み、古くなった場合はサーバーにアクセスします。 キャッシュはアプリを再起動しても保持され、アプリの再インストール時または手動でクリアした場合にのみ削除されます。
params.loadTimeoutMs	任意 デフォルト: 5000 ms	このメソッドのタイムアウト（ミリ秒単位）を制限する値です。タイムアウトに達した場合、キャッシュデータまたはローカルフォールバックが返されます。 このメソッドは内部で複数のリクエストで構成される場合があるため、まれに loadTimeoutMs で指定した時間よりわずかに遅れてタイムアウトすることがあります。

プロダクトIDをハードコードしないでください。 ハードコードすべきIDはプレースメントIDのみです。ペイウォールはリモートで設定されるため、プロダクトの数や利用可能なオファーはいつでも変わる可能性があります。アプリはこれらの変更を動的に処理する必要があります。たとえば、今日のペイウォールが2つのプロダクトを返し、明日3つを返す場合でも、コードを変更せずにすべて表示できるようにしてください。

レスポンスパラメーター:

パラメータ	説明
Paywall	プロダクトIDのリスト、ペイウォールID、リモートコンフィグ、およびその他のプロパティを持つ AdaptyPaywall オブジェクト。

プロダクトを取得する

ペイウォールを取得したら、それに対応するプロダクトの配列を取得できます：

try {
  const products = await adapty.getPaywallProducts({ paywall });
  // the requested products list
} catch (error) {
  console.error('Failed to fetch products:', error);
}

レスポンスパラメーター：

パラメータ	説明
Products	AdaptyPaywallProduct オブジェクトのリスト。プロダクト識別子、プロダクト名、価格、通貨、サブスクリプション期間、その他いくつかのプロパティを含みます。

独自のペイウォールデザインを実装する場合、AdaptyPaywallProduct オブジェクトの以下のプロパティが必要になります。よく使われるプロパティを以下に示しますが、利用可能なすべてのプロパティの詳細については、リンク先のドキュメントを参照してください。

プロパティ	説明
タイトル	プロダクトのタイトルを表示するには、product.localizedTitle を使用します。ローカライズはデバイスのロケールではなく、ユーザーが選択したストアの国に基づいて行われます。
価格	ローカライズされた価格を表示するには、product.price?.localizedString を使用します。このローカライズはデバイスのロケール情報に基づいています。product.price?.amount を使って数値としての価格にアクセスすることもできます。値はローカル通貨で提供されます。関連する通貨記号を取得するには、product.price?.currencySymbol を使用します。
サブスクリプション期間	期間（週、月、年など）を表示するには、product.subscription?.localizedSubscriptionPeriod を使用します。このローカライズはデバイスのロケールに基づいています。プログラムでサブスクリプション期間を取得するには、product.subscription?.subscriptionPeriod を使用します。ここから unit プロパティにアクセスして長さ（'day'、'week'、'month'、'year'、'unknown' のいずれか）を取得できます。numberOfUnits の値で期間の単位数を取得できます。たとえば、四半期ごとのサブスクリプションの場合、unit プロパティには 'month'、numberOfUnits プロパティには 3 が表示されます。
初回オファー	サブスクリプションに初回オファーが含まれていることを示すバッジやインジケーターを表示するには、product.subscription?.offer?.phases プロパティを確認してください。これは最大2つの割引フェーズ（無料トライアルフェーズと初回価格フェーズ）を含むリストです。各フェーズオブジェクトには以下の便利なプロパティがあります： • paymentMode：'free_trial'、'pay_as_you_go'、'pay_up_front'、'unknown' のいずれかの値を持つ文字列。無料トライアルは 'free_trial' タイプになります。 • price：数値としての割引価格。無料トライアルの場合は 0 になります。 • localizedNumberOfPeriods：デバイスのロケールを使用してローカライズされた文字列で、オファーの期間を表します。たとえば、3日間のトライアルオファーの場合、このフィールドには '3 days' と表示されます。 • subscriptionPeriod：このプロパティを使ってオファー期間の個別の詳細を取得することもできます。オファーに対しても前のセクションで説明したのと同様の方法で機能します。 • localizedSubscriptionPeriod：ユーザーのロケールに合わせてフォーマットされた割引のサブスクリプション期間。

デフォルトオーディエンスのペイウォールでフェッチを高速化する

通常、ペイウォールはほぼ瞬時にフェッチされるため、この処理を高速化することを意識する必要はありません。ただし、オーディエンスやペイウォールの数が多く、ユーザーの通信環境が不安定な場合は、フェッチに想定より時間がかかることがあります。そのような状況では、ペイウォールがまったく表示されないよりも、デフォルトのペイウォールを表示してスムーズなユーザー体験を確保したいと思うでしょう。

これに対処するには、getPaywallForDefaultAudience メソッドを使用できます。このメソッドは、All Users オーディエンスに対して指定されたプレースメントのペイウォールを取得します。ただし、推奨されるアプローチは、上記の ペイウォール情報の取得 セクションで詳しく説明されているように、getPaywall メソッドでペイウォールを取得することである点を理解することが重要です。

try {
  const paywall = await adapty.getPaywallForDefaultAudience({ 
    placementId: 'YOUR_PLACEMENT_ID', 
    locale: 'en',
    params: {
      fetchPolicy: 'reload_revalidating_cache_data' // Load from server, fallback to cache
    }
  });
  // the requested paywall
} catch (error) {
  console.error('Failed to fetch default audience paywall:', error);
}

パラメータ	必須/任意	説明
placementId	必須	プレースメントの識別子。Adapty ダッシュボードでプレースメントを作成したときに設定した値です。
locale	任意 デフォルト: en	ペイウォールのローカライズの識別子。ハイフン（-）で区切られた1つ以上のサブタグからなる言語コードを指定します。最初のサブタグが言語、2番目が地域を表します。 例: en は英語、pt-br はブラジルポルトガル語を表します。 ロケールコードと推奨する使い方については、ローカライズとロケールコードをご覧ください。
params.fetchPolicy	任意 デフォルト: 'reload_revalidating_cache_data'	fetchPolicy は、SDKがどのレイヤーを最初に読み取るかを設定します（キャッシュを使用するかどうかではありません）。デフォルトではSDKはまずサーバーにアクセスし、リクエストが失敗した場合にキャッシュデータを返します。常に最新データをユーザーに届けられるため、この設定を推奨します。 ただし、ユーザーのインターネット環境が不安定だと思われる場合は、'return_cache_data_else_load' の使用を検討してください。この設定では順序が逆になり、まずキャッシュを読み取り、キャッシュが存在しない場合のみサーバーにアクセスします。常に最新データが得られるとは限りませんが、インターネット環境に関係なく読み込みが速くなります。キャッシュは定期的に更新されるため、セッション中のネットワークリクエストを減らす目的での使用も安全です。 3つ目のポリシー 'return_cache_data_if_not_expired_else_load' は両者の中間に位置します。キャッシュが maxAgeSeconds で指定した期間より新しい場合はキャッシュを優先して読み取り、古くなった場合はサーバーにアクセスします。 なお、キャッシュはアプリを再起動しても保持され、アプリを再インストールするか手動でクリアした場合にのみ削除されます。