integration-advisor

インテグレーションアドバイザー

目的

「X を接続したい」という要望から、完全に設定され、実行できるインテグレーションの構築までユーザーをガイドします。基本的な CRUD にとどまらず、使用するワークフローや、フィールドを適切にマッピングする方法、特定のユースケースに合わせたインテグレーションの設定方法についてもアドバイスします。Lytics には、認証方式、設定の形式、フィールドマッピングのパターンがそれぞれ異なる 110 以上のプロバイダーがあり、アドバイザーがその複雑さを解消します。

対応内容：

• エクスポート：「価値の高いオーディエンスを Facebook Custom Audiences にエクスポート」
• インポート：「Salesforce から連絡先をインポート」
• エンリッチメント：「Clearbit のデータでプロフィールをエンリッチ」

環境

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

インテグレーションアーキテクチャ

インテグレーションは 3 層モデルに従います：

Provider -- what platform
  → Auth -- how to authenticate
    → Connection -- optional, for data source integrations
      → Job -- what to do, runs a specific workflow

フロー

ステップ 1：目標を把握する

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

• プラットフォーム名（Facebook、Salesforce、Google など）
• 方向：インポート、エクスポート、エンリッチメント
• データの種類：オーディエンス、イベント、プロフィール、コンバージョン
• 特定のセグメントへの言及があるか

ステップ 2：プロバイダーを探す

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

名前で一致するプロバイダーを見つけます。候補が複数ある場合は、一致するプロバイダーを提示してユーザーに選択してもらいます。プロバイダーの is_connected: true が示されているか（認証がすでに存在するか）を確認します。

ステップ 3：既存の認証と接続を確認する

# Check for existing auth credentials
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/auth" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# Check for existing connections
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/connection" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

• このプロバイダーの有効な認証がある場合は、再利用するよう計画します
• 接続がある場合は、適切かどうかを確認します
• 認証がない場合は、認証方式に応じてユーザーをガイドします：

認証方式	案内
OAuth2	「ブラウザーで OAuth フローを完了する必要があります。Lytics UI の Settings > Integrations > [Platform] に移動して認証してください。接続が完了したら、ジョブを設定できます。」
API キー	「[Platform] の API キーが必要です。用意できたら、認証を作成できます。」
認証情報	「[Platform] のユーザー名とパスワードが必要です。」

重要：OAuth フローは CLI では完了できません。必ずユーザーに Lytics UI で OAuth 認証を行うよう案内してから、API 経由で作成された auth_id を取得してください。

ステップ 4：ワークフローを推奨する

各プロバイダーには複数のワークフローがある場合があります。ユーザーの目標に基づいて適切なものを推奨します：

複数のワークフローが該当する場合は、それぞれの違いを説明します：

「Facebook には 2 つのエクスポート方法があります：

1. Custom Audiences -- セグメントを Facebook のオーディエンスとして同期し、広告ターゲティングに使用します
2. Conversion API -- アトリビューション用のコンバージョンイベントを送信します

離脱したユーザーへのリターゲティングが目的なら、Custom Audiences が適切です。」

ステップ 5：フィールドマッピングを分析する

エクスポートの場合 -- Lytics のスキーマを対象プラットフォームが受け付けるフィールドと照合します：

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

フィールド名の類似性と型の互換性に基づいてマッピングを提案します。対象セグメントのフィールドカバレッジを確認し、一致率を予測します：

「次の Lytics フィールドを Facebook にマッピングします：

• email -> EMAIL（カバレッジ 92% -- 一致率の向上に有効）
• first_name -> FN（カバレッジ 85%）
• last_name -> LN（カバレッジ 85%）
• phone -> PHONE（カバレッジ 45% -- 補助的な一致に使用）」

インポートの場合 -- 外部データソースのスキーマを調べます：

# List tables in the connection
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/connection/${CONNECTION_ID}/schema" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# Get column schema for a specific table
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/connection/${CONNECTION_ID}/schema/${TABLE}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# Sample data to verify
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/connection/${CONNECTION_ID}/scan" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT * FROM table LIMIT 5", "primary_keys": ["user_id"]}'

外部の列から Lytics のスキーマフィールドへのフィールドマッピングを提案します：

