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

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

始める前に

以下が必要です：

• Adapty ダッシュボードのプロダクト: プロダクトを作成する。
• プロダクトが設定されたフロー: フロー & ペイウォールビルダーでビルドし、プロダクトを割り当てる。
• プレースメント: プレースメントを作成し、フローを割り当てる。
• Adapty SDK のインストール: Kotlin Multiplatform SDK インストールガイドを参照。

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

ビルダーでフローまたはペイウォールを設計した場合、モバイルアプリのコード上でユーザーに表示するためのレンダリングを自分で実装する必要はありません。このようなフローまたはペイウォールには、表示する内容と表示方法の両方が含まれています。ただし、プレースメントを通じてIDを取得し、ビュー設定を取得した上で、モバイルアプリ内に表示する必要があります。

最適なパフォーマンスを確保するには、フローまたはペイウォールとそのビュー設定をできるだけ早く取得し、ユーザーに表示する前に画像のダウンロードに十分な時間を確保することが重要です。

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

Adapty.getFlow(
    placementId = "YOUR_PLACEMENT_ID",
    fetchPolicy = AdaptyPaywallFetchPolicy.Default,
    loadTimeout = 5.seconds
).onSuccess { flow ->
    // the requested flow/paywall
}.onError { error ->
    // handle the error
}

パラメーター:

パラメータ	必須/任意	説明
placementId	必須	取得したいプレースメントの識別子。Adapty ダッシュボードでプレースメントを作成した際に指定した値です。
fetchPolicy	デフォルト: AdaptyPaywallFetchPolicy.Default	fetchPolicy は、SDK がキャッシュを使用できるかどうかではなく、どのレイヤーを最初に読み取るかを設定します。デフォルトでは、SDK はまずサーバーにアクセスし、そのリクエストが失敗した場合にキャッシュされたデータを返します。ユーザーが常に最新のデータを受け取れるため、このバリアントを推奨します。 ただし、ユーザーのインターネット接続が不安定な場合は、AdaptyPaywallFetchPolicy.ReturnCacheDataElseLoad の使用を検討してください。これは順序を逆にして、まずキャッシュを読み取り、何もキャッシュされていない場合にのみサーバーにアクセスします。ユーザーが常に最新のデータを取得できるとは限りませんが、インターネット接続の状態に関わらず、より速い読み込み速度を実現できます。キャッシュは定期的に更新されるため、セッション中にネットワークリクエストを避けるために使用しても安全です。 3つ目のポリシー AdaptyPaywallFetchPolicy.ReturnCacheDataIfNotExpiredElseLoad(maxAgeMillis) は、その中間に位置します。キャッシュされたコピーが maxAgeMillis より新しい間はキャッシュを先に読み取り、古くなるとサーバーにアクセスします。 キャッシュはアプリを再起動しても保持され、アプリのアンインストール時または手動でクリアした場合にのみ削除されます。 Adapty SDK はフローとペイウォールをローカルに2つのレイヤーで保存します。1つは上述の定期更新キャッシュ、もう1つはフォールバックペイウォールです。また、CDN を使用して高速に取得し、CDN に到達できない場合に備えてスタンドアロンのフォールバックサーバーも使用しています。このシステムは、インターネット接続が不安定な場合でも信頼性を確保しながら、常に最新バージョンを取得できるよう設計されています。
loadTimeout	デフォルト: 5秒	このメソッドのタイムアウト時間を制限します。タイムアウトに達した場合、キャッシュされたデータまたはローカルのフォールバックが返されます。 なお、このメソッドは内部で複数のリクエストで構成される場合があるため、まれに loadTimeout で指定した時間よりやや遅れてタイムアウトすることがあります。 Kotlin Multiplatform の場合: 5.seconds のような拡張関数を使用して Duration を作成できます。.seconds は kotlin.time.Duration.Companion.seconds から提供されます。

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

パラメーター	説明
Flow	プレースメント、識別子（instanceIdentity、variationId）、名前、ペイウォールのバリアント（paywalls — AdaptyFlowPaywall のリスト）、リモートコンフィグ（remoteConfigs — ロケールごとに1エントリのリスト）を含む AdaptyFlow オブジェクト。プリロード、カスタム UI、またはプログラムによる確認のために実際のプロダクトを取得するには、getPaywallProducts(flow) を呼び出してください。

ビューの設定を取得する

