FlutterSDKでフローにデータを渡す

カスタムタグは、アプリから値を受け取るカスタム変数です。変数の設定で Value comes from outside the app を選択すると、アプリはAdapty SDKを通じてその値を設定できます。たとえば、テキスト要素に「Coins:」とカスタムタグが含まれている場合、アプリがそのタグに「120」を渡すと、ユーザーには「Coins: 120」と表示されます。

始める前に

Adapty SDK v4 以降が必要です。v4 より前のバージョンではフローが表示されません。

フローにカスタムタグを追加する

アプリの値をフローで表示するには、ビルダーでカスタムタグを設定します。

アプリが渡す各値に対してカスタムタグを作成します。
各タグをテキスト要素に挿入します。
グループ名を含む各タグのフルネームを確認してください。アプリのコードはこの名前で各値を渡します。たとえば、user グループに streak タグが含まれている場合、タグのフルネームは user.streak となります。

カスタムタグの値を渡す

アプリの値を AdaptyUI().createFlowView または AdaptyUIFlowPlatformView の customTags パラメータに Map<String, String> 形式で渡します。

各キーは user.streak のようなカスタムタグの完全な名前です。
各値はタグの代わりにユーザーに表示される文字列です。
各値は “1,250” のように人間が読める形式である必要があります。“1250.0” ではありません。Adapty はフォーマットや翻訳を行いません。

SDK はビューを作成する際に値を一度だけ読み込むため、フローが開いている間は変更されません。

final customTags = {
  'username': 'DragonSlayer42',
  'coins': '1,250',
};

try {
  final view = await AdaptyUI().createFlowView(
    flow: flow,
    customTags: customTags,
  );
  await view.present();
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}

AdaptyUIFlowPlatformView(
  flow: flow,
  customTags: const {
    'username': 'DragonSlayer42',
    'coins': '1,250',
  },
)

マウントされた AdaptyUIFlowPlatformView は、後から customTags を変更しても反映されません。

カスタムタグをテストするには、タグの値を設定するコードを追加した後、アプリでフローを開いてください。ビルダーのキャンバスおよびデバイスでのプレビューには初期値のみが表示されます。Adapty モバイルアプリはカスタムタグの値を設定しません。

アプリが旧ペイウォールビルダーのペイウォールにカスタムタグを設定している場合は、フローにおけるカスタムタグの違いを確認してください。

値が設定されていない場合にユーザーに表示されるもの

以下の場合、ユーザーにはカスタムタグの初期値がフォールバックとして表示されます。

アプリがそのタグに値を渡していない場合。
ユーザーがアプリを値を渡すバージョンにアップデートしていない場合。
アプリのコード内の名前が、大文字・小文字を含めタグのフルネームと一致していない場合。
同じテキスト要素内の別のカスタムタグに値がない場合。その場合、そのテキスト要素内のすべてのカスタムタグが初期値を表示します。

タグの位置に何も表示しないようにするには、空の文字列を渡してください。Adapty は空の文字列を値として扱うため、フォールバックは表示されません。

例：オンボーディングの回答からBMIを表示する

フローはユーザーから回答を収集でき、カスタムタグはアプリの値を表示できます。この2つを組み合わせることで、スコア、おすすめプラン、健康指標など、回答からアプリが計算した結果をユーザーに表示できます：

フローが回答を収集し、アプリに送信します。
アプリが結果を計算します。
アプリが次のフローにカスタムタグの値として結果を渡します。

この例では、オンボーディングフローがユーザーの体重と身長を収集します。ユーザーがオンボーディングフローの最後の画面を閉じると、アプリがBMI（ボディマス指数）を計算します。そして、BMIを表示するペイウォールフローを開きます。

フローを設定する

