audience-advisor

オーディエンスアドバイザー

目的

どのようなオーディエンスでもよいのではなく、ビジネス上の目標達成に適したオーディエンスを構築できるようユーザーを支援します。Lytics の分析 API（ML の特徴量重要度、コンテンツへの親和性、fieldinfo の分布、セグメントの概要）を活用し、根拠に基づいた提案を行います。高度な機能が設定されていない場合は、適切に機能を制限して対応します。

次の 2 つのモードに対応しています。

• 目標から作成：「購入を増やすためのオーディエンスの構築を手伝ってください」
• 既存セグメントを改善：「『高価値顧客』セグメントを改善するにはどうすればよいですか？」

環境

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

フロー

ステップ 1：意図を理解する

ユーザーに必要なモードを判断します。

パス A — ビジネス目標から新しいオーディエンスを作成する場合： 希望するオーディエンスではなく、達成したいことを尋ねます。

• 「購入を増やす」→ コンバージョン重視
• 「休眠ユーザーの利用を再開させる」→ リテンション重視
• 「メール購読者を増やす」→ 獲得重視
• 「新しい製品ラインを宣伝する」→ 認知度重視

目標の種類を分類します。これにより、後で優先するフィールドと戦略が決まります。

パス B — 既存のセグメントを改善する場合： セグメント名または ID を受け取り、そのセグメントと現在の FilterQL を取得します。

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

一致するセグメントを見つけ、現在のサイズを記録し、既存のフィルターを把握するために FilterQL を解析します。

どちらのパスもステップ 2 に進みます。

ステップ 2：既存のセグメントを調査する

すでに構築されているものを把握するため、すべてのセグメントを取得します。

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

• 名前、タグ、または種別から、目標に関連するセグメントを特定します
• 「goal」または「conversion」種別のセグメントを探します。これらはビジネス上の成果を表し、参考情報として役立ちます
• 後で割合を計算できるよう、母集団全体のサイズを記録します
• 重複を避けるため、すでにこの目標を対象としているセグメントがあれば、その旨を記録します

ステップ 3：分析シグナルを収集する

各データソースを試してください。空の結果またはエラーが返された場合はスキップし、利用可能な情報を使って進めてください。

3a. ML の特徴量重要度（最も有力なシグナルですが、存在しない場合があります）：

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/ml" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

モデルが存在する場合は、ターゲットセグメントがユーザーの望む結果に一致するものを探してください。各モデルは、ユーザーがターゲットセグメントにどの程度類似しているかを予測します。

• すべてのモデルを一覧表示し、ターゲットセグメントの名前と説明を確認します

• ターゲットセグメントをユーザーが述べた目標に照らして照合します（例：目標が「購入を促進する」の場合、「購入者」または「コンバージョンしたユーザー」をターゲットとするモデルを探します）

• 関連するモデルが見つかった場合は、その概要を取得します：

  curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/ml/${MODEL_ID}/summary" \
    -H "Authorization: ${LYTICS_API_TOKEN}"
  

  応答には、モデルの品質指標と、ターゲットオーディエンスを最もよく区別するフィールドを順位付けしたfeatures配列が含まれます：

  {
    "data": {
      "id": "model_id",
      "name": "Model Name",
      "state": "completed",
      "summary": {
        "auc": 0.85,
        "accuracy": 0.82,
        "reach": 0.75,
        "model_health": "good",
        "mse": 0.12,
        "rsq": 0.71
      },
      "features": [
        {
          "kind": "score",
          "type": "numeric",
          "name": "visit_count",
          "importance": 1.79,
          "field_prevalence": {"source": 0.30, "target": 0.99},
          "correlation": 0.23,
          "impact": {"lift": 0.35, "threshold": 2}
        }
      ]
    }
  }
  

  レコメンデーションに役立つ主な特徴量フィールド：

  • name -- フィルターに使用するスキーマフィールド名です
  • importance -- 値が高いほど、ターゲットセグメントへの所属をより正確に予測します
  • field_prevalence.source と .target -- 一般ユーザーとターゲットの間で、そのフィールドがどの程度一般的かを示します（差が大きいほど、強い識別要因です）
  • correlation -- 関係の方向と強さを示します
  • impact.lift -- このフィールドによって、ターゲットに属する可能性がどの程度高まるかを示します
  • impact.threshold -- フィルタリングに推奨されるカットオフ値です