フローまたはペイウォールを取得したら、createFlowView メソッドを使ってビューの設定を読み込み、ビューを一度に作成します。確認すべき個別のフラグはありません。プレースメントが Flow & Paywall Builder（フロー）または old Paywall Builder（ペイウォール）で設計されている場合、createFlowView は表示可能な状態のビューを返します。プレースメントがビルダーUIを持たないカスタムペイウォールの場合、createFlowView は AdaptyResult.Error を返します。その場合はリモートコンフィグペイウォールとして処理してください。

AdaptyUI.createFlowView(
    flow = flow,
    loadTimeout = 5.seconds,
    preloadProducts = true
).onSuccess { view ->
    // use view
}.onError { error ->
    // the flow has no view configured, or view creation failed
}

パラメーター	必須/任意	説明
flow	必須	Adapty.getFlow で取得した AdaptyFlow オブジェクト。
locale	任意	ビューのレンダリングに使用するフローのローカライズの識別子（例：en、pt-br）。省略した場合、en でレンダリングされます。フローに en がない場合はフローのデフォルトのローカライズが使用されます。詳細はローカライズとロケールコードを参照してください。
customLayoutId	任意 デフォルト: null SDK 4.1+	Flow Builder で定義されたレイアウトのカスタム ID。指定すると、SDK がデバイスの種類や画面サイズから自動的に選択するレイアウトの代わりに、該当するレイアウトがレンダリングされます。ID に一致するレイアウトがない場合、フローはビュー設定なしで読み込まれます。
loadTimeout	任意	このメソッドのタイムアウト上限を設定します。タイムアウトに達した場合、キャッシュされたデータまたはローカルフォールバックが返されます。このメソッドは内部で複数のリクエストが行われる場合があるため、loadTimeout で指定した時間より若干遅れてタイムアウトすることがあります。kotlin.time.Duration.Companion の 5.seconds などの拡張関数を使用できます。
preloadProducts	任意	true に設定するとプロダクトを事前に読み込み、パフォーマンスを向上させます。有効にすると、プロダクトが事前に読み込まれ、フローまたはペイウォールの表示にかかる時間が短縮されます。
customTags	任意	フローのカスタムタグに対するアプリの値を、各タグのフルネームをキーとするマップで指定します。詳細はフローへのデータの受け渡しを参照してください。
productPurchaseParams	任意	AdaptyProductIdentifier から AdaptyPurchaseParameters へのマップ。フローまたはペイウォール内の個々のプロダクトに対して、パーソナライズされたオファーやサブスクリプション更新パラメーターなど、購入固有のパラメーターを設定する際に使用します。

読み込みが完了したら、フローまたはペイウォールを表示してください。

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

通常、フローとペイウォールはほぼ即座に取得されるため、高速化を意識する必要はありません。ただし、オーディエンスやプレースメントが多数ある場合や、ユーザーのインターネット接続が不安定な場合は、フローやペイウォールの取得に予想以上の時間がかかることがあります。そのような状況では、何も表示しないよりも、デフォルトのフローまたはペイウォールを表示してスムーズなユーザー体験を確保したいと思うかもしれません。

これに対処するために、getFlowForDefaultAudience メソッドを使用できます。このメソッドは、All Users オーディエンス向けに指定されたプレースメントのフローまたはペイウォールを取得します。ただし、推奨されるアプローチは、上記のフロー/ペイウォールの取得セクションで詳しく説明されている getFlow メソッドでフローまたはペイウォールを取得することであると理解しておくことが重要です。

Adapty.getFlowForDefaultAudience(
    placementId = "YOUR_PLACEMENT_ID",
    fetchPolicy = AdaptyPaywallFetchPolicy.Default,
).onSuccess { flow ->
    // the requested flow
}.onError { error ->
    // handle the error
}

