campaign-flow-builder

キャンペーンフロービルダー

目的

「ウェルカムメールのシリーズを作りたい」といったビジネス上の意図から、エントリーセグメント、遅延、条件分岐、A/Bテスト、エクスポート手順を備えた、検証済みの完全なフローを作成できるようユーザーを導きます。アドバイザーパターンに従い、目標を把握し、構成を提案し、反復してから作成します。

フローはLyticsオブジェクトの中で最も複雑です。このスキルにより、フローを扱いやすくします。

環境

認証済みのAPIアクセスが必要です。認証情報の解決については、../references/auth.mdを参照してください。

フローAPI形式

フローでは、ノードとエッジのグラフ表現（TranslatedFlow形式）を使用します。

• ノード：ジャーニーのステップ（トリガー、遅延、エクスポート、条件分岐、A/Bテスト、終了）
• エッジ：ステップ間の接続（オプションで条件または確率を指定）

フローの作成

ステップ1：キャンペーンの目標を把握する

ユーザーの意図を分類します。

• 「ウェルカムメールのシリーズ」→セグメントへのエントリーをトリガーにし、メール間に遅延を設定
• 「再エンゲージメントキャンペーン」→離脱ユーザーをトリガーにし、条件を確認してエクスポート
• 「2つのオファーをA/Bテスト」→トリガー、A/B分岐、2つのエクスポート経路
• 「マルチチャネルのナーチャリング」→トリガー、遅延、条件分岐、複数のエクスポートチャネル

次の点を確認します。

• エントリーのトリガーは何ですか？（セグメントに入る、セグメントに属している）
• ステップ／タッチポイントはいくつありますか？
• 分岐ロジックはありますか？（VIPと標準、エンゲージメントありとなし）
• ステップ間のタイミングはどうしますか？
• ユーザーは再エントリーできますか？

ステップ2：エントリーセグメントを確認する

フローにはトリガーセグメントが必要です。存在するか確認します。

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment?table=user&sizes=true" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

適切なセグメントがない場合は、audience-builder skillまたはaudience-advisor skillを使って作成するよう提案します。

ステップ3：フローの構成を設計する

提案するフローのテキスト形式の図を提示します。

TRIGGER: On entry to "New Signups" segment
  |
  v
[Send Welcome Email] (export)
  |
  v
[Wait 3 days] (delay)
  |
  v
[Opened Welcome?] (conditional split)
  |           |
  YES         NO
  |           |
  v           v
[Send Offer] [Send Reminder]
  |           |
  v           v
[EXIT]       [EXIT]

ユーザーが構成に納得するまで、反復して調整します。

ステップ4：フローペイロードを作成する

ノードの種類

トリガー（常にsequence_id: 0）：

{
  "sequence_id": 0,
  "type": "trigger",
  "entry_segment_id": "segment-uuid-here",
  "entry_condition": "on_segment_entry",
  "reentry_allowed": false,
  "reentry_delay": 86400
}

エントリー条件：

• "on_segment_entry" -- ユーザーがセグメントに入ったときに実行されます（イベントベースで、最も一般的です）
• "in_segment" -- 現在セグメントに属しているユーザーに対して実行されます（スナップショット）

再エントリー遅延の単位は秒です。最小値は3600（1時間）です。

エクスポート（外部プラットフォームに送信）：

{
  "sequence_id": 1000,
  "type": "export",
  "label": "Send Welcome Email",
  "work_config": {}
}

work_configは、フロー作成後にworkエンドポイントから別途設定します。

遅延（ステップ間で待機）：

{
  "sequence_id": 2000,
  "type": "delay",
  "label": "Wait 3 days",
  "delay": 259200000000000
}

遅延の単位はナノ秒です。一般的な値：

• 1時間：3600000000000
• 24時間：86400000000000
• 3日：259200000000000
• 7日：604800000000000

オプション：delay_condition（FilterQL）--条件を満たした場合にのみ続行します。 オプション：delay_until_enters（セグメントIDの配列）--ユーザーが指定されたすべてのセグメントに入るまで待機します。

条件分岐（if/else分岐）：

{
  "sequence_id": 3000,
  "type": "conditional_split",
  "label": "Opened Welcome?"
}

条件はノードではなくエッジに定義します。「エッジ」のセクションを参照してください。

A/Bテスト（ランダム分岐）：

