フローとペイウォールの取得 - Capacitor

フローまたはペイウォールビルダーのペイウォールをデザインしたら、モバイルアプリで表示できます。最初のステップは、プレースメントに紐づいたフローまたはペイウォールと、以下で説明するビュー設定を取得することです。

このトピックはフローおよびペイウォールビルダーでカスタマイズされたペイウォールに関するものです。ペイウォールを手動で実装している場合は、リモートコンフィグペイウォールのペイウォールとプロダクトをモバイルアプリで取得するトピックを参照してください。

モバイルアプリにフローとペイウォールを表示する前に（クリックして展開）

1. Adapty ダッシュボードでプロダクトを作成してください。
2. Adapty ダッシュボードでフロー/ペイウォールを作成し、プロダクトを追加してください。
3. Adapty ダッシュボードでプレースメントを作成し、フロー/ペイウォールを追加してください。
4. モバイルアプリに Adapty SDK をインストールしてください。

フローまたはペイウォールの取得

Flow Builder または Paywall Builder でフローやペイウォールを設計した場合、それをユーザーに表示するためにモバイルアプリのコードでレンダリングについて心配する必要はありません。このようなフローやペイウォールには、表示する内容と表示方法の両方が含まれています。ただし、プレースメントを通じてそのIDを取得し、ビュー設定を取得してから、モバイルアプリで表示する必要があります。 フローまたはペイウォールを取得し、そのビューを作成するのは、表示するよりもできるだけ前に行うことをおすすめします。createFlowView メソッドはビューの設定を読み込み、画像のダウンロードとキャッシュをバックグラウンドで開始します。早く呼び出すほど、ダウンロードが完了するまでの時間を確保できます。フローまたはペイウォールを表示するタイミングには、設定と画像がすでにキャッシュされて表示準備が整っている状態にできます。

フローまたはペイウォールを取得するには、getFlow メソッドを使用します。

try {
  const flow = await adapty.getFlow({
    placementId: 'YOUR_PLACEMENT_ID',
  });
  // the requested flow/paywall
} catch (error) {
  // handle the error
}

パラメーター:

パラメータ	必須/任意	説明
placementId	必須	取得したいプレースメントの識別子。Adapty ダッシュボードでプレースメントを作成する際に指定した値です。
fetchPolicy	デフォルト: 'reload_revalidating_cache_data'	オプションの params オブジェクト内で渡します。デフォルトでは、SDK はサーバーからデータを取得しようとし、失敗した場合はキャッシュされたデータを返します。この方式はユーザーが常に最新のデータを受け取れるため、推奨しています。 ただし、ユーザーのインターネット接続が不安定な場合は、'return_cache_data_else_load' を使用してキャッシュが存在すればそれを返すことを検討してください。この場合、絶対的に最新のデータが届かないことがありますが、回線状況に関わらず読み込みが速くなります。キャッシュは定期的に更新されるため、ネットワークリクエストを減らす目的でセッション中に使用しても安全です。 キャッシュはアプリを再起動しても保持され、アプリの再インストール時または手動でクリアした場合にのみ削除されます。 Adapty SDK はペイウォールをローカルに2層で保存しています。上記の定期更新されるキャッシュとフォールバックペイウォールです。また、ペイウォールをより速く取得するために CDN を使用し、CDN に到達できない場合に備えてスタンドアロンのフォールバックサーバーも用意しています。このシステムは、インターネット接続が不安定な場合でも常に最新バージョンのペイウォールを取得できるよう設計されています。
loadTimeoutMs	デフォルト: 5秒	オプションの params オブジェクト内で渡します。このメソッドのタイムアウト上限を設定します。タイムアウトに達した場合、キャッシュされたデータまたはローカルフォールバックが返されます。 まれに、内部で複数のリクエストが実行されるため、このメソッドが loadTimeoutMs に指定した時間よりわずかに遅れてタイムアウトする場合があります。
プロダクトIDをハードコードしないでください。 ハードコードすべきIDはプレースメントIDのみです。フローとペイウォールはリモートで設定されるため、プロダクトの数や利用可能なオファーはいつでも変更される可能性があります。アプリはこれらの変更を動的に処理する必要があります。今日ペイウォールが2つのプロダクトを返し、明日3つを返しても、コードを変更せずにすべて表示できるようにしてください。

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