• 目標に関連するターゲットセグメントを持つモデルがない場合：ML をスキップします。ユーザーに次のように伝えてください：「この成果をターゲットとする ML モデルはありません。コンバージョンセグメントをターゲットとして類似ユーザーモデルを作成すると、予測に役立つ特徴量のランキングを取得できます。」

• 該当するモデルが複数ある場合：ターゲットセグメントが目標に最も近いモデルを優先します。

• モデルがまったく存在しない場合：何も伝えずにスキップし、次のシグナルに進みます。

3b. コンテンツアフィニティ（設定されていない場合があります）：

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/content/affinity" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

アフィニティが存在し、参照セグメントが利用できる場合：

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/content/recommend/segment/${SEGMENT_ID}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

これにより、オーディエンスを特徴づけるトピックへの関心が明らかになります。設定されていない場合は、何も伝えずにスキップします。

3c. Fieldinfo 分析（常に利用可能なベースライン）：

参照セグメント（目標／コンバージョンセグメント、または改善対象のセグメント）を指定します。 重要：スラッグ名ではなく、セグメントのidハッシュを使用してください。スラッグを使うと HTTP 500 が返されます。

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/${SEGMENT_ID}/fieldinfo?limit=50" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

アスペクトの重複を含むセグメント概要の場合：

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/${SEGMENT_ID}/summary" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

参照セグメントがない場合は、スキーマレベルのフィールド分布を使用します：

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/schema/user/fieldinfo" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

これは常に機能します。フィールドの網羅率、値の分布、カーディナリティは常に利用可能です。

ステップ 4：情報を統合して提案する

シグナルの強さごとに整理して、調査結果を提示します。

ML の特徴量重要度がある場合：

「『購入者』をターゲットとする ML モデルでは、次の項目が上位の予測要因として挙げられています：

1. visit_count -- 訪問回数が5回以上のユーザーは、コンバージョンする可能性が3.2倍高くなります
2. email_engagement -- メールをよく読むユーザーは、ベースラインの2.8倍の割合でコンバージョンします
3. products_viewed -- 3つ以上の商品カテゴリを閲覧している場合、購入意向が高いことを示します

これらのフィールドを中心にフィルターを作成することをおすすめします。」

コンテンツアフィニティがある場合：

「コンバージョンしたユーザーは、『テクノロジー』コンテンツ（ベースライン比3.2倍）と『製品レビュー』（2.5倍）への関心が特に高くなっています。コンテンツアフィニティをターゲティングシグナルとして使うことをご検討ください。」

fieldinfo のみの場合（常に利用可能）：

「『最近購入したユーザー』セグメントを見ると：

• 78% のユーザーが visit_count >= 5 です（全ユーザーでは30%）
• 92% のユーザーに email が設定されています（メールキャンペーンに適しています）
• country：65% が US、15% が CA、10% が UK

visit_count >= 5 でフィルタリングすると、コンバージョンしたユーザーの大半を含めながら、購入意向の低いユーザーを除外できます。」

既存のセグメントを改善する場合：

「現在、『高価値』セグメントには50,000人（全体の35%）が含まれています。ターゲットを絞ったキャンペーンにはやや広すぎます。次のことがわかりました：

• フィルターEXISTS emailは全ユーザーの92%に一致するため、選別効果はあまりありません
• このセグメントのうち、purchase_historyが設定されているのは20%だけです。このフィールドはここでは役に立たない可能性があります
• visit_count >= 5を追加すると、実際にコンバージョンしたユーザーの78%を維持しながら、15,000人（10%）に絞り込めます

更新後の FilterQL の提案： FILTER AND (visit_count >= 5, email_engagement > 0.3) FROM user ALIAS high_value_v2」

Step 5: サイジングを繰り返す

