フローとペイウォールの取得 - React Native

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

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

Adapty SDK がモバイルアプリにどのように統合されているか、実際の例を見てみませんか？ペイウォールの表示、購入処理、その他の基本機能を含む完全なセットアップを実演しているサンプルアプリをご覧ください。

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

Adapty ダッシュボードでプロダクトを作成する。
Adapty ダッシュボードでフロー/ペイウォールを作成し、プロダクトを組み込む。
Adapty ダッシュボードでプレースメントを作成し、フロー/ペイウォールを組み込む。
モバイルアプリに Adapty SDK をインストールする。

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

Flow Builder またはペイウォールビルダーを使ってフローまたはペイウォールを作成した場合、モバイルアプリのコード上でそれをユーザーに表示するためのレンダリング処理を自分で実装する必要はありません。そのようなフローやペイウォールには、表示する内容と表示方法の両方が含まれています。ただし、プレースメントを通じてIDを取得し、ビュー設定を取得した上で、モバイルアプリ内に表示する必要があります。フローまたはペイウォールをできるだけ早い段階で取得し、そのビューを作成しておきましょう — 理想的には表示するよりもかなり前に行います。createFlowView メソッドはビューの設定を読み込み、画像のダウンロードとキャッシュをバックグラウンドで開始します。早めに呼び出すほど、ダウンロードが完了するまでの時間を確保できます。フローまたはペイウォールを表示する頃には、設定と画像がすでにキャッシュされた状態になっています。

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

try {
    const placementId = 'YOUR_PLACEMENT_ID';

    const flow = await adapty.getFlow(placementId);
  // the requested flow/paywall
} catch (error) {
    // handle the error
}

パラメーター:

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

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

fetchPolicy

デフォルト: .reloadRevalidatingCacheData

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

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

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

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

loadTimeoutMs

デフォルト: 5秒

このメソッドのタイムアウト上限を設定します。タイムアウトに達した場合、キャッシュデータまたはローカルフォールバックが返されます。

内部で複数のリクエストが実行される場合があるため、まれに loadTimeout で指定した時間よりわずかに遅れてタイムアウトすることがあります。

Android の場合: 拡張関数（例: 5.seconds、.seconds は import com.adapty.utils.seconds から）を使用するか、TimeInterval.seconds(5) で TimeInterval を作成できます。制限なしにするには TimeInterval.INFINITE を使用してください。

レスポンスパラメータ

パラメータ	説明
Flow	フローの識別子（`id`、`variationId`）、名前、プレースメント、ペイウォールのバリアント（`paywalls`）、リモートコンフィグ（`remoteConfigs`）を含む `AdaptyFlow` オブジェクト。

ビュー設定の取得

ビルダーの Show on device トグルを必ず有効にしてください。このオプションがオンになっていない場合、ビュー設定を取得できません。

プレースメントが Flow Builder または ペイウォールビルダー でデザインされている場合、Adapty が UI をレンダリングします。createFlowView でビューを作成し、フローまたはペイウォールを表示してください。プレースメントがビルダー UI を持たないカスタムペイウォールの場合は、代わりにリモートコンフィグペイウォールとして処理してください。 React Native SDK では、ビューの設定を事前に取得する必要はなく、createFlowView を直接呼び出せます。

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


try {
  const view = await createFlowView(flow);
} catch (error) {
  // handle the error
}

パラメーター:

パラメーター	必須/任意	説明
flow	必須	目的のフロー/ペイウォールのコントローラーを取得するための `AdaptyFlow` オブジェクト。
customTags	任意	カスタムタグとその解決済みの値の辞書を定義します。カスタムタグはコンテンツ内のプレースホルダーとして機能し、フロー/ペイウォール内でパーソナライズされたコンテンツを提供するために特定の文字列に動的に置き換えられます。詳細については、ペイウォールビルダーのカスタムタグに関するトピックを参照してください。
prefetchProducts	任意	画面上のプロダクト表示タイミングを最適化するために有効にします。`true` にすると、AdaptyUI が必要なプロダクトを自動的にフェッチします。デフォルト: `false`。
android.enableSafeArea	任意	Android のみ（iOS では無視されます）。ネストされたオブジェクトとして渡してください: `android: { enableSafeArea: true }`。`true` にすると、フロービューにセーフエリアのパディングが適用されます。モーダル表示（`createFlowView` + `present()`）の場合はデフォルトで `true`、埋め込みの `AdaptyFlowView` コンポーネントの場合はデフォルトで `false` です。ほとんどのケースではデフォルト設定が適しています。

複数の言語を使用している場合は、フローのローカライズを追加する方法と、ロケールコードを正しく使用する方法をこちらでご確認ください。

ビューを取得したら、フロー/ペイウォールを表示してください。

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