パラメータ	説明
Flow	フローの識別子（id、variationId）、名前、プレースメント、ペイウォールのバリアント（paywalls）、リモートコンフィグ（remoteConfigs）を持つ AdaptyFlow オブジェクト。

ビュー設定を取得する

プレースメントが Flow Builder または Paywall Builder でデザインされている場合、Adapty が UI をレンダリングします。createFlowView でビューを作成し、フローまたはペイウォールを表示してください。プレースメントがビルダー UI のないカスタムペイウォールの場合は、代わりにリモートコンフィグペイウォールとして処理してください。 Capacitor SDK では、createFlowView を直接呼び出すことができます。事前にビューの設定を取得する必要はありません。

try {
  const view = await createFlowView(flow);
} catch (error) {
  // handle the error
}

パラメーター:

パラメーター	必須/任意	説明
flow	必須	目的のフロー/ペイウォールのコントローラーを取得するための AdaptyFlow オブジェクト。
customTags	任意	カスタムタグとその解決済みの値の辞書を定義します。カスタムタグはコンテンツ内のプレースホルダーとして機能し、フロー/ペイウォール内のパーソナライズされたコンテンツに対して特定の文字列に動的に置き換えられます。詳細については、ペイウォールビルダーのカスタムタグに関するトピックを参照してください。
prefetchProducts	任意	画面上のプロダクト表示タイミングを最適化するために有効にします。true の場合、AdaptyUI は必要なプロダクトを自動的に取得します。デフォルト: true。
android.enableSafeArea	任意	Android のみ（iOS では無視されます）。android キーの下にネストされます。true の場合、フロービューにセーフエリアのパディングが適用されます。デフォルト: true。デフォルト設定はほとんどのケースに適しています。

ビューを取得したら、フロー/ペイウォールを表示してください。

デフォルトオーディエンスのフローまたはペイウォールをより速く取得する

通常、フローやペイウォールはほぼ瞬時に取得されるため、この処理を高速化することを気にする必要はありません。ただし、オーディエンスやプレースメントの数が多く、ユーザーのインターネット接続が不安定な場合は、フローやペイウォールの取得に予想以上の時間がかかることがあります。そのような場合、何も表示しないよりもスムーズなユーザー体験を確保するために、デフォルトのフローまたはペイウォールを表示したいことがあるでしょう。 これに対処するには、getFlowForDefaultAudience メソッドを使用できます。このメソッドは、指定したプレースメントの All Users オーディエンスに対応するフローまたはペイウォールを取得します。ただし、推奨されるアプローチは getFlow メソッドでフローまたはペイウォールを取得することであり、詳細は上記の フロー/ペイウォールの取得 セクションを参照してください。

try {
  const flow = await adapty.getFlowForDefaultAudience({
    placementId: 'YOUR_PLACEMENT_ID',
  });
  // the requested flow/paywall
} catch (error) {
  // handle the error
}

パラメーター	必須/任意	説明
placementId	必須	プレースメントの識別子です。Adapty ダッシュボードでプレースメントを作成する際に指定した値です。
fetchPolicy	デフォルト: 'reload_revalidating_cache_data'	省略可能な params オブジェクト内に渡します。デフォルトでは、SDK はサーバーからデータを読み込もうとし、失敗した場合はキャッシュされたデータを返します。ユーザーが常に最新のデータを受け取れるよう、この設定を推奨します。 ただし、ユーザーがネットワーク環境の不安定な状況を頻繁に経験する場合は、'return_cache_data_else_load' を使用してキャッシュが存在するときはキャッシュデータを返すことを検討してください。この場合、ユーザーが最新データを取得できないことがありますが、ネットワーク状況に関わらず読み込み時間が短縮されます。キャッシュはセッション中に定期的に更新されるため、ネットワークリクエストを避ける目的でキャッシュを使用しても安全です。 なお、キャッシュはアプリを再起動しても保持され、アプリの再インストール時または手動でクリアした場合にのみ削除されます。

アセットのカスタマイズ

フロー/ペイウォールの画像や動画をカスタマイズするには、カスタムアセットを実装します。