セグメントを作成せずに、フィルターのバリエーションをテストします。各変更がオーディエンスサイズに与える影響をユーザーに示します：

# Get total population size for percentage context
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/size" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: text/plain" \
  -d 'FILTER * FROM user'

# Test each filter variation
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/size" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: text/plain" \
  -d 'FILTER AND (visit_count >= 5) FROM user'

段階的な絞り込みとして提示します：

Starting point: 145,000 total users (100%)

1. visit_count >= 5          -> 43,500 (30%)
2. + email_engagement > 0.3  -> 18,200 (13%)
3. + last_visit > "now-30d"  -> 12,400 (9%)   <-- recommended

This 9% audience captures your highest-intent users with recent activity.

サイジングの前に、各 FilterQL を検証します：

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/validate" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: text/plain" \
  -d 'FILTER AND (visit_count >= 5, email_engagement > 0.3, last_visit > "now-30d") FROM user'

Step 6: 確認して作成する

提案したオーディエンスにユーザーが納得したら、完全な確認ゲートパターンを使用してセグメントを作成するため、audience-builder skill に引き継ぎます。

既存のセグメントを改善する場合は、代わりに PUT /v2/segment/:id を使用します。

Step 7: 作成後のスナップショット

作成後、audience-snapshot skill を実行して最終的なオーディエンス構成を表示し、問題がないことを確認するよう提案します。

オーディエンスのサイジングに関するガイダンス

全体に占める割合	評価	最適な用途
< 1%	非常に狭く、リーチや統計的有意性が制限される可能性があります	高度なパーソナライズ、VIP プログラム
1-10%	適切にターゲティングされています	コンバージョンキャンペーン、リターゲティング
10-30%	広範なターゲティングです	認知度向上キャンペーン、一斉メール配信
> 30%	非常に広範です。ターゲティングを絞ると ROI が向上するか検討してください	広範な告知のみ

目標タイプ別のフィールド選択ガイダンス

目標	推奨されるフィールドタイプ	理由
コンバージョン／購入	行動：visit_count、pages_viewed、カートのアクティビティ	行動はデモグラフィック情報よりも意図を正確に予測できます
再エンゲージメント／維持	時間：last_visit、last_purchase、経過時間スコア	経過時間から利用が途絶えたユーザーを特定できます
認知度／リーチ	デモグラフィック：country、industry、interest categories	広範な属性から適切な対象層にリーチできます
メール／チャネルの拡大	チャネル：email_opt_in、channel_preferences、エンゲージメントスコア	チャネル固有のシグナルが最も重要です

絞り込みパターン

• 広く始めて、段階的に絞り込む -- 各段階でサイズへの影響を示し、トレードオフをユーザーが理解できるようにします
• 絞り込むには AND、広げるには OR を使用する -- 条件の組み合わせ方をユーザーに案内します
• 推奨する前にフィールドのカバレッジを確認する -- カバレッジが 20% のフィールドを使うと、オーディエンスは最大でも 20% に制限されます
• セット型フィールドには INTERSECTS を優先する（例：products_purchased）。数値には比較演算子を使用します
• 時間によるターゲティングには日付計算を使用する -- 最近なら "now-30d"、中期なら "now-90d"、長期なら "now-1y" を使用します

エラー処理

• ML モデルがない場合：適切にスキップし、フィールド情報の分析を利用します。類似モデルの作成を提案します。
• アフィニティがない場合：通知せずにスキップし、フィールド情報を使って続行します。
• コンバージョン／目標セグメントがない場合：理想的な顧客の特徴を手動で説明するようユーザーに依頼します。スキーマ探索を使って、一致するフィールドを見つけます。
• フィルタリング後にセグメントが空になる場合：最も制約の厳しいフィルターを削除するか、しきい値を調整して対象を広げるよう提案します。
• ユーザーが目標に迷っている場合：一般的な目標カテゴリを提示し、選択してもらいます。

依存関係

• 組み合わせるもの：audience-builder skill、audience-snapshot skill、segment-manager skill、schema-discovery skill
• 参照先：../references/auth.md、../references/api-client.md、../references/field-types.md、../references/filterql-grammar.md