メインコンテンツへスキップ

はじめに

Connected Sources は、あらゆる外部プラットフォームから MoEngage に直接リアルタイムでデータをストリーミングできる、MoEngage の柔軟な Webhook 連携フレームワークです。CRM、e コマースプラットフォーム、マーケティングツール、カスタムアプリケーションを標準化されたアプローチで連携できます。

仕組み

次の 3 つのシンプルなステップで、あらゆる外部システムを接続できます。

Webhook POST

お客様のシステムが JSON ペイロードを MoEngage のエンドポイントに送信します

変換

マッパーがデータを抽出して検証します

インポート

データがイベントとプロファイルに取り込まれます

主な機能

  • リアルタイムイベント: ユーザーのアクションを発生と同時にストリーミングします
  • プロファイルの同期: ユーザー属性を自動的に更新します
  • 一括処理: 1 回の呼び出しでバッチを処理します
  • 柔軟なマッピング: 複雑な JSON 構造を変換します
  • 日付の結合: 別々の日付/時刻フィールドを結合します
  • 動的属性: カスタムフィールドを自動的にインポートします

ユースケース

  • 📝 リードの獲得: Unbounce、Typeform、HubSpot からのフォーム送信をストリーミングして、即座にフォローアップします
  • 💳 支払いイベント: Stripe、Chargebee からのサブスクリプション (作成、失敗、期限切れ間近) を追跡します
  • 🎫 サポートチケット: Zendesk/Intercom でのやり取りを監視して、満足度を追跡します
  • 🛒 e コマース: カスタムプラットフォームから注文、カート、閲覧を取得します
  • 🛠️ カスタムアプリ: ネイティブ SDK なしで独自システムからイベントを送信します

🚀 連携を構築する

次の 5 つのステップに従って、サンプルペイロードから MoEngage への本番データフローまでを実現します。
  1. 準備: 前提条件とペイロード
  2. 作成: マッパーを構築する
  3. 提出: MoEngage に送信する
  4. 設定: Webhook URL を追加する
  5. テスト: データフローを確認する

準備: 前提条件とサンプルペイロード

マッパーを構築する前に、必要なものがすべて揃っていることを確認してください。
必要なもの:
  • お客様のシステムの Webhook 機能 (HTTP POST)
  • 認証のサポート (Basic 認証またはカスタムヘッダー)
  • 有効な JSON Webhook ペイロード
  • お客様のシステムからの 2~3 件のサンプルペイロード
  • MoEngage の認証情報 (Settings → APIs の Workspace ID、Data API Key)
⚡ レート制限推奨最大値: 200 リクエスト/秒より高いスループットが必要な場合は、想定されるボリューム、ユースケースの説明、ピーク時/平均のパターン、データセンターの場所を添えて、Solutions Engineering チームにお問い合わせください。
💡 早めに検証しましょう: 先に進む前に、サンプルペイロードを JSONLint に貼り付けて、有効な JSON であることを確認してください。

作成: マッパー設定を構築する

マッパーは、受信した Webhook データをイベントまたはユーザープロファイルにどのように変換するかを MoEngage に指示する JSON 設定です。これが連携の中核です。

📋 マッピングタイプを選択する

2 つの同期タイプを利用できます:
  • mapping_type: "events" - イベントを追跡し、かつユーザープロファイルを作成/更新します
  • mapping_type: "users" - ユーザープロファイルの作成/更新のみを行います (イベントなし)

マッピングタイプ別のフィールド要件

📍 JSONPath クイックリファレンス

JSONPath 式を使用して、ペイロードのフィールドを MoEngage のフィールドにマッピングします。読み方は次のとおりです。

📌 フィールドの完全なリファレンス

📋 スターターテンプレート

このテンプレートをコピーし、JSONPath 式を実際のペイロードのパスに置き換えてください。

💡 実際の動作を見る: 実践的な例

各例をクリックすると、ペイロードと対応するマッパー設定を並べて確認できます。
シナリオ: リードフォームが送信時に連絡先情報を送信する
ポイント: メールを一意の ID として使用 • 静的なイベント名 • エポックタイムスタンプ • ユーザープロファイルを更新
シナリオ: システムが 1 つの Webhook で複数の注文を送信する
✅ ポイント: 配列の場合は batching=true • [*] ワイルドカードで反復処理 • 注文ごとに個別のイベントを作成
シナリオ: 別々の日付フィールドと時刻フィールドを結合する必要がある
✅ ポイント: user_time="#MERGE" で結合を指示 • #MERGE セクションでフィールドを定義 • formats でパターンを指定
シナリオ: CRM がイベントトラッキングなしでプロファイルの更新を送信する
✅ ポイント: mapping_type="users" • イベントは作成されない • event_name/user_time/platform は不要
シナリオ: ログイン前の行動を追跡し、識別後に結合する
🔄 結合フロー: ログイン後、customer_id と anon_id の両方を含むイベントを送信します。MoEngage は匿名の履歴を識別済みのプロファイルに自動的に結合します。
プロのヒント: create_all の使用create_all 属性を使用すると、ペイロード内の指定したオブジェクトに含まれるすべてのキーを反復処理できます。キーが動的である、頻繁に変更される、または絶えず増えていくオブジェクトを扱う場合に強くお勧めします。新しいフィールドを 1 つずつ手動でマッピングする代わりに、create_all を使えばすべてを一度に取得できます。
シナリオ: カスタムフィールドが user_attributes オブジェクトに絶えず追加される CRM からユーザープロファイルを同期する。
✅ ポイント: 標準フィールドは直接マッピング (例: u_fn) • create_all により、明示的なマッピングなしで lead_score、industry、lifecycle_stage が自動的に取り込まれます。
シナリオ: CRM が、ユーザープロパティとイベントの詳細の両方に動的で予測できないキーを含むイベントを送信する。
✅ ポイント: create_all は user_attributes とイベントの attr オブジェクトの両方で同時に機能します • 高度にカスタマイズされた CRM ペイロードに最適です。
タイムスタンプ: 可能な場合は エポックミリ秒 (整数) を使用してください。形式の指定は不要です。ペイロードで文字列のタイムスタンプを使用している場合は、formats セクションで形式を指定してください。
T、Z、マイクロ秒のサフィックスを付けた dd/MM/yyyy および dd-MM-yyyy のバリエーションもサポートされています。
🎨 ビジュアルツールを使いたい場合 Visual Mapper Generator を使用すると、ガイド付きのインターフェースで JSON 設定を構築できます。