ヒーロー画像とヒーロー動画には事前定義されたID（hero_image と hero_video）があります。カスタムアセットバンドルでは、これらのIDを使って各要素を指定し、動作をカスタマイズします。

その他の画像や動画については、Adapty ダッシュボードでカスタムIDを設定する必要があります。

たとえば、次のようなことができます：

• 一部のユーザーに異なる画像や動画を表示する。
• リモートのメイン画像の読み込み中に、ローカルのプレビュー画像を表示する。
• 動画の再生前にプレビュー画像を表示する。 カスタムアセットをシンプルなディクショナリで指定する例を以下に示します。

const customAssets: Record<string, AdaptyCustomAsset> = {
  'custom_image': { type: 'image', relativeAssetPath: 'custom_image.png' },
  'hero_video': {
    type: 'video',
    fileLocation: {
      ios: { fileName: 'custom_video.mp4' },
      android: { relativeAssetPath: 'videos/custom_video.mp4' }
    }
  }
};

const view = await createFlowView(flow, { customAssets });

Adapty ダッシュボードの新しいペイウォールビルダーでペイウォールのビジュアル部分をデザインしたら、モバイルアプリでそれを表示できます。このプロセスの最初のステップは、以下で説明するように、プレースメントに関連付けられたペイウォールとそのビュー設定を取得することです。 このトピックは、ペイウォールビルダーでカスタマイズされたペイウォールに関するものです。リモートコンフィグのペイウォールを取得する方法については、モバイルアプリでリモートコンフィグのペイウォールとプロダクトを取得するを参照してください。

モバイルアプリでペイウォールを表示する前に（クリックして展開）

1. Adapty ダッシュボードでプロダクトを作成する。
2. Adapty ダッシュボードでペイウォールを作成し、プロダクトを追加する。
3. Adapty ダッシュボードでプレースメントを作成し、ペイウォールを追加する。
4. モバイルアプリに Adapty SDK をインストールする。

ペイウォールビルダーで作成したペイウォールの取得

ペイウォールビルダーを使ってペイウォールをデザインした場合、モバイルアプリのコードでレンダリングしてユーザーに表示する必要はありません。このようなペイウォールには、表示内容と表示方法の両方が含まれています。ただし、プレースメントを通じてペイウォールのIDを取得し、ビュー設定を行ったうえで、モバイルアプリ内に表示する必要があります。 最適なパフォーマンスを確保するために、ペイウォールとそのビュー設定をできるだけ早く取得し、ユーザーに表示する前に画像のダウンロードが完了するための十分な時間を確保することが重要です。

ペイウォールを取得するには、getPaywall メソッドを使用します。

try {
  const paywall = await adapty.getPaywall({
    placementId: 'YOUR_PLACEMENT_ID',
    locale: 'en',
  });
  // the requested paywall
} catch (error) {
  // handle the error
}

パラメーター：

パラメーター	必須/任意	説明
placementId	必須	目的のプレースメントの識別子。Adapty ダッシュボードでプレースメントを作成する際に指定した値です。
locale	任意 デフォルト: en	ペイウォールのローカライズの識別子。このパラメーターは、マイナス（-）文字で区切られた1つまたは2つのサブタグで構成される言語コードである必要があります。最初のサブタグは言語、2番目のサブタグは地域を表します。 例：en は英語、pt-br はブラジルポルトガル語を表します。 ロケールコードとその推奨される使用方法については、ローカライズとロケールコードを参照してください。
params	任意	ペイウォールを取得するための追加パラメーター。
プロダクトIDをハードコードしないでください。 ハードコードしてよいのはプレースメントIDだけです。ペイウォールはリモートで設定されるため、プロダクト数や利用可能なオファーはいつでも変更される可能性があります。アプリはこれらの変更を動的に処理する必要があります。今日は2つのプロダクトが返ってきて、明日は3つになったとしても、コードを変更せずにすべてを表示できるようにしてください。

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

パラメーター	説明
Paywall	プロダクトIDのリスト、ペイウォール識別子、リモートコンフィグ、その他のプロパティを含む AdaptyPaywall オブジェクト。

ペイウォールビルダーで作成したペイウォールのビュー設定を取得する

