Flutter SDK でオンボーディングを取得する

Adapty ダッシュボードのビルダーでオンボーディングのビジュアル部分をデザインしたら、Flutter アプリに表示できます。この処理の最初のステップは、以下で説明するように、プレースメントに関連付けられたオンボーディングとそのビュー設定を取得することです。

始める前に、次の点を確認してください。

Adapty Flutter SDK バージョン 3.8.0 以降がインストールされていること。
オンボーディングを作成していること。
オンボーディングをプレースメントに追加していること。

オンボーディングを取得する

ノーコードビルダーでオンボーディングを作成すると、アプリが取得して表示する必要のある設定を含むコンテナとして保存されます。このコンテナは、表示されるコンテンツ、表示方法、ユーザーのインタラクション（クイズの回答やフォームへの入力など）の処理方法といった、エクスペリエンス全体を管理します。また、コンテナは分析イベントを自動的に追跡するため、ビュートラッキングを別途実装する必要はありません。

パフォーマンスを最大限に発揮するため、ユーザーに表示する前に画像のダウンロードを完了できるよう、早めにオンボーディング設定を取得してください。

オンボーディングを取得するには、getOnboarding メソッドを使用します。

try {
  final onboarding = await Adapty().getOnboarding(placementId: "YOUR_PLACEMENT_ID");
} on AdaptyError catch (e) {
    //handle error
} catch (e) { 
    //handle error
}

次に、createOnboardingView メソッドを呼び出して、表示するビューを取得します。

createOnboardingView メソッドの結果は一度しか使用できません。再度使用する必要がある場合は、createOnboardingView メソッドを新たに呼び出してください。再作成せずに 2 回呼び出すと、AdaptyUIError.viewAlreadyPresented エラーが発生する場合があります。


try {
    final onboardingView = await Adapty().createOnboardingView(onboarding: onboarding);
} on AdaptyError catch (e) { 
    //handle error
} catch (e) { 
    //handle error
}

パラメーター：

パラメーター	必須/任意	説明
placementId	必須	目的のプレースメントの識別子。Adapty ダッシュボードでプレースメントを作成する際に指定した値です。
locale	任意デフォルト: `en`	オンボーディングのローカライズ識別子。このパラメーターは、マイナス（-）文字で区切られた 1 つまたは 2 つのサブタグで構成される言語コードを指定します。最初のサブタグは言語、2 番目のサブタグは地域を表します。例：`en` は英語、`pt-br` はブラジルポルトガル語を表します。
fetchPolicy	デフォルト: `.reloadRevalidatingCacheData`	デフォルトでは、SDK はサーバーからデータを読み込もうとし、失敗した場合はキャッシュされたデータを返します。このオプションを推奨します。ユーザーが常に最新のデータを取得できるためです。ただし、ユーザーが不安定なインターネット接続を使用していると考えられる場合は、`.returnCacheDataElseLoad` を使用して、キャッシュが存在する場合はキャッシュデータを返すことを検討してください。このシナリオでは、ユーザーが最新のデータを取得できない場合がありますが、インターネット接続が不安定な場合でも読み込み時間が短くなります。キャッシュは定期的に更新されるため、セッション中にネットワークリクエストを避けるために使用しても安全です。キャッシュはアプリの再起動後も保持され、アプリの再インストールまたは手動でのクリーンアップ時にのみ消去されます。 Adapty SDK はオンボーディングをローカルに 2 層で保存します。1 層目は上記の定期更新キャッシュで、2 層目はフォールバックオンボーディングです。また、CDN を使用してオンボーディングをより速く取得し、CDN が利用できない場合に備えたスタンドアロンのフォールバックサーバーも用意されています。このシステムは、インターネット接続が不安定な場合でも信頼性を確保しながら、常に最新バージョンのオンボーディングを取得できるように設計されています。
loadTimeout	デフォルト: 5 秒	このメソッドのタイムアウトを制限する値です。タイムアウトに達した場合、キャッシュデータまたはローカルフォールバックが返されます。この処理は内部で複数のリクエストで構成されている場合があるため、まれに `loadTimeout` で指定した時間よりも少し遅れてタイムアウトすることがあります。

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

パラメーター	説明
Onboarding	オンボーディングの識別子と設定、リモートコンフィグ、その他いくつかのプロパティを含む `AdaptyOnboarding` オブジェクト。

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

通常、オンボーディングはほぼ瞬時に取得されるため、このプロセスの高速化を心配する必要はありません。ただし、オーディエンスやオンボーディングが多数あり、ユーザーのインターネット接続が遅い場合、オンボーディングの取得に想定より時間がかかる場合があります。そのような状況では、オンボーディングをまったく表示しないよりも、スムーズなユーザー体験を確保するためにデフォルトのオンボーディングを表示したい場合があります。

この問題を解決するために、getOnboardingForDefaultAudience メソッドを使用できます。このメソッドは、指定されたプレースメントの All Users オーディエンス向けオンボーディングを取得します。ただし、推奨されるアプローチは、上記のオンボーディングを取得するセクションで説明したように、getOnboarding メソッドでオンボーディングを取得することです。

getOnboardingForDefaultAudience の代わりに getOnboarding の使用を検討してください。後者には重要な制限があります：

互換性の問題: 複数のアプリバージョンをサポートする際に問題が生じる場合があります。後方互換性のあるデザインが必要になるか、古いバージョンで表示が崩れる可能性を受け入れる必要があります。
パーソナライズなし: “All Users” オーディエンスのコンテンツのみ表示され、国、アトリビューション、またはカスタム属性に基づくターゲティングが行われません。

ユースケースにおいて高速なフェッチがこれらのデメリットを上回る場合は、以下に示すように getOnboardingForDefaultAudience を使用してください。それ以外の場合は、上記の説明に従って getOnboarding を使用してください。

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

パラメーター：

パラメーター必須/任意説明

placementId 必須目的のプレースメントの識別子。Adapty ダッシュボードでプレースメントを作成する際に指定した値です。

locale

任意

デフォルト: en

オンボーディングのローカライズ識別子。このパラメーターは、マイナス（-）文字で区切られた 1 つまたは 2 つのサブタグで構成される言語コードを指定します。最初のサブタグは言語、2 番目のサブタグは地域を表します。

例：en は英語、pt-br はブラジルポルトガル語を表します。

fetchPolicy

デフォルト: .reloadRevalidatingCacheData

デフォルトでは、SDK はサーバーからデータを読み込もうとし、失敗した場合はキャッシュされたデータを返します。このオプションを推奨します。ユーザーが常に最新のデータを取得できるためです。

ただし、ユーザーが不安定なインターネット接続を使用していると考えられる場合は、.returnCacheDataElseLoad を使用して、キャッシュが存在する場合はキャッシュデータを返すことを検討してください。このシナリオでは、ユーザーが最新のデータを取得できない場合がありますが、インターネット接続が不安定な場合でも読み込み時間が短くなります。キャッシュは定期的に更新されるため、セッション中にネットワークリクエストを避けるために使用しても安全です。

キャッシュはアプリの再起動後も保持され、アプリの再インストールまたは手動でのクリーンアップ時にのみ消去されます。

Adapty SDK はオンボーディングをローカルに 2 層で保存します。1 層目は上記の定期更新キャッシュで、2 層目はフォールバックオンボーディングです。また、CDN を使用してオンボーディングをより速く取得し、CDN が利用できない場合に備えたスタンドアロンのフォールバックサーバーも用意されています。このシステムは、インターネット接続が不安定な場合でも信頼性を確保しながら、常に最新バージョンのオンボーディングを取得できるように設計されています。