• 名前の類似性で自動的に照合します（例：email_address -> email）
• ID となる可能性のあるフィールド（email、user_id、phone）を特定します
• マッピングされていないフィールドを警告し、含めるべきか提案します

ステップ 6：セグメントを確認する（エクスポートの場合）

ユーザーがセグメントに言及した場合は、そのセグメントが存在することを確認します：

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

エクスポートするセグメントが指定されていない場合は、次のように提案します：

「エクスポートにはセグメントが必要です。作成をお手伝いしましょうか？データを分析して、目標に最適なオーディエンスを提案できます。」 その後、audience-advisor skill または audience-builder skill に引き継ぎます。

ステップ 7：ジョブ設定を作成して確認する

ジョブの完全な設定を組み立て、確認ゲートのパターンを使って提示します：

## Proposed Integration: Export High-Value Users to Facebook Custom Audiences

**Workflow**: facebook_custom_audiences
**Auth**: Facebook OAuth (connected as [email protected])
**Segment**: High Value Customers (12,400 users)

**Field Mappings**:
  email -> EMAIL
  first_name -> FN
  last_name -> LN

**Schedule**: Continuous sync

次に、生の API ペイロードを表示します：

{
  "name": "Export High Value to Facebook",
  "workflow": "facebook_custom_audiences",
  "config": {
    "segment_id": "abc123",
    "field_mappings": { ... }
  },
  "auth_ids": ["auth_456"]
}

ステップ 8：承認を得て実行する

依存関係の順にリソースを作成します：

# Create job
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/job/${WORKFLOW}" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ ... approved config ... }'

インポートで新しい接続が必要な場合は、先に接続を作成します：

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

ステップ 9：確認する

作成後、ジョブのステータスを確認します：

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

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

初期ステータスを報告し、モニタリングを提案します：

「ジョブが作成され、実行中です。初期ステータス：active。数分後に最初の同期結果を確認するか、後ほどジョブのステータスを確認するようお知らせください。」

一般的な連携パターン

目的	ワークフローの種類	主な設定
広告のオーディエンスを再設定する	エクスポート - カスタムオーディエンス	segment_id、フィールドマッピング
コンバージョンイベントを送信する	エクスポート - Conversion API	イベントマッピング、pixel/tag ID
CRM の連絡先をインポートする	インポート - 連絡先の同期	オブジェクトタイプ、フィールドマッピング、識別フィールド
行動イベントをインポートする	インポート - イベントストリーム	イベントタイプ、タイムスタンプフィールド
メールプラットフォームと同期する	エクスポート - リストの同期	segment_id、リスト ID、フィールドマッピング
データウェアハウスにエクスポートする	エクスポート - テーブルへの書き込み	データセット、テーブル、書き込みモード、パーティション

フィールドマッピングのヒューリスティクス

Lytics からプラットフォームへの一般的なフィールドマッピング：

Lytics フィールド	Facebook	Google Ads	Salesforce	一般
email	EMAIL	hashedEmail	Email	email
first_name	FN	firstName	FirstName	first_name
last_name	LN	lastName	LastName	last_name
phone	PHONE	hashedPhone	Phone	phone
country	COUNTRY	countryCode	MailingCountry	country
city	CT	city	MailingCity	city
zip	ZIP	zipCode	MailingPostalCode	postal_code

エラー処理

• プロバイダーが見つかりません：類似するプロバイダーを一覧表示し、ユーザーに уточ明を求めます
• 認証がありません：OAuth の場合は Lytics UI への移動を案内するか、API キー認証の作成を支援します
• 認証の有効期限切れ：Lytics UI で再認証するよう提案します
• 一致するワークフローがありません：そのプロバイダーで利用可能なワークフローを一覧表示します
• セグメントが見つかりません：audience-builder または audience-advisor での作成を提案します
• 接続スキャンに失敗しました：認証情報と外部システムへのネットワークアクセスを確認します
• ジョブの作成に失敗しました：エラーを解析し、必須の設定フィールドを確認します

依存関係

• 構成要素：connection-manager skill、job-manager skill、schema-discovery skill、../references/confirmation-gate.md
• 参照：../references/auth.md
• 関連：audience-advisor skill、audience-builder skill（エクスポートするセグメントを作成する場合）