Skip to main content
このリファレンスでは、キャンペーンがどのようにユーザーに届くかを定義するリクエストボディのコンポーネントについて説明します: trigger_condition、segmentation_details、scheduling_details、delivery_controls、conversion_goal_details、control_group_details、utm_params、campaign_audience_limit、advanced、basic_details.geofences。これらは Create Campaign および Update Campaign で使用されます。 basic_details(geofences を除く)と、チャネル、プラットフォーム、テンプレートタイプごとの campaign_content については、キャンペーンコンテンツのリファレンス を参照してください。
フィールドの型、列挙値、必須マーカーについては、/api/campaigns/campaign-draft.yaml にある OpenAPI 仕様が正式な情報源です。このページでは、インラインのスキーマ説明では表現できない、実行可能なバリエーションと条件付きルールを補足します。

クイックスタート

最小限のオーディエンス設定は、segmentation_details.is_all_user_campaign: true または segmentation_details.included_filters 配下の単一のフィルターのいずれかです。最小限のスケジュールは scheduling_details.delivery_type: ASAP です。イベントトリガー型キャンペーンでは、trigger_condition も必要です。
以下は、サポートされているすべての配信タイプ、フィルタープリミティブ、配信制御フラグを網羅したリファレンス資料です。

ページの内容

トリガー条件

trigger_condition オブジェクトは、トリガー型キャンペーンがいつ発火するかを定義します。以下の配信タイプでは 必須 です。
  • Push の EVENT_TRIGGERED、DEVICE_TRIGGERED、LOCATION_TRIGGERED。
  • Email の EVENT_TRIGGERED。
BUSINESS_EVENT_TRIGGERED キャンペーンは、basic_details.business_event によってトリガーを識別し、trigger_condition は使用しません。
INTELLIGENT_DELAY は Push のみ でサポートされています。Email の trigger_delay_type では DELAY または ASAP を指定できます。

トリガー遅延のバリエーション

トリガー条件が満たされるとすぐにキャンペーンが発火します。

Intelligent delay の最適化(Push)

intelligent_delay_optimization オブジェクトは、MoEngage が最適な送信時刻を選択する時間枠を定義します。

プライマリおよびセカンダリのトリガーフィルター

secondary_included_filters は、同様に一致する必要がある追加のフィルターグループを追加します。「ユーザーが X を行い、かつ Y でもある」という形式のトリガーに便利です。

配信タイプごとのトリガー要件

フィルタープリミティブ

フィルターは、segmentation_details の included_filters.filters[] と excluded_filters.filters[]、および trigger_condition の included_filters.filters[] と secondary_included_filters.filters[] の中で使用されるプリミティブです。すべてのフィルターグループは次の形式を持ちます。
filter_operator は and または or(小文字)です。フィルターは filter_type によって区別されるオブジェクトです。

データ型ごとの演算子

キャンペーンのオーディエンス

segmentation_details オブジェクトは、キャンペーンを受信するユーザーを定義します。明示的なフィルターグループと、すべてのユーザーをターゲットにするフラグの 2 つのトップレベルモードがサポートされています。

キャンペーンの配信スケジュール

scheduling_details.delivery_type フィールドで送信モデルを選択します。値に応じて、必要なフィールドが異なります。 PERIODIC キャンペーンでは、delivery_type は AT_FIXED_TIME で、periodic_details が必須です。

スケジュールのバリエーション

定期スケジュール

periodic_details オブジェクトは、PERIODIC キャンペーンでは 必須 です。 repeat_on_days_of_week_for_month の各エントリは、次の形式を持ちます。

Best Time to Send

bts_details オブジェクトは、delivery_type が SEND_IN_BTS の場合は 必須 です。

ユーザーのタイムゾーン

user_timezone_details オブジェクトは、delivery_type が SEND_IN_USER_TIMEZONE の場合は 必須 です。

配信制御

delivery_controls オブジェクトには、スロットリング、フリークエンシーキャップ、DND の動作、オフライン/キューイングのフラグが含まれます。使用できるフィールドは Push と Email で異なります。

Push の配信制御

Email の配信制御

コンバージョン目標のトラッキング

conversion_goal_details オブジェクトは、キャンペーンの成果をアトリビューションするために MoEngage がトラッキングするイベントを設定します。

目標のフィールド

目標イベント属性のフィールド

コントロールグループ

control_group_details オブジェクトは、キャンペーンレベルおよびグローバルのコントロールグループ(送信対象から除外されるユーザー)を設定します。

UTM パラメータ

utm_params オブジェクトは、キャンペーンコンテンツ内の URL に UTM トラッキングパラメータを付加します。5 つの標準キーが明示的に定義されています。utm_ で始まる 最大 5 つの追加カスタムキー もサポートされています。
カスタムキーの上限は合計 5 つです。utm_ で始まらないカスタムキーは拒否されます。

キャンペーンのオーディエンス上限

campaign_audience_limit オブジェクトは、キャンペーンが到達できるユーザー数に上限を設定します。
フラグによって制御される機能です。 どのワークスペースでもデフォルトでは有効になっていません。フラグが有効になっていないワークスペースで campaign_audience_limit を含めると、error.code: VALIDATION_FAILED および error.message: "Campaign Audience Limit feature is not enabled for this db" とともに 400 が返されます。有効にするには MoEngage のアカウントチームにお問い合わせください。
サポートされているチャネル: Email、Push。BROADCAST_LIVE_ACTIVITY ではサポートされていません。
Push と Email の両方のすべての配信タイプに適用されます。

Push の詳細設定

advanced オブジェクト(Push のみ)には、通知の有効期限の設定とプラットフォームごとの優先度が含まれます。
advanced は Push のリクエストボディの一部です。Email のリクエストボディには含まれません。

有効期限の設定

プラットフォームレベルの優先度

ジオフェンスのターゲティング

basic_details.geofences オブジェクトは、Push の LOCATION_TRIGGERED キャンペーンでは 必須 です。このフィールドは構造上 basic_details の中にありますが、ロケーショントリガー型のターゲティングにおいて trigger_condition および delivery_controls.send_limit_* と連携して機能するため、ここで説明しています。
ユーザーがジオフェンスに入ったときにキャンペーンが発火します。

検証ルール

以下のルールは、このページの複数のサブオブジェクトにまたがって適用されます。

既存のキャンペーンの更新

PATCH /v5/campaigns/{campaign_id} は、このページのすべてのスキーマを再利用します。更新には追加のルールが適用されます。
  • ネストされたオブジェクト内のフィールドを更新する場合、リクエストには 親オブジェクト全体 を含める必要があります。たとえば、segmentation_details.included_filters.filters 内の 1 つのフィルターを変更する場合は、segmentation_details ブロック全体を含めます。
  • ACTIVE 状態のキャンペーンでは、以下のフィールドを編集できません。
    • trigger_condition
    • segmentation_details
    • conversion_goal_details
    • スケジュールの タイプ(delivery_type)
    • スケジュールの 開始日(scheduling_details.start_time)
  • SCHEDULED 状態のキャンペーンでは、スケジュールのタイプを除くすべてのフィールドを編集できます。
  • STOPPED または ARCHIVED 状態のキャンペーンは更新できません。
  • イベントトリガー型キャンペーンで trigger_condition または campaign_content を更新した場合、コンテンツのキャッシュにより、ユーザーに反映されるまで最大 30 分 かかることがあります。
  • 定期キャンペーンでは、設定の変更は次回のスケジュール実行から適用されます。
  • 1 回限りのキャンペーンでは、変更は更新時点でまだ送信されていないメッセージに適用されます。

関連情報