ペイウォールを取得したら、ViewConfiguration が含まれているかどうかを確認してください。これが存在する場合、ペイウォールビルダーで作成されたペイウォールであることを示します。この情報をもとに、ペイウォールの表示方法を決定します。ViewConfiguration が存在する場合はペイウォールビルダーのペイウォールとして扱い、存在しない場合はリモートコンフィグのペイウォールとして処理してください。

Capacitor SDK では、ビュー設定を手動で取得することなく、直接 createPaywallView メソッドを呼び出してください。

if (paywall.hasViewConfiguration) {
  try {
    const view = await createPaywallView(paywall);
  } catch (error) {
    // handle the error
  }
} else {
  // use your custom logic
}

パラメーター：

パラメータ	必須/任意	説明
paywall	必須	目的のペイウォールのコントローラーを取得するための AdaptyPaywall オブジェクト。
customTags	任意	カスタムタグとその解決済みの値の辞書を定義します。カスタムタグはペイウォールコンテンツ内のプレースホルダーとして機能し、ペイウォール内のパーソナライズされたコンテンツ向けに特定の文字列へ動的に置換されます。詳細はペイウォールビルダーのカスタムタグのトピックを参照してください。
prefetchProducts	任意	画面上のプロダクト表示タイミングを最適化するために有効にします。true の場合、AdaptyUI は必要なプロダクトを自動的に取得します。デフォルト: false。

ビューを取得したら、ペイウォールを表示します。

デフォルトオーディエンス向けペイウォールを取得してより速く表示する

通常、ペイウォールはほぼ瞬時に取得されるため、速度を気にする必要はありません。ただし、オーディエンスやペイウォールの数が多く、かつユーザーのインターネット接続が不安定な場合は、取得に想定以上の時間がかかることがあります。そのような状況では、ペイウォールをまったく表示しないよりも、デフォルトのペイウォールを表示してスムーズなユーザー体験を確保したい場合があります。 これに対処するには、getPaywallForDefaultAudience メソッドを使用できます。このメソッドは、All Users オーディエンス向けに指定されたプレースメントのペイウォールを取得します。ただし、推奨されるアプローチは getPaywall メソッドでペイウォールを取得することであり、詳細は上記のペイウォール情報を取得するセクションを参照してください。

try {
  const paywall = await adapty.getPaywallForDefaultAudience({
    placementId: 'YOUR_PLACEMENT_ID',
    locale: 'en',
  });
  // the requested paywall
} catch (error) {
  // handle the error
}

パラメータ	必須/任意	説明
placementId	必須	プレースメントの識別子です。Adapty ダッシュボードでプレースメントを作成する際に指定した値です。
locale	任意 デフォルト: en	ペイウォールのローカライゼーションの識別子です。このパラメータは、マイナス（-）文字で区切られた1つ以上のサブタグで構成される言語コードを指定します。最初のサブタグは言語を、2番目のサブタグは地域を表します。 例: en は英語、pt-br はブラジルポルトガル語を表します。 ロケールコードおよび推奨される使用方法については、ローカライゼーションとロケールコードを参照してください。
params	任意	ペイウォールを取得するための追加パラメータです。

アセットのカスタマイズ

ペイウォール内の画像や動画をカスタマイズするには、カスタムアセットを実装します。

ヒーロー画像と動画には事前定義されたIDがあります：hero_image と hero_video です。カスタムアセットバンドルでは、これらのIDを使って対象の要素を指定し、動作をカスタマイズします。

その他の画像や動画については、Adapty ダッシュボードでカスタムIDを設定する必要があります。

たとえば、次のようなことができます：

• 一部のユーザーに別の画像や動画を表示する。
• リモートのメイン画像の読み込み中にローカルのプレビュー画像を表示する。
• 動画再生前にプレビュー画像を表示する。 以下は、シンプルなディクショナリーを使ってカスタムアセットを提供する例です：

const customAssets: Record<string, AdaptyCustomAsset> = {
  'custom_image': { type: 'image', relativeAssetPath: 'custom_image.png' },
  'hero_video': {
    type: 'video',
    fileLocation: {
      ios: { fileName: 'custom_video.mp4' },
      android: { relativeAssetPath: 'videos/custom_video.mp4' }
    }
  }
};

view = await createPaywallView(paywall, { customAssets });