通常、フローやペイウォールはほぼ即座に取得されるため、高速化を意識する必要はありません。ただし、オーディエンスやプレースメントが多数あり、ユーザーの通信環境が不安定な場合は、取得に時間がかかることがあります。そのような状況では、何も表示しないよりも、デフォルトのフローまたはペイウォールを表示してスムーズなユーザー体験を提供したほうがよいでしょう。これに対処するために、getFlowForDefaultAudience メソッドを使用できます。このメソッドは、指定したプレースメントの All Users オーディエンス向けのフローまたはペイウォールを取得します。ただし、推奨されるアプローチはフロー/ペイウォールの取得セクションで詳しく説明されている getFlow メソッドを使用してフローまたはペイウォールを取得することである点を理解しておくことが重要です。

getFlow を推奨する理由

getFlowForDefaultAudience メソッドにはいくつかの重大なデメリットがあります：

後方互換性の問題: 現行バージョンと将来のバージョンで異なるペイウォールを表示する必要がある場合、課題が生じる可能性があります。現行（レガシー）バージョンに対応したペイウォールを設計するか、現行（レガシー）バージョンのユーザーがペイウォールを表示できない問題を受け入れるかのいずれかを選択する必要があります。
ターゲティングの喪失: すべてのユーザーが All Users オーディエンス向けに設計された同一のペイウォールを表示することになるため、国、マーケティングのアトリビューション、独自のカスタム属性に基づくパーソナライズされたターゲティングができなくなります。より速いフローまたはペイウォールの取得というメリットのためにこれらのデメリットを受け入れられる場合は、以下のように getFlowForDefaultAudience メソッドを使用してください。それ以外の場合は、上記で説明した getFlow を使用してください。

try {
    const id = 'YOUR_PLACEMENT_ID';

    const flow = await adapty.getFlowForDefaultAudience(id);
  // the requested flow/paywall
} catch (error) {
    // handle the error
}

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

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

パラメータ	必須/任意	説明
placementId	必須	プレースメントの識別子です。Adapty ダッシュボードでプレースメントを作成する際に指定した値です。
fetchPolicy	デフォルト: `.reloadRevalidatingCacheData`	デフォルトでは、SDK はサーバーからデータを読み込もうとし、失敗した場合はキャッシュされたデータを返します。ユーザーが常に最新のデータを受け取れるため、この設定を推奨します。ただし、ユーザーのインターネット接続が不安定な場合は、`.returnCacheDataElseLoad` の使用を検討してください。この設定では、キャッシュが存在する場合にキャッシュデータを返します。最新データが得られないケースはありますが、接続状況に関わらず読み込みが速くなります。キャッシュはセッション中も定期的に更新されるため、ネットワークリクエストを減らす目的で安心して利用できます。なお、キャッシュはアプリを再起動しても保持され、アプリのアンインストール時または手動でクリアした場合のみ削除されます。

fetchPolicy

デフォルト: .reloadRevalidatingCacheData

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

ただし、ユーザーのインターネット接続が不安定な場合は、.returnCacheDataElseLoad の使用を検討してください。この設定では、キャッシュが存在する場合にキャッシュデータを返します。最新データが得られないケースはありますが、接続状況に関わらず読み込みが速くなります。キャッシュはセッション中も定期的に更新されるため、ネットワークリクエストを減らす目的で安心して利用できます。

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

アセットのカスタマイズ

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

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

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

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

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

この機能を使用するには、Adapty React Native SDK をバージョン 3.8.0 以上に更新してください。

シンプルなディクショナリを使ってカスタムアセットを提供する例を以下に示します：

const customAssets: Record<string, AdaptyCustomAsset> = {
  'custom_image': { type: 'image', relativeAssetPath: 'custom_image.png' },
  'hero_video': {
    type: 'video',
    fileLocation: {
      ios: { fileName: 'custom_video.mp4' },
      android: { relativeAssetPath: 'videos/custom_video.mp4' }
    }
  }
};

view = await createFlowView(flow, { customAssets })

アセットが見つからない場合、フロー/ペイウォールはデフォルトの外観にフォールバックします。

Adapty ダッシュボードの新しいペイウォールビルダーでペイウォールのビジュアルデザインを作成した後、それをモバイルアプリに表示できます。最初のステップは、プレースメントに関連付けられたペイウォールとそのビュー設定を取得することです。詳細は以下をご覧ください。

新しいペイウォールビルダーは、React Native SDK バージョン 3.0 以降で動作します。

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

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

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

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

ペイウォールビルダーを使ってペイウォールをデザインした場合、ユーザーに表示するためのレンダリングコードをアプリ内に書く必要はありません。このようなペイウォールには、表示する内容と表示方法の両方が含まれています。ただし、プレースメントを通じてペイウォールのIDを取得し、ビュー設定を取得した上で、アプリ内に表示する必要があります。最適なパフォーマンスを確保するには、ユーザーに表示する前に画像のダウンロードが完了するよう十分な時間を確保するために、ペイウォールとそのビュー設定をできるだけ早く取得することが重要です。

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

