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

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

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

1. Adapty ダッシュボードでプロダクトを作成する。
2. Adapty ダッシュボードでフロー/ペイウォールを作成してプロダクトを追加する。
3. Adapty ダッシュボードでプレースメントを作成してフロー/ペイウォールを追加する。
4. モバイルアプリに Adapty 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	デフォルトでは、SDK はサーバーからデータの読み込みを試み、失敗した場合はキャッシュされたデータを返します。ユーザーが常に最新のデータを取得できるため、この設定を推奨します。 ただし、ユーザーのインターネット接続が不安定な場合は、AdaptyPaywallFetchPolicy.ReturnCacheDataElseLoad の使用を検討してください。これはキャッシュが存在する場合にキャッシュデータを返します。この場合、ユーザーが最新のデータを取得できないことがありますが、接続状況にかかわらず読み込み時間が短縮されます。キャッシュは定期的に更新されるため、セッション中にネットワークリクエストを避ける用途では安全に使用できます。 キャッシュはアプリ再起動後も保持され、アプリの再インストール時または手動でクリアした場合にのみ削除されます。 Adapty SDK はフローとペイウォールをローカルに2つの層で保存します。上記の定期更新キャッシュとフォールバックペイウォールです。また、より高速な取得のために 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 Builder（フロー）または 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 オブジェクト。
loadTimeout	任意	このメソッドのタイムアウト上限を設定します。タイムアウトに達した場合、キャッシュデータまたはローカルのフォールバックが返されます。内部的に複数のリクエストで構成される場合があるため、指定した loadTimeout より若干遅れてタイムアウトすることがあります。kotlin.time.Duration.Companion の 5.seconds などの拡張関数を利用できます。
preloadProducts	任意	true に設定すると、パフォーマンス向上のためにプロダクトを事前読み込みします。有効にすると、プロダクトが事前に読み込まれ、フローやペイウォールの表示にかかる時間が短縮されます。
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	デフォルトでは、SDK はサーバーからデータの読み込みを試み、失敗した場合はキャッシュされたデータを返します。この方式では常に最新のデータをユーザーに提供できるため、こちらをお勧めします。 ただし、ユーザーのインターネット接続が不安定な場合は、AdaptyPaywallFetchPolicy.ReturnCacheDataElseLoad の使用を検討してください。キャッシュが存在する場合はそのデータを返します。この場合、ユーザーが受け取るデータが最新でない可能性はありますが、接続状況に関わらず読み込みが速くなります。キャッシュは定期的に更新されるため、セッション中にネットワークリクエストを避ける目的で使用しても問題ありません。 なお、キャッシュはアプリを再起動しても保持されます。クリアされるのは、アプリのアンインストール時または手動でクリーンアップした場合のみです。

アセットのカスタマイズ

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

ヒーロー画像と動画には、事前に定義された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 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	デフォルトでは、SDK はサーバーからデータを読み込もうとし、失敗した場合はキャッシュされたデータを返します。この設定を推奨します。ユーザーが常に最新のデータを受け取れるためです。 ただし、ユーザーが不安定なインターネット接続を使用していると考えられる場合は、AdaptyPaywallFetchPolicy.ReturnCacheDataElseLoad の使用を検討してください。キャッシュが存在する場合はキャッシュされたデータを返します。この場合、ユーザーは必ずしも最新のデータを受け取れるわけではありませんが、接続状況に関わらず高速な読み込みを体験できます。キャッシュは定期的に更新されるため、セッション中にネットワークリクエストを避けるために使用しても安全です。 アプリを再起動してもキャッシュは維持され、アプリの再インストールまたは手動でのクリア時にのみ削除されます。 Adapty SDK はペイウォールをローカルに2層で保存します: 上記の定期更新キャッシュとフォールバックペイウォールです。また、ペイウォールをより高速に取得するために CDN を使用し、CDN が利用できない場合に備えてスタンドアロンのフォールバックサーバーも使用しています。このシステムは、インターネット接続が不安定な状況でも信頼性を確保しながら、常に最新バージョンのペイウォールを取得できるよう設計されています。
loadTimeout	デフォルト: 5秒	このメソッドのタイムアウト上限を設定します。タイムアウトに達した場合、キャッシュされたデータまたはローカルのフォールバックが返されます。 なお、このメソッドは内部で複数のリクエストが発生する場合があるため、まれに loadTimeout で指定した時間より若干遅れてタイムアウトすることがあります。 Kotlin Multiplatform の場合: 拡張関数（例: 5.seconds、.seconds は import com.adapty.utils.seconds から）または TimeInterval.seconds(5) を使って TimeInterval を作成できます。制限なしに設定する場合は 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	デフォルトでは、SDK はサーバーからデータを読み込もうとし、失敗した場合はキャッシュされたデータを返します。ユーザーが常に最新のデータを受け取れるようにするため、この設定を推奨します。 ただし、ユーザーが不安定なインターネット環境を利用していると考えられる場合は、AdaptyPaywallFetchPolicy.ReturnCacheDataElseLoad の使用を検討してください。キャッシュが存在する場合にキャッシュされたデータを返します。この場合、最新のデータが得られないことがありますが、インターネット接続が不安定であっても読み込み時間が短くなります。キャッシュは定期的に更新されるため、ネットワークリクエストを避けるためにセッション中に使用しても問題ありません。 キャッシュはアプリを再起動しても保持され、アプリの再インストールまたは手動でのクリア時にのみ削除されます。

アセットのカスタマイズ

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

ヒーロー画像と動画には、あらかじめ定義された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
    }
}