Flutter SDKでのフローとペイウォールの取得を最適化する
Flutter でフローやペイウォールを確実に取得するには、次の3つが必要です:高速なレンダリング、オーディエンス対象のバリアントの返却、そしてネットワークが遅い場合のグレースフルなフォールバック。以下のルールでは、それを実現するためのタイミング・キャッシング・フォールバックパターンについて説明します。
このルールは、Adapty().activate() と Adapty().identify() がすでに完了していることを前提としています。詳細は Flutter SDK の呼び出し順序 を参照してください。
ルールと注意点
| これをやる | これをやらない | 理由 |
|---|---|---|
表示しようとしているプレースメントをフェッチするか、preloadFlows でキャッシュをウォームアップする(SDK 4.3.0+)。 | 起動時に独自の並行 getFlow 呼び出しを広げる。 | 手作りのプリフェッチバーストはメインスレッドをブロックし、ブラックスクリーンを引き起こす。preloadFlows はこのために設計されており、バッチをネイティブ SDK に一度の呼び出しで送信する。 |
アトリビューションが解決される機会を得た後に getFlow をフェッチする — たとえば、activate から 1〜2 秒後、または didUpdateProfileStream が発火した後。 | runApp の前に main() で getFlow を呼び出す。 | アトリビューションがまだ届いていない。フローはデフォルトのオーディエンスに対して解決され、セグメントや ASA パーソナライゼーションが暗黙的にバイパスされる。 |
loadTimeout を設定し、すべてのプレースメントにフォールバックペイウォールを設定する。 | getFlow を無制限に待つ。 | タイムアウトがないと、接続状況が悪いユーザーはネットワークが解決されるまで空白画面を見続けるか、アプリを閉じてしまう。 |
カスタムペイウォールとプロダクトの取得方法については カスタムペイウォールとプロダクトの取得 を、適切なプレースメントの選び方については プレースメント を参照してください。
プレースメントをプリロードする
preloadFlows および preloadFlowsForDefaultAudience は SDK バージョン 4.3.0 以降で利用できます。
preloadFlows はフローの JSON を事前にキャッシュします。その後は通常通り使用できます:フローの取得には getFlow、ビューの作成には createFlowView を使用します。
fetchPolicy は、後続の getFlow がどのレイヤーを最初に読み込むかを制御するものであり、キャッシュにアクセスできるかどうかを制御するものではありません:
AdaptyFlowFetchPolicy.returnCacheDataElseLoadはキャッシュ済みのコピーを最初に読み込み、キャッシュがない場合のみネットワークにアクセスします。AdaptyFlowFetchPolicy.returnCacheDataIfNotExpiredElseLoad(maxAge)は、コピーがmaxAgeより新しい間は同じ動作をします。- デフォルトの
AdaptyFlowFetchPolicy.reloadRevalidatingCacheDataは最初にネットワークにアクセスし、リクエストが失敗またはタイムアウトした場合にキャッシュ済みのコピーにフォールバックします。
プリロードはどのポリシーでも効果がありますが、動作は異なります。キャッシュファーストポリシーではリクエスト自体がなくなり、デフォルトポリシーではリクエストは残りつつウォームコピーがフォールバックとして使われます。テストデバイスでは、getFlow はどのポリシーでもキャッシュをスキップし、ネットワークリクエストが失敗した場合のみプリロード済みコピーを使用します。
セッションで必要になるプレースメントがわかっているが、まだ表示したくない場合に使用してください。たとえば、activate と identify が完了した直後に、ユーザーがまだタップしていないボタンの背後にあるフローを準備しておく場合などです。
try {
await Adapty().preloadFlows(
placementIds: ['onboarding', 'main_paywall'],
loadTimeout: const Duration(seconds: 5),
);
} on AdaptyError catch (adaptyError) {
// at least one placement failed to preload
}
// Later, when the user reaches the paywall:
final flow = await Adapty().getFlow(
placementId: 'main_paywall',
fetchPolicy: AdaptyFlowFetchPolicy.returnCacheDataElseLoad,
);
パラメーター:
placementIds(必須):プリロードするプレースメント。loadTimeout(任意):オーディエンスターゲティングされたフローのプリロード待機時間。デフォルトは5秒で、1秒未満の値は1秒に引き上げられます。タイムアウトに達した場合、SDKはデフォルトオーディエンスのフローを代わりに読み込むことがあります。
知っておくべき動作:
- すべてのプレースメントの試行が完了してから、失敗したすべてのプレースメントをまとめた1つの
AdaptyErrorでコールが失敗します。1つのプレースメントの失敗が他のプレースメントの処理を停止させることはなく、ロードに成功したプレースメントはキャッシュに残ります。 - プリロードは常にネットワークにアクセスします。独自の
fetchPolicyはありません。 - プリロードはキャッシュを温めるだけです。コンテンツを返すわけではないため、表示するには引き続き
getFlowを呼び出す必要があります。
プリロードの対象範囲
フローは段階的に画面に表示されます。プリロードは最初の段階をカバーします。これは getFlow が行う処理と同じです。
| レイヤー | 取得元 | プリロードによるウォーミング |
|---|---|---|
| フロー JSON — 選択されたバリアント、プロダクト ID、リモートコンフィグ | getFlow | あり |
| UI レイアウト — 画面の構造、スタイリング、テキスト | createFlowView | なし |
| 画像(動画要素の代替となる静止フレームを含む) | createFlowView(バックグラウンド) | なし |
| プロダクト | createFlowView または getPaywallProducts | なし |
| 動画ファイル | 画面レンダリング時にシステムプレーヤーが取得 | SDK ではキャッシュされない |
そのため、特定のレイアウトに対して最初に createFlowView を呼び出す際は、プリロード後であっても1回のラウンドトリップが発生します。その後、ネイティブ SDK はそのレイアウトをディスクキャッシュに保持します。このキャッシュはアプリの再起動後も保持されるため、コストが発生するのはすべてのリクエストではなく、最初のリクエスト時のみとなります。
オーディエンスのセグメンテーションをスキップする
オーディエンスのセグメンテーションを一切待たずにキャッシュをウォームアップするには、デフォルトオーディエンスのバリアントを使用します。タイムアウトは不要です:
await Adapty().preloadFlowsForDefaultAudience(placementIds: ['main_paywall']);
その後 getFlowForDefaultAudience を呼び出すと、getFlow が preloadFlows のコピーを読み取るのと同じ方法で、キャッシュされたコピーを読み取ります。
アプリバンドルから最初の画面のメディアを表示する
フローは画像や動画を Adapty からダウンロードします。最初の画面のメディアを即座に表示するには、アプリバンドルから直接提供してください。これは、既存のネイティブオンボーディングのビジュアルなど、すでに同梱しているメディアを再利用するのに便利な方法です。
- Flow & Paywall Builderで、画像または動画にカスタムメディアIDを設定します。そこでアップロードしたファイルはフォールバックとして使用されます。
- ファイルをFlutterのアセットに追加し、
pubspec.yamlのassetsに記載します。 - フロービューを作成する際に、
customAssetsでそのIDに対応するバンドルファイルを渡します。
// "welcome_video" は Flow & Paywall Builder で設定したカスタムメディア ID です
final bundledAssets = {
'welcome_video': AdaptyCustomAsset.localVideoAsset(
assetId: 'assets/videos/welcome.mp4',
),
};
try {
final view = await AdaptyUI().createFlowView(
flow: flow,
customAssets: bundledAssets,
);
} on AdaptyError catch (e) {
// handle the error
}
バンドルしたファイルはアプリのダウンロードサイズに影響するため、ユーザーが最初に目にするメディアのみをバンドルしてください。
バンドルされていないメディアも即座に表示されます。フローのレイアウトには各画像の低解像度コピー(動画のスチルフレームを含む)が含まれており、フルファイルが読み込まれるまでの間、それが表示されます。
customAssets の完全なリファレンスについては、アセットのカスタマイズを参照してください。
接続状況が悪い環境向けのチューニング
接続状況が常に悪い市場(農村部、交通機関、ルーティングの問題が発生する地域)向けの設定:
- 最初のフェッチ以外はすべて
fetchPolicy: AdaptyFlowFetchPolicy.returnCacheDataElseLoadを設定する。 - Adapty ダッシュボードのすべてのプレースメントにフォールバックペイウォールを設定する。
loadTimeoutを 3〜5 秒に設定し、タイムアウトが発生した場合はフォールバックを受け入れる。getProfile()の完了をフロー表示の条件にしない。getFlowは独立して呼び出すことで、プロファイルの取得が遅くても UI をブロックしないようにする。