try {
    const placementId = 'YOUR_PLACEMENT_ID';
    const locale = 'en';

    const paywall = await adapty.getPaywall(placementId, locale);
  // the requested paywall
} catch (error) {
    // handle the error
}

パラメーター:

パラメータ	必須/任意	説明
placementId	必須	取得したいプレースメントの識別子。Adapty ダッシュボードでプレースメントを作成する際に指定した値です。
locale	任意デフォルト: `en`	ペイウォールのローカライゼーションの識別子。ハイフン（-）で区切られた1つまたは2つのサブタグで構成される言語コードを指定します。最初のサブタグは言語、2番目はリージョンを表します。例：`en` は英語、`pt-br` はブラジルポルトガル語を表します。ロケールコードおよび推奨する使用方法については、ローカライゼーションとロケールコードを参照してください。
fetchPolicy	デフォルト: `.reloadRevalidatingCacheData`	デフォルトでは、SDK はサーバーからデータを読み込もうとし、失敗した場合はキャッシュされたデータを返します。常に最新のデータをユーザーに届けられるため、この設定を推奨します。ただし、ユーザーのインターネット接続が不安定だと考えられる場合は、`.returnCacheDataElseLoad` を使用して、キャッシュが存在する場合はキャッシュデータを返すようにすることを検討してください。この場合、最新データが届かないことがありますが、接続が不安定な状況でも読み込みが速くなります。キャッシュはこまめに更新されるため、ネットワークリクエストを減らす目的でセッション中に使用しても問題ありません。キャッシュはアプリを再起動しても保持され、アプリの再インストール時または手動でクリアした場合にのみ削除されます。 Adapty SDK はペイウォールをローカルに2層で保存します。1つは上述の定期更新キャッシュ、もう1つはフォールバックペイウォールです。また、ペイウォールの取得を高速化するために CDN を使用し、CDN に接続できない場合に備えたスタンドアロンのフォールバックサーバーも備えています。このシステムは、インターネット接続が不安定な状況でも信頼性を確保しながら、常に最新バージョンのペイウォールを取得できるよう設計されています。
loadTimeoutMs	デフォルト: 5秒	このメソッドのタイムアウト上限を設定します。タイムアウトに達した場合、キャッシュデータまたはローカルのフォールバックが返されます。内部で複数のリクエストが発生する場合があるため、まれに `loadTimeout` で指定した時間よりわずかに遅れてタイムアウトすることがあります。 Android の場合：`TimeInterval` は拡張関数（例：`5.seconds`（`.seconds` は `import com.adapty.utils.seconds` から）など）または `TimeInterval.seconds(5)` で作成できます。制限なしに設定するには `TimeInterval.INFINITE` を使用してください。

レスポンスパラメータ

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

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

ペイウォールビルダーの Show on device トグルを有効にしてください。このオプションがオンになっていない場合、ビュー設定を取得できません。

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

React Native SDK では、ビュー設定を手動で取得せずに、直接 createPaywallView メソッドを呼び出してください。

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

// for the Adapty SDK < 3.14 – import {createPaywallView} from 'react-native-adapty/dist/ui';

if (paywall.hasViewConfiguration) {
  try {
    const view = await createPaywallView(paywall);
  } catch (error) {
    // handle the error
  }
} else {
    //use your custom logic
}

パラメーター:

パラメーター	必須/任意	説明
paywall	必須	目的のペイウォールのコントローラーを取得するための `AdaptyPaywall` オブジェクト。
customTags	任意	カスタムタグとその解決済みの値のディクショナリを定義します。カスタムタグはペイウォールコンテンツ内のプレースホルダーとして機能し、特定の文字列に動的に置き換えることでペイウォール内のコンテンツをパーソナライズします。詳細はペイウォールビルダーのカスタムタグのトピックを参照してください。
prefetchProducts	任意	画面上のプロダクト表示タイミングを最適化するために有効にします。`true` の場合、AdaptyUI は必要なプロダクトを自動的に取得します。デフォルト: `false`。

複数の言語を使用している場合は、ペイウォールビルダーのローカライゼーションを追加する方法と、ロケールコードの正しい使い方についてはこちらをご覧ください。

ビューを取得したら、ペイウォールを表示してください。

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