パラメータ	必須/任意	説明
placementId	必須	プレースメントの識別子。Adapty ダッシュボードでプレースメントを作成する際に指定した値です。
fetchPolicy	デフォルト: AdaptyPaywallFetchPolicy.Default	fetchPolicy は、SDK がキャッシュを使用するかどうかではなく、どのレイヤーを最初に読み取るかを設定します。デフォルトでは、SDK はまずサーバーにアクセスし、リクエストが失敗した場合にキャッシュされたデータを返します。ユーザーが常に最新のデータを取得できるため、このバリアントをお勧めします。 ただし、ユーザーがインターネット接続が不安定な環境にいると考えられる場合は、AdaptyPaywallFetchPolicy.ReturnCacheDataElseLoad の使用を検討してください。このポリシーは順序を逆にし、まずキャッシュを読み取り、キャッシュが存在しない場合のみサーバーにアクセスします。ユーザーが最新のデータを取得できない場合もありますが、インターネット接続の状態にかかわらず、読み込み時間が短縮されます。キャッシュは定期的に更新されるため、ネットワークリクエストを避けるためにセッション中に使用しても問題ありません。 3つ目のポリシー AdaptyPaywallFetchPolicy.ReturnCacheDataIfNotExpiredElseLoad(maxAgeMillis) は、両者の中間に位置します。キャッシュされたコピーが maxAgeMillis より新しい間はキャッシュを先に読み取り、古くなった場合はサーバーにアクセスします。 キャッシュはアプリの再起動後も保持され、アプリのアンインストールまたは手動でのクリーンアップ時にのみクリアされます。

アセットのカスタマイズ

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

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

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

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

• 一部のユーザーに異なる画像や動画を表示する。
• リモートのメイン画像を読み込む間、ローカルのプレビュー画像を表示する。
• 動画を再生する前にプレビュー画像を表示する。
• アプリにバンドルされたメディアを表示し、最初の画面をダウンロードなしでレンダリングする。アプリバンドルから最初の画面のメディアを表示するを参照してください。

カスタムアセットをマップで指定する方法の例を次に示します。

// Import generated Res class for accessing resources

viewModelScope.launch {
    // Get URIs for bundled resources using Res.getUri()
    val heroImagePath = Res.getUri("files/images/hero_image.png")
    val demoVideoPath = Res.getUri("files/videos/demo_video.mp4")

    // Or read image as byte data
    val imageByteData = Res.readBytes("files/images/avatar.png")

    // Create custom assets map
    val customAssets: Map<String, AdaptyCustomAsset> = mapOf(
        // Load image from app resources (bundled with the app)
        // Files should be placed in commonMain/composeResources/files/
        "hero_image" to AdaptyCustomAsset.localImageResource(
            path = heroImagePath
        ),

        // Or use image byte data
        "avatar" to AdaptyCustomAsset.localImageData(
            data = imageByteData
        ),

        // Load video from app resources
        "demo_video" to AdaptyCustomAsset.localVideoResource(
            path = demoVideoPath
        ),

        // Or use a video file from device storage
        "intro_video" to AdaptyCustomAsset.localVideoFile(
            path = "/path/to/local/video.mp4"
        )
    )

    // Use custom assets when creating the flow view
    AdaptyUI.createFlowView(
        flow = flow,
        customAssets = customAssets
    ).onSuccess { view ->
        // Present the flow with custom assets
        view.present()
    }.onError { error ->
        // Handle the error - the flow will fall back to default appearance
    }
}

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

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

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

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

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

ペイウォールビルダーを使ってペイウォールをデザインした場合、ユーザーに表示するためのレンダリングコードをアプリ内に書く必要はありません。このようなペイウォールには、表示する内容と表示方法の両方が含まれています。ただし、プレースメントからペイウォールのIDを取得し、ビュー設定を取得した上で、モバイルアプリ内に表示する必要があります。

最適なパフォーマンスを確保するために、ペイウォールとそのビュー設定をできるだけ早く取得し、ユーザーに表示する前に画像のダウンロードに十分な時間を確保することが重要です。

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

Adapty.getPaywall(
    placementId = "YOUR_PLACEMENT_ID",
    locale = "en",
    fetchPolicy = AdaptyPaywallFetchPolicy.Default,
    loadTimeout = 5.seconds
).onSuccess { paywall ->
    // the requested paywall
}.onError { error ->
    // handle the error
}

パラメーター:

