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

フローまたはペイウォールビルダーのペイウォールを設計したら、モバイルアプリに表示できます。最初のステップは、以下に説明するように、プレースメントに関連付けられたフローまたはペイウォールとそのビュー設定を取得することです。

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

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

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

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

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

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

try {
  final flow = await Adapty().getFlow(placementId: 'YOUR_PLACEMENT_ID');
  // the requested flow/paywall
} on AdaptyError catch (adaptyError) {
  // handle the error
} catch (e) {
  // handle the error
}

パラメーター:

パラメーター	必須/任意	説明
placementId	必須	取得したいプレースメントの識別子。Adapty ダッシュボードでプレースメントを作成する際に指定した値です。
fetchPolicy	デフォルト: .reloadRevalidatingCacheData	デフォルトでは、SDK はサーバーからデータの取得を試み、失敗した場合はキャッシュされたデータを返します。この方式を推奨しているのは、常に最新のデータをユーザーに届けられるためです。 ただし、ユーザーが不安定なインターネット環境を利用していると考えられる場合は、.returnCacheDataElseLoad を使用することを検討してください。キャッシュが存在する場合はそちらを返す方式です。この場合、ユーザーが最新データを受け取れないことがありますが、通信状況が不安定でも高速に読み込めます。キャッシュは定期的に更新されるため、セッション中にネットワークリクエストを避ける目的で使用しても安全です。 なお、キャッシュはアプリを再起動しても保持され、アプリの再インストール時または手動でクリアした場合にのみ削除されます。 Adapty SDK はペイウォールを2つの層でローカルに保存しています。上述の定期更新されるキャッシュと、フォールバックペイウォールです。また、ペイウォールをより高速に取得するために CDN を使用し、CDN に接続できない場合に備えてスタンドアロンのフォールバックサーバーも用意しています。このシステムは、インターネット接続が不安定な状況でも信頼性を確保しながら、常に最新バージョンのペイウォールを提供できるよう設計されています。
loadTimeout	デフォルト: 5秒	このメソッドのタイムアウトを制限する Duration。タイムアウトに達した場合、キャッシュされたデータまたはローカルのフォールバックが返されます。 なお、内部で複数のリクエストが発生する場合があるため、まれに loadTimeout で指定した時間よりもわずかに遅れてタイムアウトすることがあります。
レスポンスパラメータ:
パラメーター	説明
:--------	:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Flow	フローの識別子（instanceIdentity、variationId）、名前、プレースメント、ペイウォールのバリアント（paywalls）、リモートコンフィグ（remoteConfigs）を含む AdaptyFlow オブジェクト。

ビューの設定を取得する

プレースメントが Flow Builder または Paywall Builder で設計されている場合、Adapty が UI をレンダリングします — 取得したフローの hasViewConfiguration プロパティが true になります。createFlowView でビューを作成し、フローまたはペイウォールを表示してください。プレースメントがビルダー UI のないカスタムペイウォール（hasViewConfiguration が false）の場合は、代わりにリモートコンフィグペイウォールとして処理してください。

try {
  final view = await AdaptyUI().createFlowView(flow: flow);
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}

パラメーター:

パラメータ	必須/任意	説明
flow	必須	対象のフロー/ペイウォールのビューを取得するための AdaptyFlow オブジェクト。
customTags	任意	カスタムタグとその解決済みの値のマップを定義します。カスタムタグはコンテンツ内のプレースホルダーとして機能し、フロー/ペイウォール内でパーソナライズされたコンテンツを提供するために特定の文字列に動的に置き換えられます。詳細については、ペイウォールビルダーのカスタムタグを参照してください。
preloadProducts	任意	画面上のプロダクト表示タイミングを最適化するために有効にします。true の場合、AdaptyUI は必要なプロダクトを自動的に取得します。デフォルト: false。
loadTimeout	任意	ビュー設定の読み込み時間を制限する Duration。タイムアウトに達した場合、キャッシュされたデータまたはローカルのフォールバックが使用されます。

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

デフォルトオーディエンスのフローまたはペイウォールを取得して高速化する

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

try {
  final flow = await Adapty().getFlowForDefaultAudience(placementId: 'YOUR_PLACEMENT_ID');
  // the requested flow/paywall
} on AdaptyError catch (adaptyError) {
  // handle error
} catch (e) {
  // handle unknown error
}

パラメーター	必須/任意	説明
placementId	必須	プレースメントの識別子です。Adapty ダッシュボードでプレースメントを作成する際に指定した値を使用してください。
fetchPolicy	デフォルト: .reloadRevalidatingCacheData	デフォルトでは、SDK はサーバーからデータを読み込もうとし、失敗した場合はキャッシュされたデータを返します。この方法を推奨します。ユーザーが常に最新のデータを取得できるためです。 ただし、ユーザーのインターネット環境が不安定だと考えられる場合は、.returnCacheDataElseLoad の使用を検討してください。キャッシュが存在する場合はキャッシュデータを返します。この場合、最新のデータが届かない可能性はありますが、接続状況に関わらず読み込みが速くなります。キャッシュはセッション中に定期的に更新されるため、ネットワークリクエストを減らす目的でキャッシュを利用しても問題ありません。 なお、キャッシュはアプリの再起動後も保持され、アプリの再インストール時または手動でクリアした場合にのみ削除されます。