提出: マッパーを MoEngage に送信する

マッパー JSON の準備ができたら、次の内容を添えて [email protected] にメールで送信してください。
  • 完成したマッパー JSON (添付)
  • サンプルの Webhook ペイロード
  • 連携の詳細: パートナー名、Workspace ID、データセンター、ユースケース

設定: Webhook URL を追加する

MoEngage から一意の Webhook URL が提供されます。Basic 認証の認証情報 (ユーザー名として Workspace ID、パスワードとして Data API Key) を使用して、この URL をソースシステムに追加します。 イベントの場合: https://api-0X.moengage.com/v1/partner/<partner_name>/events/?configName=<config_name> ユーザーの場合: https://api-0X.moengage.com/v1/partner/<partner_name>/users/?configName=<config_name>

テスト: データフローを確認する

Postman を使用して、サンプルペイロードを Webhook URL に送信します。200 OK レスポンスを確認し、request_id を保存してから、MoEngage ダッシュボード → Analytics → Events を確認します (処理には 1~2 分かかります)。

✅ API レスポンスについて

レスポンスコードによって結果が異なります。
ステータス: リクエストは正常に受信され、処理のためにキューに登録されました。
次のステップ: request_id を保存してください。データは 1~2 分以内に MoEngage に表示されます。
原因: マッパーで必須として定義されているフィールドがペイロードにありません。
🔧 修正方法: JSONPath 式がペイロードの構造と一致していることを確認し、すべての必須フィールドが存在することを確認してください。
原因: JSON ペイロードの形式が不正であるか、想定される構造と一致していません。
🔧 修正方法: JSONLint を使用して JSON を検証し、波かっこ、角かっこ、カンマの欠落がないか確認してください。
原因: Basic 認証の認証情報が無効であるか、Authorization ヘッダーがありません。
🔧 修正方法: Postman で Basic Auth を選択し、ユーザー名に Workspace ID、パスワードに Data API Key を入力してください。
上記に記載されていないエラーレスポンスが発生した場合は、次の情報を添えて MoEngage Solutions Engineering にお問い合わせください。
  • 完全なエラーレスポンス (JSON)
  • マッパー設定 (JSON)
  • テストしていたサンプルペイロード (JSON)
  • 想定される動作と実際の動作

🔧 よくある問題

❌ イベントが表示されない 200 OK レスポンスを確認 • customer_id のパスを確認 • タイムスタンプの形式を確認 • 2~3 分待つ • request_id を添えて MoEngage に問い合わせる 🔀 属性が正しくない jsonpath.com で JSONPath をテスト • ペイロードの構造を確認 • フィールド名のタイプミスを確認 (大文字と小文字を区別) ⏰ タイムスタンプのエラー 形式文字列を正確に一致させる • 可能な場合はエポックミリ秒を使用 • ISO 形式の場合はタイムゾーンを含める 📦 一括処理が行われない batching=true を設定 • すべてのパスで [*] を使用 • ペイロード内の配列の位置を確認 ✨ create_all の問題 パスがオブジェクトを指していることを確認 • キーと値のペアであることを確認 • ネストを確認 (1 階層のみ機能)

🛠️ 便利なツール

✅ JSONLint 構文を検証 jsonlint.com にアクセス → 🗺️ JSONPath 式をテスト jsonpath.com にアクセス → 🪝 Webhook.site ペイロードを検査 webhook.site にアクセス → 📮 Postman API 呼び出しをテスト postman.com にアクセス → ⏰ Epoch Converter 日付の変換 epochconverter.com にアクセス → 🎨 Mapper Generator ビジュアル設定ツール ツールを開く →

❓ よくある質問

はい。マッパーに user_attributes と attr の両方を含めてください。プロファイルの更新とイベントの作成が同時に行われます。
新しいプロファイルが自動的に作成されます。customer_id がすでに存在する場合、イベントは既存のプロファイルに関連付けられます。
はい。更新した JSON を添えて MoEngage にお問い合わせください。新しい config_name を持つ新しいバージョンがデプロイされます。古い URL は以前のマッパーで引き続き機能します。
最大 1MB を推奨します。一括リクエストの場合、最適なパフォーマンスを得るには 1 回の呼び出しあたり 100~500 件のイベントをバッチ処理してください。
JSONPath 表記を使用します。特定のアイテムには $.orders[0].items[0].name、バッチ処理には $.orders[*].items[*].name を使用します。複雑なネストの場合は、事前にフラット化が必要になることがあります。

🆘 サポート

お困りですか?
  • 💬 一般的な質問: MoEngage のカスタマーサクセスマネージャーにお問い合わせください
  • 🔧 テクニカルサポート: 次の情報を添えて [email protected] にメールでお問い合わせください:
    • マッパー JSON (添付)
    • サンプルの Webhook ペイロード
    • レスポンスのリクエスト ID
    • 問題の説明
  • 🎨 マッパーに関するサポート: ペイロードと要件を共有していただければ、当社のチームがサポートします