パラメーター	必須/任意	説明
placementId	必須	対象のプレースメントの識別子です。Adapty ダッシュボードでプレースメントを作成する際に指定した値です。
locale	任意 デフォルト: en	ペイウォールのローカライゼーション識別子です。マイナス（-）文字で区切られた1つまたは2つのサブタグで構成される言語コードを指定します。最初のサブタグは言語、2番目は地域を表します。 例: en は英語、pt-br はブラジルポルトガル語を表します。 ロケールコードの詳細および推奨される使い方については、ローカライゼーションとロケールコードを参照してください。
fetchPolicy	デフォルト: AdaptyPaywallFetchPolicy.Default	fetchPolicy は、SDK がキャッシュを使用するかどうかではなく、どのレイヤーを最初に読み込むかを設定します。デフォルトでは、SDK はまずサーバーにアクセスし、リクエストが失敗した場合にキャッシュデータを返します。ユーザーが常に最新データを取得できるため、この設定を推奨します。 ただし、ユーザーが不安定なインターネット環境を使用していると考える場合は、AdaptyPaywallFetchPolicy.ReturnCacheDataElseLoad の使用を検討してください。この設定では順序が逆になり、まずキャッシュを読み込み、キャッシュが存在しない場合のみサーバーにアクセスします。最新データを取得できない場合もありますが、インターネット接続が不安定な状況でも高速な読み込みが実現します。キャッシュは定期的に更新されるため、セッション中にネットワークリクエストを避ける目的で使用しても安全です。 3番目のポリシー AdaptyPaywallFetchPolicy.ReturnCacheDataIfNotExpiredElseLoad(maxAgeMillis) は、この2つの中間に位置します。キャッシュのコピーが maxAgeMillis より新しい場合はキャッシュを先に読み込み、古くなった場合はサーバーにアクセスします。 キャッシュはアプリを再起動しても保持され、アプリの再インストールまたは手動でのクリーンアップによってのみ消去されます。 Adapty SDK はペイウォールをローカルに2つのレイヤーで保存しています。1つは上記の定期更新キャッシュ、もう1つはフォールバックペイウォールです。また、CDN を使用してペイウォールの取得を高速化し、CDN が利用できない場合に備えてスタンドアロンのフォールバックサーバーも用意しています。このシステムは、インターネット接続が不安定な場合でも、常に最新バージョンのペイウォールを安定して取得できるよう設計されています。
loadTimeout	デフォルト: 5秒	このメソッドのタイムアウト時間を制限する値です。タイムアウトに達した場合、キャッシュデータまたはローカルのフォールバックが返されます。 まれに、内部で複数のリクエストが実行されるため、loadTimeout に指定した時間よりわずかに遅れてタイムアウトする場合があります。 Kotlin Multiplatform の場合: 拡張関数（例: 5.seconds、.seconds は import com.adapty.utils.seconds から）を使用して TimeInterval を作成するか、TimeInterval.seconds(5) を使用できます。制限なしに設定するには TimeInterval.INFINITE を使用してください。

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

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

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

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

createPaywallView メソッドを使用して、ビューの設定を読み込みます。

if (paywall.hasViewConfiguration) {
    AdaptyUI.createPaywallView(
        paywall = paywall,
        loadTimeout = 5.seconds,
        preloadProducts = true
    ).onSuccess { paywallView ->
        // use paywallView
    }.onError { error ->
        // handle the error
    }
} else {
    // use your custom logic
}

パラメーター	必須/任意	説明
paywall	必須	目的のペイウォールのコントローラーを取得するための AdaptyPaywall オブジェクト。
loadTimeout	任意	このメソッドのタイムアウト上限を設定します。タイムアウトに達した場合、キャッシュデータまたはローカルのフォールバックが返されます。なお、このメソッドは内部で複数のリクエストを行う場合があるため、loadTimeout で指定した時間よりわずかに遅くタイムアウトすることがあります。kotlin.time.Duration.Companion の 5.seconds のような拡張関数を使用できます。
preloadProducts	任意	プロダクトを事前読み込みしてパフォーマンスを向上させるには true に設定します。有効にすると、プロダクトが事前に読み込まれ、ペイウォールの表示に要する時間が短縮されます。
productPurchaseParams	任意	AdaptyProductIdentifier から AdaptyPurchaseParameters へのマップ。ペイウォール内の個々のプロダクトに対して、パーソナライズドオファーやサブスクリプション更新パラメーターなど、購入固有のパラメーターを設定するために使用します。

読み込みが完了したら、ペイウォールを表示してください。

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

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

この問題に対処するには、getPaywallForDefaultAudience メソッドを使用することで、All Users オーディエンスに対して指定プレースメントのペイウォールを取得できます。ただし、推奨される方法は getPaywall メソッドによるペイウォールの取得であることを理解しておくことが重要です。詳しくは上記の ペイウォール情報の取得 セクションをご覧ください。