アセットのカスタマイズ

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

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

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

たとえば、以下のようなことができます。

• 特定のユーザーに別の画像や動画を表示する。
• リモートのメイン画像の読み込み中に、ローカルのプレビュー画像を表示する。
• 動画を再生する前にプレビュー画像を表示する。 Here’s an example of how you can provide custom assets via a simple dictionary:

final customAssets = {
    // Show a local image using a custom ID
    'custom_image': AdaptyCustomAsset.localImageAsset(
        assetId: 'assets/images/image_name.png',
    ),

    // Show a local video with a preview image
    'hero_video': AdaptyCustomAsset.localVideoAsset(
        assetId: 'assets/videos/custom_video.mp4',
    ),
};

try {
  final view = await AdaptyUI().createFlowView(
    flow: flow,
    customAssets: customAssets,
  );
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}

カスタムタイマーの設定

モバイルアプリでカスタムタイマーを使用するには、customTimers マップを createFlowView メソッドに渡します。マップの各キーはタイマー ID で、その値はタイマーの終了時刻を定義する DateTime オブジェクトです。以下に例を示します：

try {
  final view = await AdaptyUI().createFlowView(
    flow: flow,
    customTimers: {
      'CUSTOM_TIMER_6H': DateTime.now().add(const Duration(seconds: 3600 * 6)),
      'CUSTOM_TIMER_NY': DateTime(2027, 1, 1), // New Year 2027
    },
  );
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}

この例では、CUSTOM_TIMER_NY と CUSTOM_TIMER_6H は、Adapty ダッシュボードで設定した開発者定義タイマーの Timer ID です。customTimers マップにより、アプリは各タイマーを正しい値で動的に更新します。例えば：

• CUSTOM_TIMER_NY: 元日など、タイマーの終了時刻までの残り時間。
• CUSTOM_TIMER_6H: ユーザーがフローを開いてから始まった 6 時間の残り時間。

Adapty ダッシュボードのペイウォールビルダーでペイウォールのビジュアル部分をデザインしたら、モバイルアプリに表示できます。まず、プレースメントに関連付けられたペイウォールとそのビュー設定を取得する必要があります。詳細は以下をご覧ください。

ペイウォールビルダーでカスタマイズしたペイウォールについての説明です。ペイウォールを手動で実装する場合は、リモートコンフィグペイウォールのペイウォールとプロダクトを取得するを参照してください。

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

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

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

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

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

try {
  final paywall = await Adapty().getPaywall(placementId: "YOUR_PLACEMENT_ID", locale: "en");
  // the requested paywall
} on AdaptyError catch (adaptyError) {
  // handle the error
} catch (e) {
}

パラメーター：

パラメータ	必須/任意	説明
placementId	必須	取得したいプレースメントの識別子です。Adapty ダッシュボードでプレースメントを作成する際に指定した値です。
locale	任意 デフォルト: en	ペイウォールのローカライズの識別子です。このパラメータは、マイナス（-）文字で区切られた1つまたは2つのサブタグで構成される言語コードを指定します。最初のサブタグは言語、2番目は地域を表します。 例: en は英語、pt-br はブラジルポルトガル語を表します。 ロケールコードや推奨される使用方法については、ローカライズとロケールコードをご覧ください。
fetchPolicy	デフォルト: .reloadRevalidatingCacheData	デフォルトでは、SDK はサーバーからデータの読み込みを試み、失敗した場合はキャッシュされたデータを返します。ユーザーが常に最新のデータを受け取れるため、この方法を推奨します。 ただし、ユーザーのインターネット接続が不安定な場合は、.returnCacheDataElseLoad を使用してキャッシュが存在する場合はキャッシュデータを返すことも検討してください。この場合、ユーザーが最新のデータを受け取れないことがありますが、通信状況に関わらず読み込みが速くなります。キャッシュは定期的に更新されるため、セッション中にネットワークリクエストを避ける目的で使用しても問題ありません。 キャッシュはアプリの再起動後も保持され、アプリの再インストール時または手動でのクリーンアップ時にのみクリアされます。 Adapty SDK はペイウォールをローカルに2つの層で保存します。1つは上記の定期更新キャッシュ、もう1つはフォールバックペイウォールです。またCDNを使用してペイウォールの取得を高速化し、CDNが利用できない場合に備えたスタンドアロンのフォールバックサーバーも用意しています。このシステムにより、インターネット接続が不安定な状況でも確実に最新のペイウォールを取得できるよう設計されています。
loadTimeout	デフォルト: 5秒	このメソッドのタイムアウト上限を設定します。タイムアウトに達した場合、キャッシュされたデータまたはローカルフォールバックが返されます。 内部で複数のリクエストが発生する場合があるため、まれに loadTimeout で指定した時間よりわずかに遅れてタイムアウトすることがあります。 Android の場合: 拡張関数（例: 5.seconds、.seconds は import com.adapty.utils.seconds から）を使用して TimeInterval を作成するか、TimeInterval.seconds(5) を使用できます。制限を設けない場合は TimeInterval.INFINITE を使用してください。
レスポンスパラメーター:
パラメータ	説明
:--------	:----------------------------------------------------------------------------------------------------------------------------------------------------------
Paywall	プロダクト ID のリスト、ペイウォール識別子、リモートコンフィグ、およびその他のプロパティを含む AdaptyPaywall オブジェクト。

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

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