2つのフローを作成します: ユーザーの体重と身長を収集するオンボーディングフローと、BMIを表示するペイウォールフローです。
オンボーディングフローに2つのNumber入力を追加します:
- 体重（キログラム）用。Element IDをweightに設定します。
- 身長（センチメートル）用。Element IDをheightに設定します。
両方の入力で、FormatをIntegerに設定します。入力はユーザーが入力した通りのテキストとして値を送信するため、サンプルコードは”70.5”と”70,5”を同じように読み取りません。整数には小数点区切り文字がないため、すべてのロケールで同じように読み取られます。
アプリが両方の値を確実に受け取れるよう、オンボーディングフローを入力のない画面で終了させます。その画面に、Close flowアクションを持つボタンを追加します。入力はフォーカスを失ったとき、またはユーザーが別の画面に移動したときに値を送信します。Close flowアクションは値を送信しません。サンプルコードは、ユーザーが最後の画面に到達した場合にのみペイウォールを開きます。
ペイウォールフローで、bmiという名前のカスタムタグを作成します。Initial valueフィールドにダッシュ（—）を入力します。アプリがBMIを渡さない場合、ユーザーにはダッシュが表示されます。
ペイウォールフローに「Your BMI:」という文字列を含むテキスト要素を追加します。この文字列の後に、bmiカスタムタグを挿入します。
オンボーディングフローをonboardingなどのプレースメントに追加します。ペイウォールフローをID bmi_paywallのプレースメントに追加します。BMIをペイウォールに渡すのコードは、このIDでペイウォールを取得します。

ペイウォールにBMIを渡す

オンボーディングフローの flow_user_input イベントから体重と身長を収集します。詳細はフローからデータを処理するを参照してください。ユーザーが最後の画面に到達したかどうかは、is_last_screen が true に設定された flow_screen_showed イベントを監視することで確認できます。詳細はフロー画面のビューを追跡するを参照してください。その画面の後にユーザーがオンボーディングフローを閉じたら、BMIを計算します。次に、ペイウォールのビューを作成し、bmi カスタムタグにBMIを渡します。

AdaptyUI().setFlowsEventsObserverに登録するオブザーバーに以下のメソッドを追加してください。オブザーバーはflowViewDidFinishRestoreとflowViewDidReceiveErrorも実装する必要がありますが、この例では省略しています：

final Map<String, String> bodyAnswers = {};
bool reachedLastScreen = false;

void flowViewDidReceiveAnalyticEvent(
  AdaptyUIFlowView view,
  String name,
  Map<String, dynamic> params,
) {
  if (name == 'flow_screen_showed' && params['is_last_screen'] == true) {
    reachedLastScreen = true;
    return;
  }
  if (name != 'flow_user_input') return;

  final elementId = params['element_id'];
  final value = params['value'];
  if (elementId is! String || value is! String) return;

  bodyAnswers[elementId] = value;
}

void flowViewDidDisappear(AdaptyUIFlowView view) {
  // The observer receives events from every flow. Reset `bodyAnswers` and
  // `reachedLastScreen` whenever a flow disappears, so that the paywall
  // doesn't open again when the user closes it.
  final answers = Map<String, String>.of(bodyAnswers);
  final finished = reachedLastScreen;
  bodyAnswers.clear();
  reachedLastScreen = false;

  // Number inputs send their values as strings.
  final weight = double.tryParse(answers['weight'] ?? '');
  final height = double.tryParse(answers['height'] ?? '');
  if (!finished || weight == null || height == null || height <= 0) return;

  final heightInMeters = height / 100;
  final bmi = weight / (heightInMeters * heightInMeters);
  showBmiPaywall(bmi.toStringAsFixed(1));
}

Future<void> showBmiPaywall(String bmi) async {
  try {
    final flow = await Adapty().getFlow(placementId: 'bmi_paywall');
    final view = await AdaptyUI().createFlowView(
      flow: flow,
      customTags: {'bmi': bmi},
    );
    await view.present();
  } on AdaptyError catch (e) {
    // handle the error
  } catch (e) {
    // handle the error
  }
}

toStringAsFixed は常にピリオドを小数点の区切り文字として使用します。ユーザーのロケールの区切り文字を使用するには、intl パッケージの NumberFormat を使って BMI をフォーマットしてください。

BMIをユーザーのプロファイルに保存する

BMIに基づいて異なるフローをユーザーに表示するには、BMIをプロファイルのカスタム属性として保存します。Adapty ダッシュボードで、キー bmi を持つNumber カスタム属性を作成してください。その後、その属性を基に作成したオーディエンスごとに異なるフローを表示します。

flowViewDidDisappear 内で、bmi を計算する行の直後に updateProfile メソッドを呼び出します。セグメントがBMIをしきい値と比較できるよう、フォーマット済みの文字列ではなく double 型の値を渡してください。

try {
  final builder = AdaptyProfileParametersBuilder()
    ..setCustomDoubleAttribute(bmi, 'bmi');
  await Adapty().updateProfile(builder.build());
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}