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

オンボーディングはSDK v4で非推奨となり、将来のリリースで削除される予定です。 バグ修正や機能改善は行われません。代わりにフローを使用してください。オンボーディングがWebView内で動作するのに対し、フローはデバイス上でネイティブにレンダリングされるため、よりスムーズなアニメーション、一貫したネイティブの外観、高速な読み込み、WebViewランタイムへの依存がないというメリットがあります。はじめるにはフローとペイウォールの取得およびフローとペイウォールの表示を参照してください。

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つは上記の定期更新されるキャッシュ、もう1つはフォールバックオンボーディングです。また、CDN を使用してオンボーディングを高速に取得し、CDN に接続できない場合に備えてスタンドアロンのフォールバックサーバーも用意しています。このシステムは、インターネット接続が不安定な状況でも信頼性を確保しながら、常に最新バージョンのオンボーディングを取得できるよう設計されています。
loadTimeout	デフォルト: 5秒	このメソッドのタイムアウト上限を設定します。タイムアウトに達した場合、キャッシュされたデータまたはローカルのフォールバックが返されます。内部で複数のリクエストが発生する場合があるため、まれに `loadTimeout` で指定した時間よりもわずかに遅れてタイムアウトすることがあります。
レスポンスパラメーター:
パラメータ	説明
:----------	:-----------------------------------------------------------------------------------------------------------------------------------------------------------
Onboarding	`AdaptyOnboarding` オブジェクト。オンボーディングの識別子と設定、リモートコンフィグ、およびその他のプロパティを含みます。

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

通常、オンボーディングはほぼ瞬時にフェッチされるため、このプロセスの高速化を気にする必要はありません。ただし、オーディエンスやオンボーディングの数が多く、ユーザーのインターネット接続が遅い場合、オンボーディングのフェッチに想定より時間がかかることがあります。そのような場合は、オンボーディングをまったく表示しないよりも、デフォルトのオンボーディングを表示してスムーズなユーザー体験を確保したいところです。この問題を解決するには、getOnboardingForDefaultAudience メソッドを使用できます。このメソッドは、指定したプレースメントの All Users オーディエンス向けのオンボーディングを取得します。ただし、推奨されるアプローチはオンボーディングの取得セクションで説明している getOnboarding メソッドでオンボーディングを取得することである点を必ず理解しておいてください。

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

互換性の問題: 複数のアプリバージョンをサポートする際に問題が生じる可能性があり、後方互換性のある設計が必要になるか、古いバージョンが正しく表示されないことを許容しなければなりません。
パーソナライズなし: 「すべてのユーザー」オーディエンス向けのコンテンツのみ表示され、国・アトリビューション・カスタム属性などによるターゲティングは利用できません。

これらのデメリットよりも高速なフェッチが優先される場合は、以下のように 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 ダッシュボードでプレースメントを作成する際に指定した値です。

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

locale

任意

デフォルト: en

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

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

fetchPolicy

デフォルト: .reloadRevalidatingCacheData

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

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

キャッシュはアプリを再起動しても保持され、アプリの再インストール時またはキャッシュを手動でクリアした場合にのみ削除されます。

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