Adapty.getPaywallForDefaultAudience(
    placementId = "YOUR_PLACEMENT_ID",
    locale = "en",
    fetchPolicy = AdaptyPaywallFetchPolicy.Default,
).onSuccess { paywall ->
    // the requested paywall
}.onError { error ->
    // handle the error
}

パラメーター	必須/任意	説明
placementId	必須	プレースメントの識別子です。Adapty ダッシュボードでプレースメントを作成する際に指定した値です。
locale	任意 デフォルト: en	ペイウォールのローカライゼーションの識別子です。このパラメーターは、マイナス（-）文字で区切られた1つ以上のサブタグで構成される言語コードを指定します。最初のサブタグは言語を表し、2番目のサブタグは地域を表します。 例: en は英語を意味し、pt-br はブラジルポルトガル語を表します。 ロケールコードとその推奨される使い方については、ローカライゼーションとロケールコードを参照してください。
fetchPolicy	デフォルト: AdaptyPaywallFetchPolicy.Default	fetchPolicy は、SDK がキャッシュを使用できるかどうかではなく、どのレイヤーを最初に読み取るかを設定します。デフォルトでは、SDK はまずサーバーにアクセスし、リクエストが失敗した場合にキャッシュされたデータを返します。ユーザーが常に最新のデータを取得できるため、この方式をお勧めします。 ただし、ユーザーが不安定なインターネット環境を利用していると思われる場合は、AdaptyPaywallFetchPolicy.ReturnCacheDataElseLoad の使用を検討してください。この方式では順序が逆になり、まずキャッシュを読み取り、何もキャッシュされていない場合にのみサーバーにアクセスします。ユーザーは最新のデータを取得できない場合がありますが、インターネット接続が不安定であっても、より速い読み込みを体験できます。キャッシュは定期的に更新されるため、ネットワークリクエストを避けるためにセッション中に使用しても安全です。 3番目のポリシーである AdaptyPaywallFetchPolicy.ReturnCacheDataIfNotExpiredElseLoad(maxAgeMillis) は、両者の中間に位置します。キャッシュされたコピーが maxAgeMillis より新しい間はキャッシュを先に読み取り、古くなるとサーバーにアクセスします。 キャッシュはアプリを再起動しても保持され、アプリの再インストールまたは手動でのクリーンアップ時にのみ削除されます。

アセットのカスタマイズ

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

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

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

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

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

カスタムアセットをマップ経由で提供する方法の例を示します。

// Import generated Res class for accessing resources

viewModelScope.launch {
    // Get URIs for bundled resources using Res.getUri()
    val heroImagePath = Res.getUri("files/images/hero_image.png")
    val demoVideoPath = Res.getUri("files/videos/demo_video.mp4")

    // Or read image as byte data
    val imageByteData = Res.readBytes("files/images/avatar.png")

    // Create custom assets map
    val customAssets: Map<String, AdaptyCustomAsset> = mapOf(
        // Load image from app resources (bundled with the app)
        // Files should be placed in commonMain/composeResources/files/
        "hero_image" to AdaptyCustomAsset.localImageResource(
            path = heroImagePath
        ),

        // Or use image byte data
        "avatar" to AdaptyCustomAsset.localImageData(
            data = imageByteData
        ),

        // Load video from app resources
        "demo_video" to AdaptyCustomAsset.localVideoResource(
            path = demoVideoPath
        ),

        // Or use a video file from device storage
        "intro_video" to AdaptyCustomAsset.localVideoFile(
            path = "/path/to/local/video.mp4"
        ),

        // Apply custom brand colors
        "brand_primary" to AdaptyCustomAsset.color(
            colorHex = "#FF6B35"
        ),

        // Create gradient background
        "card_gradient" to AdaptyCustomAsset.linearGradient(
            colors = listOf("#1E3A8A", "#3B82F6", "#60A5FA"),
            stops = listOf(0.0f, 0.5f, 1.0f)
        )
    )

    // Use custom assets when creating paywall view
    AdaptyUI.createPaywallView(
        paywall = paywall,
        customAssets = customAssets
    ).onSuccess { paywallView ->
        // Present the paywall with custom assets
        paywallView.present()
    }.onError { error ->
        // Handle the error - paywall will fall back to default appearance
    }
}