try {
  final view = await AdaptyUI().createPaywallView(
        paywall: paywall,
      );
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}

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

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

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

try {
    final paywall = await Adapty().getPaywallForDefaultAudience(placementId: 'YOUR_PLACEMENT_ID');
} on AdaptyError catch (adaptyError) {
    // handle error
} catch (e) {
    // handle unknown error
}

パラメータ	必須/任意	説明
placementId	必須	プレースメントの識別子。Adapty ダッシュボードでプレースメントを作成する際に指定した値です。
locale	任意 デフォルト: en	ペイウォールのローカライズの識別子。このパラメータは、マイナス（-）文字で区切られた1つ以上のサブタグで構成される言語コードを指定します。最初のサブタグは言語、2番目のサブタグは地域を表します。 例: en は英語、pt-br はブラジルポルトガル語を表します。 ロケールコードの詳細と推奨される使用方法については、ローカライズとロケールコードを参照してください。
fetchPolicy	デフォルト: .reloadRevalidatingCacheData	デフォルトでは、SDK はサーバーからデータの読み込みを試み、失敗した場合はキャッシュされたデータを返します。ユーザーが常に最新のデータを取得できるため、この設定を推奨します。 ただし、ユーザーのインターネット接続が不安定な場合は、.returnCacheDataElseLoad を使用して、キャッシュが存在する場合はキャッシュされたデータを返すことを検討してください。この場合、最新データが取得できないことがありますが、接続状況に関わらず高速な読み込みが可能になります。キャッシュはセッション中も定期的に更新されるため、ネットワークリクエストを減らす目的で安全に使用できます。 なお、キャッシュはアプリの再起動後も保持され、アプリの再インストールまたは手動でのクリーンアップ時にのみ削除されます。

アセットのカスタマイズ

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

ヒーロー画像と動画には、あらかじめ hero_image および hero_video というIDが定義されています。カスタムアセットバンドルでは、これらのIDを使って各要素を指定し、動作をカスタマイズします。

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

たとえば、次のようなことが可能です。

• 一部のユーザーに別の画像や動画を表示する。
• リモートのメイン画像の読み込み中に、ローカルのプレビュー画像を表示する。
• 動画を再生する前にプレビュー画像を表示する。

カスタムアセットをシンプルなディクショナリ形式で提供する例を以下に示します。

final customAssets = {
    // Show a local image using a custom ID
    'custom_image': AdaptyCustomAsset.localImageAsset(
        assetId: 'assets/images/image_name.png',
    ),

    // Show a local video with a preview image
    'hero_video': AdaptyCustomAsset.localVideoAsset(
        assetId: 'assets/videos/custom_video.mp4',
    ),
};

try {
  final view = await AdaptyUI().createPaywallView(
    paywall: paywall,
    customAssets: customAssets,
  );
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}

カスタムタイマーの設定

モバイルアプリでカスタムタイマーを使用するには、createPaywallView メソッドに customTimers マップを渡します。マップの各キーはタイマーIDで、その値はタイマーの終了時刻を定義する DateTime オブジェクトです。以下に例を示します。

try {
  final view = await AdaptyUI().createPaywallView(
        paywall: paywall,
        customTimers: {
          'CUSTOM_TIMER_6H': DateTime.now().add(const Duration(seconds: 3600 * 6)),
          'CUSTOM_TIMER_NY': DateTime(2025, 1, 1), // New Year 2025
        },
      );
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}

この例では、CUSTOM_TIMER_NY と CUSTOM_TIMER_6H は、Adapty ダッシュボードで設定した開発者定義タイマーの Timer ID です。customTimers マップにより、アプリは各タイマーを正しい値で動的に更新します。例：

• CUSTOM_TIMER_NY: 元旦など、タイマーの終了時刻までの残り時間。
• CUSTOM_TIMER_6H: ユーザーがペイウォールを開いてから始まった6時間のうち、残りの時間。