{
  "sequence_id": 4000,
  "type": "ab_test",
  "label": "50/50 Test"
}

確率はエッジに定義します。合計は1.0でなければなりません。

終了（フローの終端）：

{
  "sequence_id": 9999,
  "type": "exit"
}

エッジの種類

単純な接続：

{"id": "0-1000", "source": 0, "target": 1000, "type": "connected"}

条件分岐エッジ（FilterQLを使用）：

{
  "id": "3000-4000",
  "source": 3000,
  "target": 4000,
  "type": "connected",
  "condition": {
    "definition": "FILTER AND (email_opened = true) FROM user",
    "label": "Yes",
    "priority": 2
  }
}

優先度の数値が大きいものから先に確認されます。デフォルト／フォールバックエッジでは、"definition": ""および"priority": 1を指定してください。

A/Bテストエッジ（確率を指定）：

{
  "id": "4000-5000",
  "source": 4000,
  "target": 5000,
  "type": "connected",
  "probability": 0.5
}

同じソースノードからの確率の合計は1.0でなければなりません。

ステップIDの割り当て

• トリガーは常にsequence_id: 0です
• その他のIDはすべて呼び出し側が割り当てる正の整数です（フロー内で一意である必要があります）
• 見やすくするため、1000の倍数（1000、2000、3000）を使うのが慣例です

ステップ5：確認して作成する

確認ゲートパターンを使用します。次の内容を提示します。

• フロー図（テキスト形式）
• エントリーセグメント名とサイズ
• ステップ数と種類
• タイミングの概要
• APIペイロードの生データ

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/flow/ui" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ ... flow payload ... }'

ステップ6：エクスポートステップを設定する

フローがドラフト状態で作成されたら、各エクスポートステップのwork／エクスポートを設定します。

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/flow/ui/${FLOW_ID}/step/${STEP_ID}/work" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ ... work configuration ... }'

その後、workを公開します。

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/flow/ui/${FLOW_ID}/step/${STEP_ID}/work/publish" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

ステップ 7：フローを有効化する

すべてのエクスポートステップで作業が公開されたら、フローを有効化します。

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/flow/ui/${FLOW_ID}" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"state": "running"}'

重要：同時にrunningにできるフローのバージョンは 1 つだけです。新しいバージョンを公開すると、古いバージョンは自動的にdrainingに設定されます。

よくあるキャンペーンパターン

ウェルカムシリーズ

TRIGGER (on_segment_entry: "New Signups")
  -> [Send Welcome] -> [Wait 3d] -> [Send Tips] -> [Wait 7d] -> [Send Offer] -> EXIT

再エンゲージメント

TRIGGER (in_segment: "Lapsed 30d")
  -> [Send Win-Back] -> [Wait 7d]
  -> CONDITIONAL (opened email?)
     YES -> [Send Discount] -> EXIT
     NO  -> [Send Final Notice] -> EXIT

A/B テスト

TRIGGER (on_segment_entry: "Trial Users")
  -> [Wait 1d]
  -> A/B TEST (50/50)
     A -> [Send Offer A] -> EXIT
     B -> [Send Offer B] -> EXIT

マルチチャネルのナーチャリング

TRIGGER (on_segment_entry: "High Intent")
  -> [Send Email] -> [Wait 2d]
  -> CONDITIONAL (converted?)
     YES -> EXIT
     NO  -> [Push Notification] -> [Wait 3d]
           -> [Retarget on Facebook] -> EXIT

フローの状態

状態	説明	編集可能？
draft	非アクティブで、完全に編集可能です	はい -- ステップの追加／削除／変更
running	アクティブで、ユーザーを処理しています	一部可能 -- work_config、ラベル、条件は更新できますが、ステップの追加／削除はできません
draining	終了処理中で、新しいエントリーはありません	runningと同じ
deleted	完全に削除されています	いいえ

エラー処理

• 条件の FilterQL が無効：フローを作成する前に条件を検証します
• 確率の合計が 1.0 ではない：調整して再試行します
• エントリーセグメントが見つからない：audience-builder を使って作成できるよう案内します
• ステップ ID が重複している：一意の値を生成し直します
• work config が不足している：エクスポートステップの設定を案内します

依存関係

• 構成要素：segment-manager skill、audience-builder skill、job-manager skill
• 参照先：../references/filterql-grammar.md、../references/confirmation-gate.md、../references/auth.md、../references/api-client.md