通常、ペイウォールはほぼ即座に取得されるため、速度を気にする必要はありません。ただし、オーディエンスやペイウォールの数が多く、ユーザーのインターネット接続が不安定な場合、ペイウォールの取得に予想以上の時間がかかることがあります。そのような状況では、ペイウォールをまったく表示しないよりも、デフォルトのペイウォールを表示してスムーズなユーザー体験を確保したい場合があるでしょう。これに対処するには、getPaywallForDefaultAudience メソッドを使用できます。このメソッドは、All Users オーディエンス向けに指定されたプレースメントのペイウォールを取得します。ただし、推奨アプローチは getPaywall メソッドでペイウォールを取得することであり、詳細は上記のペイウォール情報の取得セクションを参照してください。

getPaywall を推奨する理由

getPaywallForDefaultAudience メソッドにはいくつかの重大な欠点があります：

後方互換性の問題: 異なるアプリバージョン（現行バージョンと将来のバージョン）で異なるペイウォールを表示する必要がある場合、課題が生じることがあります。現行（レガシー）バージョンに対応したペイウォールを設計するか、現行（レガシー）バージョンのユーザーがペイウォールを表示できない問題を許容するか、いずれかの対応が必要になります。
ターゲティングの喪失: すべてのユーザーに All Users オーディエンス向けに設計された同一のペイウォールが表示されます。これにより、国、マーケティングのアトリビューション、独自のカスタム属性などに基づくパーソナライズされたターゲティングができなくなります。これらのデメリットを許容してペイウォールの取得を高速化したい場合は、以下のように getPaywallForDefaultAudience メソッドを使用してください。そうでない場合は、上記で説明した getPaywall を使用してください。

try {
    const id = 'YOUR_PLACEMENT_ID';
    const locale = 'en';

    const paywall = await adapty.getPaywallForDefaultAudience(id, locale);
  // the requested paywall
} catch (error) {
    // handle the error
}

getPaywallForDefaultAudience メソッドは、React Native SDK バージョン 2.11.2 以降で利用できます。

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

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

パラメータ	必須/任意	説明
placementId	必須	プレースメントの識別子です。Adapty ダッシュボードでプレースメントを作成する際に指定した値です。
locale	任意デフォルト: `en`	ペイウォールのローカライゼーションの識別子です。このパラメータは、マイナス（-）文字で区切られた1つ以上のサブタグで構成される言語コードである必要があります。最初のサブタグは言語、2番目のサブタグは地域を表します。例: `en` は英語、`pt-br` はブラジルポルトガル語を表します。ロケールコードの詳細および推奨される使用方法については、ローカライゼーションとロケールコードを参照してください。
fetchPolicy	デフォルト: `.reloadRevalidatingCacheData`	デフォルトでは、SDK はサーバーからデータを読み込もうとし、失敗した場合はキャッシュされたデータを返します。この方法はユーザーが常に最新のデータを受け取れるため、推奨しています。ただし、ユーザーがインターネット接続の不安定な環境にいると想定される場合は、`.returnCacheDataElseLoad` を使用してキャッシュが存在すればそれを返す方法も検討してください。この場合、最新データが届かないことがありますが、接続状態に関わらず読み込み時間が短縮されます。キャッシュはセッション中に定期的に更新されるため、ネットワークリクエストを減らす目的で安全に使用できます。なお、キャッシュはアプリを再起動しても保持され、アプリの再インストールまたは手動クリアを行った場合にのみ削除されます。

locale

任意

デフォルト: en

ペイウォールのローカライゼーションの識別子です。このパラメータは、マイナス（-）文字で区切られた1つ以上のサブタグで構成される言語コードである必要があります。最初のサブタグは言語、2番目のサブタグは地域を表します。

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

ロケールコードの詳細および推奨される使用方法については、ローカライゼーションとロケールコードを参照してください。

fetchPolicy

デフォルト: .reloadRevalidatingCacheData

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

ただし、ユーザーがインターネット接続の不安定な環境にいると想定される場合は、.returnCacheDataElseLoad を使用してキャッシュが存在すればそれを返す方法も検討してください。この場合、最新データが届かないことがありますが、接続状態に関わらず読み込み時間が短縮されます。キャッシュはセッション中に定期的に更新されるため、ネットワークリクエストを減らす目的で安全に使用できます。

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

アセットのカスタマイズ

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

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

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

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

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

この機能を使用するには、Adapty React Native SDK をバージョン 3.8.0 以上に更新してください。

シンプルなディクショナリを使ってカスタムアセットを提供する例を示します:

const customAssets: Record<string, AdaptyCustomAsset> = {
  'custom_image': { type: 'image', relativeAssetPath: 'custom_image.png' },
  'hero_video': {
    type: 'video',
    fileLocation: {
      ios: { fileName: 'custom_video.mp4' },
      android: { relativeAssetPath: 'videos/custom_video.mp4' }
    }
  }
};

view = await createPaywallView(paywall, { customAssets })

アセットが見つからない場合、ペイウォールはデフォルトの外観にフォールバックします。