はじめに
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 への本番データフローまでを実現します。- 準備: 前提条件とペイロード
- 作成: マッパーを構築する
- 提出: MoEngage に送信する
- 設定: Webhook URL を追加する
- テスト: データフローを確認する
準備: 前提条件とサンプルペイロード
マッパーを構築する前に、必要なものがすべて揃っていることを確認してください。必要なもの:
- お客様のシステムの 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"- ユーザープロファイルの作成/更新のみを行います (イベントなし)
- Events マッパー
- Users マッパー
マッピングタイプ別のフィールド要件
📍 JSONPath クイックリファレンス
JSONPath 式を使用して、ペイロードのフィールドを MoEngage のフィールドにマッピングします。読み方は次のとおりです。📌 フィールドの完全なリファレンス
📋 スターターテンプレート
このテンプレートをコピーし、JSONPath 式を実際のペイロードのパスに置き換えてください。💡 実際の動作を見る: 実践的な例
各例をクリックすると、ペイロードと対応するマッパー設定を並べて確認できます。📝 例 1: シンプルなフォーム送信
📝 例 1: シンプルなフォーム送信
シナリオ: リードフォームが送信時に連絡先情報を送信する
- ペイロード
- マッパー設定
ポイント: メールを一意の ID として使用 • 静的なイベント名 • エポックタイムスタンプ • ユーザープロファイルを更新
🛒 例 2: e コマース注文の一括処理
🛒 例 2: e コマース注文の一括処理
シナリオ: システムが 1 つの Webhook で複数の注文を送信する
- ペイロード
- マッパー設定
✅ ポイント: 配列の場合は
batching=true • [*] ワイルドカードで反復処理 • 注文ごとに個別のイベントを作成📅 例 3: 日付と時刻の結合
📅 例 3: 日付と時刻の結合
シナリオ: 別々の日付フィールドと時刻フィールドを結合する必要がある
- ペイロード
- マッパー設定
✅ ポイント:
user_time="#MERGE" で結合を指示 • #MERGE セクションでフィールドを定義 • formats でパターンを指定👤 例 4: ユーザープロファイルの同期のみ
👤 例 4: ユーザープロファイルの同期のみ
シナリオ: CRM がイベントトラッキングなしでプロファイルの更新を送信する
- ペイロード
- マッパー設定
✅ ポイント:
mapping_type="users" • イベントは作成されない • event_name/user_time/platform は不要🔒 例 5: 匿名ユーザーのトラッキング
🔒 例 5: 匿名ユーザーのトラッキング
シナリオ: ログイン前の行動を追跡し、識別後に結合する
- ペイロード
- マッパー設定
🔄 結合フロー: ログイン後、
customer_id と anon_id の両方を含むイベントを送信します。MoEngage は匿名の履歴を識別済みのプロファイルに自動的に結合します。🔄 例 6: 動的なユーザープロパティ (create_all)
🔄 例 6: 動的なユーザープロパティ (create_all)
シナリオ: カスタムフィールドが
user_attributes オブジェクトに絶えず追加される CRM からユーザープロファイルを同期する。- ペイロード
- マッパー設定
✅ ポイント: 標準フィールドは直接マッピング (例:
u_fn) • create_all により、明示的なマッピングなしで lead_score、industry、lifecycle_stage が自動的に取り込まれます。🔀 例 7: 動的なイベント属性 (create_all)
🔀 例 7: 動的なイベント属性 (create_all)
シナリオ: CRM が、ユーザープロパティとイベントの詳細の両方に動的で予測できないキーを含むイベントを送信する。
- ペイロード
- マッパー設定
✅ ポイント:
create_all は user_attributes とイベントの attr オブジェクトの両方で同時に機能します • 高度にカスタマイズされた CRM ペイロードに最適です。📅 サポートされている日付形式のリファレンス
📅 サポートされている日付形式のリファレンス
T、Z、マイクロ秒のサフィックスを付けた dd/MM/yyyy および dd-MM-yyyy のバリエーションもサポートされています。
提出: マッパーを 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 レスポンスについて
レスポンスコードによって結果が異なります。✅ 200 OK - 送信成功
✅ 200 OK - 送信成功
ステータス: リクエストは正常に受信され、処理のためにキューに登録されました。
次のステップ:
request_id を保存してください。データは 1~2 分以内に MoEngage に表示されます。❌ 400 Bad Request - 必須フィールドの欠落
❌ 400 Bad Request - 必須フィールドの欠落
原因: マッパーで必須として定義されているフィールドがペイロードにありません。
🔧 修正方法: JSONPath 式がペイロードの構造と一致していることを確認し、すべての必須フィールドが存在することを確認してください。
❌ 400 Bad Request - 無効なペイロード構造
❌ 400 Bad Request - 無効なペイロード構造
原因: JSON ペイロードの形式が不正であるか、想定される構造と一致していません。
🔧 修正方法: JSONLint を使用して JSON を検証し、波かっこ、角かっこ、カンマの欠落がないか確認してください。
❓ その他のエラー - SE に問い合わせる
❓ その他のエラー - SE に問い合わせる
上記に記載されていないエラーレスポンスが発生した場合は、次の情報を添えて 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 が存在しない場合はどうなりますか?
customer_id が存在しない場合はどうなりますか?
新しいプロファイルが自動的に作成されます。
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
- 問題の説明
- 🎨 マッパーに関するサポート: ペイロードと要件を共有していただければ、当社のチームがサポートします