はじめに

Config (または Config ファイル) は、Connected Channel の各コネクタを定義します。新しいコネクタを追加する場合や既存のコネクタを変更する場合は、コネクタが正しく構成されるように Config ファイルをアップロードする必要があります。

サンプルファイル

以下のサンプル Config ファイルをダウンロードして使い始めることができます。

ファイルの種類	説明
Boilerplate Code	コネクタの構築を始める際にこのファイルを使用します。
Full Config File	このファイルには、入力タイプ、リクエスト、レスポンスが含まれています。

Config のセクション

Config ファイルは次のセクションに分かれています。

セクション	キー	詳細
基本情報	`basic_info`	名前、説明、タイプなどのコネクタの基本的な詳細が含まれます。
入力変数	`input_variables`	コネクタの使用時に入力フィールドを表示します。次のフィールドを設定できます。データ型: Integer (Int)、String、Boolean、JSON、Dropdown などが含まれます。可視性: このフィールドは、キャンペーンの作成時または App marketplace での統合時に表示されます。
認証	`auth`	認証なしおよびベーシック認証を含む、アプリの認証メカニズムです。
リクエストとレスポンス	`modules`	キャンペーンの実行中に MoEngage がアプリに対して行う API 呼び出しを構築し、MoEngage による API レスポンスの解釈の概要を提供します。

ファイル形式

Config ファイルのファイル形式は次のとおりです。 kkk

{
"basic_info": {
"name": "",
"description": "",
"type": "CHANNEL"
},
"input_variables": [{
"visibility_scope": "",
"key": "",
"event_export_key": "",
"name": "",
"required": "",
"type": "",
"encrypt": "",
"validations": [""]
}],
"auth": {
"auth_type": "",
"auth_info": "",
"alias": ""
},
"modules": [{
"name": "default",
"type": "REQUEST_RESPONSE",
"params": {
"request": {
"method": "",
"headers": {"": ""},
"url": "",
"url_params": {"": ""},
"body_type": "",
"body": ""
},
"response": [{
"body_type": "",
"datetime_format": "",
"evaluation_criteria": {},
"actions": []
}]
}
}]
}

基本情報

このセクションでは、コネクタの名前と、コネクタが解決するユースケースを定義する必要があります。

キー	必須	タイプ	説明
`name`	はい	String	コネクタ名です。App marketplace で接続を作成するときに表示されます。
`description`	はい	String	コネクタが解決するユースケースの 1 行の説明です。例: このコネクタを使用すると、Telegram Bot を介して Telegram ユーザーにテキストメッセージを送信できます。
`type`	はい	String	Connected Apps のアプリタイプです。

入力変数

入力変数を使用すると、App marketplace に入力フィールドをレンダリングできます。入力変数は、MoEngage をアプリに正常に接続し、アプリを通じてキャンペーンを効果的に実行するために必要な情報の収集を容易にします。入力変数を定義するには、input_variables セクションに次の内容を追加する必要があります。

キー	必須	タイプ	有効な値	説明
`visibility_scope`	はい	String	`app_marketplace` `campaign`	入力変数の場所で、次のいずれかになります。 App marketplace キャンペーン作成 (ステップ 2)
`key`	はい	String	英小文字のみ空白なし _ (アンダースコア)、-(ハイフン)	後続のステップで入力変数の値にアクセスするために使用されます。
`event_export_key`	はい	String	英小文字のみ空白なし _ (アンダースコア)、- (ハイフン)	MoEngage からデータウェアハウスなどの他のサードパーティアプリにイベントをエクスポートする際に送信されるキーです。
`name`	はい	String	英数字 [0-9、a から z、A から Z]、および _(アンダースコア)、-(ハイフン)、スペースのみ	入力変数のラベルです。
`required`	はい	String	`true` `false`	条件が true の場合、この入力は UI で必須としてマークされます。
`type`	はい	String	`text` `number` `bool` `datetime` `password` `dropdown` `radio` `json` `code` `key_value`	想定される値に基づいて、UI に表示する内容を決定します。
`validations`	いいえ	Object	検証についてはこちらを参照してください。	値を制限したい場合に使用します。正規表現ルールを追加して、フロントエンドの検証を追加できます。

上記の必須キーに加えて、UI とデータ処理を強化するために、すべての入力タイプで次のオプションのキーがサポートされています。

キー	必須	タイプ	有効な値	説明
`header`	いいえ	String	任意の文字列	UI の入力フィールドの上に表示されるセクション見出しです。キーと値のペアのセットなど、関連するフィールドをグループ化するために使用します。
`help_text`	いいえ	String	任意の文字列	見出しの下に表示される短い説明で、ユーザーが入力すべき内容をガイドします。
`is_hidden`	いいえ	Boolean	`true` / `false`	`true` の場合、フィールドは UI から非表示になりますが、その値 (`default_value` を含む) は引き続きリクエストに渡されます。デフォルトは `false` です。
`default_value`	いいえ	Object / Array	タイプによって異なる	フィールドが最初に読み込まれたときにレンダリングされる事前入力値です。`key_value` タイプの場合、これはキーと値のオブジェクトの配列です。

可視性スコープ

入力変数は次の場所で収集されます。

App Marketplace
キャンペーン作成フォーム (ステップ 2)

App MarketPlace

チャネルアプリへの接続は、以下に示すように App marketplace から追加されます。

App marketplace では、認証要件として機能するフィールド、またはすべてのキャンペーンに共通するフィールドを収集する必要があります。これらのフィールドは、キャンペーン情報から独立している必要があります。たとえば、Telegram Bot ID は App marketplace で収集することをお勧めします。これにより、同じ Telegram Bot を使用して複数のキャンペーンを実行できます。一方、Telegram Chat ID はキャンペーンに依存し、エンドユーザーごとに変更する必要があるため、App marketplace で収集することはお勧めしません。

MoEngage は、デフォルトで App marketplace の各コネクタの接続名を表示します。これにより、接続を区別するための視覚的な識別子が提供されます。

キャンペーン作成フォーム (ステップ 2)

チャネルアプリへの接続は、以下に示すようにキャンペーン作成から追加されます。

サポートされている入力タイプ

すべての入力タイプは、App marketplace とキャンペーン作成フォーム (ステップ 2) で使用できます。

MoEngage は現在、次の入力タイプをサポートしています。

Text

この入力タイプでは、ユーザーは基本的なテキストまたは文字列値を入力できます。UI にはシンプルな 1 行のテキストボックスとして表示され、ユーザー名やメールアドレスなどの短い自由テキスト入力を求める場合に便利です。

Text を追加するには、次の構造に従います。

{
  "visibility_scope": "{{campaign or app_marketplace}}",
  "key": "{{key used in code}}",
  "event_export_key": "{{key used for events}}",
  "name": "display label",
  "required": {{true or false}},
  "type": "text",
  "validations": [{{array of validation rules if any}}]
}

Rich-Text (HTML)

Rich-Text は個別の入力タイプではありません。メッセージコンテンツで使用されるフィールドの Text 入力タイプで利用できる書式設定モードです。HTML サポートはワークスペースレベルの機能であり、Config ファイルで切り替えることはできません。ワークスペースでこの機能を有効にするには、サポートにお問い合わせください。有効にすると、メッセージコンテンツで使用される Text フィールドで標準の HTML タグを使用できます。<script> は許可されていませんが、それ以外のすべての HTML タグがサポートされています。 Rich-Text を使用するには、Text の構造に従います。

{
  "visibility_scope": "campaign",
  "key": "{{key used in code}}",
  "event_export_key": "{{key used for events}}",
  "name": "Message Text",
  "required": true,
  "type": "text"
}

ネストされたタグがサポートされています。たとえば、<b><i>Text</i></b> は太字の斜体テキストとしてレンダリングされます。

サポートされていないタグは、リクエストが送信される前に値から自動的に削除され、入力時に UI でユーザーに警告通知が表示されます。

次の HTML 要素は禁止されており、ステップ 2 の検証中にブロックされます。

<script>
<iframe>
<style>
<object>
<applet>
<meta> — http-equiv="refresh" による不正なリフレッシュリダイレクトのリスクがあります。
<base> — 相対リンクパスを操作される脆弱性があります。
ネストされた <script> ブロックを含む <svg> 要素。
すべてのインラインイベントハンドラー (onclick、onerror、onload、onmouseover など)。<img> や <a> など、一般的に許可されている要素に付加されている場合も含みます。
<a href="javascript:..."> 内に実装された javascript: プロトコルリンク。

このリストに含まれていないタグは、キャンペーン作成の第 2 フェーズで UI 検証を通過します。ただし、このステータスは、フォームレベルのサニタイザーがそれらを明示的にブロックしないことを確認するだけです。ダウンストリームのクライアントアプリケーション (Telegram など) がそれらをどのように解釈、エスケープ、または表示するかについては保証されず、動的属性 (onclick や onerror など) がペイロードの送信前に削除されることも保証されません。本番環境のキャンペーンでこれらのタグを使用する前に、必ずターゲットチャネルでエンドツーエンドのレンダリング動作を検証してください。

Connected App でのユーザー入力の例:

<b>Your order is ready!</b> Use code <code>SAVE10</code> for 10% off

Number

この入力タイプは数値用です。テキストボックスとして表示されますが、数値の入力のみを受け付けます。年齢、ID、数量などの数値を収集する場合に使用します。

Number を追加するには、次の構造に従います。

{
    "visibility_scope": "<campaign or app_marketplace>",
    "key": "<key used in code>",
    "event_export_key": "<key used for events>",
    "name": "<display label>",
    "required": <true or false>,
    "type": "number",
    "validations": [<array of validation rules if any>]
}

必要に応じて、検証を使用して数値入力の下限と上限を制限できます。

Boolean

この入力タイプはラジオボタンとして表示され、ユーザーは True または False の 2 つの選択肢から必ず 1 つを選択します。機能の有効化/無効化、同意/不同意など、二者択一をユーザーに求める場合に使用します。

Boolean を追加するには、次の構造に従います。

{    "visibility_scope": "<campaign or app_marketplace>",
    "key": "<key used in code>",
    "event_export_key": "<key used for events>",
    "name": "<display label>",
    "required": <true or false>,
    "type": "bool"
}

DateTime

この入力タイプは日付と時刻用です。DateTime ピッカーとして表示され、ユーザーは特定の日付と時刻を選択できます。投稿やリマインダーのスケジュール設定など、特定の日付や時刻に関するデータを収集する場合に使用します。

DateTime を追加するには、次の構造に従います。

{
    "visibility_scope": "<campaign or app_marketplace>",
    "key": "<key used in code>",
    "event_export_key": "<key used for events>",
    "name": "<display label>",
    "required": <true or false>,
    "type": "datetime"
}

Password

この入力タイプはパスワード入力用です。テキストボックスとして表示されますが、プライバシー保護のためにユーザーの入力をマスクします。ログインアドレスなど、ユーザーに機密情報を要求する場合に使用する必要があります。

Password を追加するには、次の構造に従います。

{
    "visibility_scope": "<campaign or app_marketplace>",
    "key": "<key used in code>",
    "event_export_key": "<key used for events>",
    "name": "<display label>",
    "required": <true or false>,
    "type": "password",
    "validations": [<array of validation rules if any>]
}

ドロップダウンリスト (単一選択および複数選択)

この入力タイプでは、複数選択モードでユーザーが複数のオプションを選択できます。あらかじめ決められたオプションのセットがあり、自由テキストの入力を許可せずに入力を制限したい場合に推奨されます。

ドロップダウンリストを追加するには、次の構造に従います。

{
    "visibility_scope": "<campaign or app_marketplace>",
    "key": "<key used in code>",
    "event_export_key": "<key used for events>",
    "name": "<display label>",
    "required": <true or false>,
    "type": "dropdown",    "allow_multiple": <true or false>, // If true, multiple options can be selected
    "options": [
        {
            "label": "Option 1", // This value will be shown on the UI
            "key": "key_1" // This will be the selected value passed
        },
        {
            "label": "Option 2",
            "key": "key_2"
        },
        {
            "label": "Option 3",
            "key": "key_3"
        }
    ]
}

Hash Maps

この入力タイプは、キーと値のペアの入力に使用されます。動的な UI セクションとしてレンダリングされ、ユーザーはキーと値のペアの行を追加、編集、削除できます。ボタンラベルや URL、カスタムメタデータなど、可変のユーザー定義データが必要な場合に使用します。 Config ファイルに "type": "key_value" の入力変数が複数含まれている場合、それぞれが独自の見出し、ヘルプテキスト、行のセットを持つ独立した UI セクションとしてレンダリングされます。

Hash Map を追加するには、次の構造に従います。

{
  "visibility_scope": "{{campaign or app_marketplace}}",
  "key": "{{key used in code}}",
  "event_export_key": "{{key used for events}}",
  "name": "display label",
  "required": {{true or false}},
  "type": "key_value",
  "is_hidden": {{true or false}},
  "header": "Section heading shown above the field",
  "help_text": "Short instructions shown below the header",
  "default_value": [
    {
      "key": "default_key_1",
      "value": "default_value_1"
    }
  ]
}

UI の動作

動作	詳細
デフォルトの状態	デフォルトでは、空のキーと値の行が 1 つレンダリングされます。`default_value` が指定されている場合は、代わりにそれに応じて行が事前入力されます。
行の追加	Add コントロールにより、セクションに新しい空のキーと値の行が追加されます。
行の削除	各行には、その行を削除するための削除 (ゴミ箱) アイコンがあります。
パーソナライゼーション	キーと値の入力はどちらも、キャンペーン作成の他のテキストフィールドと同様に `@` パーソナライゼーションをサポートしています。
必須	`required: true` の場合、キャンペーンを保存する前に、少なくとも 1 つの行に空でないキーと空でない値の両方が必要です。
非表示	`is_hidden: true` の場合、フィールドは UI にレンダリングされませんが、その値 (デフォルト値またはその他の値) は引き続きリクエストペイロードに含まれます。

シナリオの例

同じ Config ファイル内の 2 つの key_value 入力変数:

[
  {
    "visibility_scope": "app_marketplace",
    "key": "source_config.inlinebuttons",
    "event_export_key": "source_config.inlinebuttons",
    "name": "Inline Keyboard Buttons",
    "required": true,
    "type": "key_value",
    "is_hidden": false,
    "header": "Call to Action Buttons",
    "help_text": "Add buttons. Key = Button Text, Value = URL."
  },
  {
    "visibility_scope": "app_marketplace",
    "key": "source_config.metadata",
    "event_export_key": "source_config.metadata",
    "name": "Optional Metadata",
    "required": false,
    "is_hidden": true,
    "type": "key_value",
    "header": "Additional Data",
    "help_text": ""
  }
]

これは、Call to Action Buttons (表示、必須) と Additional Data (非表示、オプションですが、設定されたデフォルト値とともに送信されます) の 2 つの個別のセクションとしてレンダリングされます。

出力形式

フォームが送信されると、MoEngage は key_value フィールドの値を行オブジェクトの配列として渡します。

[
  {
    "key": "reply_markup",
    "value": "yes",
    "disableKey": false,
    "disableValue": false,
    "deletable": true,
    "uniqueKey": "1e2006d1-bb13-44b1-bfa1-11d3ca896901"
  },
  {
    "key": "protect_content",
    "value": "true",
    "disableKey": false,
    "disableValue": false,
    "deletable": true,
    "uniqueKey": "62cc6db5-e49d-4b16-91fd-4e79b6d61ea4"
  }
]

キー	タイプ	説明
`key`	String	この行にユーザーが入力したキーです。
`value`	String	この行にユーザーが入力した値で、パーソナライゼーションタグを含む場合があります。
`disableKey`	Boolean	`true` の場合、この行のキー入力は読み取り専用としてレンダリングされます。ユーザーに名前を変更させたくない事前入力済みの行に使用されます。
`disableValue`	Boolean	`true` の場合、この行の値入力は読み取り専用としてレンダリングされます。
`deletable`	Boolean	`false` の場合、この行の削除アイコンは非表示になり、削除できなくなります。
`uniqueKey`	String	行ごとに生成される UUID で、編集間で行を追跡するために内部的に使用されます。ユーザーは編集できません。

リクエストボディで key_value フィールドを参照するには、他の入力変数と同様に JINJA を使用しますが、値は単一の文字列ではなく配列に解決されることに注意してください。通常、ボディを構築する際にはこの配列を反復処理します。

入力の検証

Text や Password など、検証をサポートする入力タイプを定義する場合は、UI でユーザーが入力した値を検証するためのルールをあらかじめ設定する必要があります。入力変数内に次のキーを使用して検証を追加できます。

"validations": [
    {
        "text": "Rule description",
        "regex": "<regex expression>"
    }
]

以下は、3 つの個別のルールを持つ Full Name フィールドの例です。

"validations": [
    {
        "text": "Start the name with an alphabet",
        "regex": "^[A-Za-z]"
    },
    {
        "text": "Use only numbers, spaces, \"_\" or \"-\" with alphabets",
        "regex": "^[a-zA-Z0-9-_ ]*$"
    },
    {
        "text": "Use 3-25 characters",
        "regex": "^[a-zA-Z0-9 -_]{3,25}$"
    }
]

これらの各ルールは、有効な入力に導くために UI でユーザーに表示されます。

入力変数の参照

ユーザーから入力変数の値を収集した後、次のセクションでそれらを使用できます。

認証
リクエストとレスポンス

入力変数を参照するには、JINJA コードを使用できます。この参照メカニズムは、MoEngage のパーソナライゼーションに似ています。たとえば、次の入力変数について考えてみます。

App marketplace から:
Username: String
キャンペーン作成フォーム (ステップ 2) から:
Mobile Number: String

これらの変数を参照するには、次の JINJA コードを使用します。

{{AppMarketplaceForm["username"]}}
{{CampaignCreationForm["mobile_number"]}}

これらの入力変数はユーザーの入力を取得し、認証時に使用したり、API リクエストペイロードの一部として含めたりできます。

認証

このセクションでは、アプリに必要な認証を定義できます。MoEngage はアプリへのリクエストの送信を可能にし、Connected Channels は次の組み込み認証タイプをサポートしています。

No Auth
Basic Auth
API Key Auth
OAuth2

キー	必須	タイプ	説明
`auth_type`	はい	String	コネクタに使用する認証のタイプを表します。有効なオプションは次のとおりです。 `no_auth` `basic_auth` `oauth`
`auth_info`	はい	Object	選択した認証のタイプに応じた認証の詳細を表します。
`alias`	はい	String	NIL

No Auth

アプリで認証が不要な場合、または標準の認証方法をカスタム実装している場合は、No Auth を選択できます。No Auth を選択すると、MoEngage はリクエストに対して事前認証操作を実行しません。 “No Auth” を使用する場合は、アプリタイプとして No Auth を選択します。必要に応じて、API にカスタム URL パラメータまたはヘッダーを含めることができます。

"auth": {
    "auth_type": "no_auth",
    "auth_info": {},
    "alias": "valid_alias"
}

このアプリタイプでは追加情報は不要なため、auth_info キーには空のオブジェクトを渡す必要があります。

Basic Auth

アプリが Basic Auth をサポートしている場合は、App marketplace でユーザー名とパスワードを収集し、各リクエストの Basic Auth トークンの一部として渡すことができます。 Basic Auth を追加するには、次の構造に従います。

"auth": {
    "auth_type": "basic_auth",
    "auth_info": {
        "username": "{{AppMarketplaceForm[\"account_id\"]}}",
        "password": "{{AppMarketplaceForm[\"account_key\"]}}"
    },
    "alias": "valid_alias"
}

上記の例では、App Marketplace フォームでユーザーが入力した値を参照しています。MoEngage は Base64 でエンコードされた Basic Auth トークンを生成し、各リクエストの Authorization ヘッダーに含めます。たとえば、Account ID が ABC123 で Account Key が 123XYZ の場合、各リクエストで次のヘッダーを渡す必要があります。 Authorization: Basic QUJDMTIzOjEyM1hZWg==

OAuth2

アプリが認可に OAuth2 フレームワークを使用している場合、ユーザーの同意の取得やアクセストークンとリフレッシュトークンの管理を含むフロー全体を MoEngage が処理するように構成できます。

MoEngage は次の OAuth2 グラントタイプをサポートしています。

Authorization Code
Refresh Token

特別な認証変数

MoEngage は、アプリ内で OAuth2 メカニズムをサポートするために参照できるいくつかの特別な変数を公開しています。

名前	JINJA 参照コード	説明
Redirect URI	`{{AppMarketplaceForm[\"redirect_uri\"]}}`	Redirect URI は、アプリの同意ページからユーザーをリダイレクトするために使用されます。これはユーザーのデータセンターに基づいて動的に算出されます。最新の承認済み MoEngage URL については、以下の表を参照してください。
State	`{{AppMarketplaceForm[\"state\"]}}`	MoEngage が最初のリクエストに追加する、不透明で任意の英数字の文字列です。アプリは MoEngage にリダイレクトする際にこの文字列を含める必要があります。
Authorization Code	`{{AppMarketplaceForm[\"auth_code\"]}}`	ユーザーの同意を取得した後にアプリが受け取る認可コードです。
Access Token	`{{AppMarketplaceForm[\"MOE_ACCESS_TOKEN_DEFAULT\"]}}`	ユーザーを認可するために、MoEngage が後続の呼び出しで送信するアクセストークンです。
Refresh Token	`{{AppMarketplaceForm[\"refresh_token\"]}}`	アクセストークンの有効期限が切れたときに更新するために使用されるリフレッシュトークンです。

OAuth2 の呼び出しとコネクタリクエストを設定する際に、上記の変数を参照できます。

Redirect URI

Redirect URI は、アプリが追加されているデータセンターによって異なります。

データセンター	Redirect URI
DC-01	https://dashboard-01.moengage.com/v3/partner/oauth/callback
DC-02	https://dashboard-02.moengage.com/v3/partner/oauth/callback
DC-03	https://dashboard-03.moengage.com/v3/partner/oauth/callback
DC-04	https://dashboard-04.moengage.com/v3/partner/oauth/callback

すべてのデータセンターでアプリを公開する場合は、各 Redirect URI を承認する必要があります。

アプリの OAuth を設定する

OAuth2 を追加するには、次の構造に従います。

"auth": {
    "auth_type": "oauth",
    "auth_info": {
        "authorization_mapping": {
            "method": "GET",
            "headers": {
        	   "": ""
},
            "url": "",
            "url_params": {
                "response_type": "code",
                "client_id": "{{AppMarketplaceForm[\"client_id\"]}}",
                "redirect_uri": "{{AppMarketplaceForm[\"redirect_uri\"]}}",
                "state": "{{AppMarketplaceForm[\"state\"]}}",
                "scope": ""
            },
            "body_type": "JSON",
            "auth_code_mapping": "code"
        },
        "access_token_mapping": {
            "method": "POST",
            "headers": {
                "Content-Type": "application/x-www-form-urlencoded",
        	   "": ""
            },
            "url": "",
            "url_params": {
          "": ""
             },
            "body_type": "FORM",
            "body": "[{\"name\":\"grant_type\",\"value\":\"authorization_code\"},{\"name\":\"code\",\"value\":\"{{AppMarketplaceForm[\"auth_code\"]}}\"}, {\"name\":\"redirect_uri\",\"value\":\"{{AppMarketplaceForm[\"redirect_uri\"]}}\"}, {\"name\":\"client_id\",\"value\":\"{{AppMarketplaceForm[\"client_id\"]}}\"}, {\"name\":\"client_secret\",\"value\":\"{{AppMarketplaceForm[\"client_secret\"]}}\"}]",
            "response_mapping": {
                "access_token_mapping": "access_token",
                "access_token_expiry_mapping": "expires_in"
            },
            "access_token_expiry_time": 3600 // time in seconds
        },
        "refresh_token_mapping": {
            "method": "POST",
            "headers": {
                "Content-type": "application/x-www-form-urlencoded"
            },
            "url": "",
            "url_params": {},
            "body_type": "FORM",
            "body": "[{\"name\":\"grant_type\",\"value\":\"refresh_token\"},{\"name\":\"refresh_token\",\"value\":\"{{AppMarketplaceForm[\"refresh_token\"]}}\"}, {\"name\":\"client_id\",\"value\":\"{{AppMarketplaceForm[\"client_id\"]}}\"}, {\"name\":\"client_secret\",\"value\":\"{{AppMarketplaceForm[\"client_secret\"]}}\"}]",
            "response_mapping": {
                "refresh_token_mapping": "refresh_token",
                "refresh_token_expiry_mapping": null
            },
            "refresh_token_expiry_time": 36000 // time in seconds
        },
        "client_id": "{{AppMarketplaceForm[\"client_id\"]}}",
        "client_secret": "{{AppMarketplaceForm[\"client_secret\"]}}",
        "grant_type": [
            "refresh_token",
            "authorization_code"
        ]
    }
}

OAuth2 の auth モジュールには、次のキーが必要です。

キー	必須	タイプ	有効な値	説明
`authorization_mapping`	はい	Object	詳細については、以下のセクションのオブジェクトマッピングを参照してください。	MoEngage がユーザーの同意を取得するための、アプリの認可リクエストを定義します。
`access_token_mapping`	はい	Object	詳細については、以下のセクションのオブジェクトマッピングを参照してください。	MoEngage への後続の呼び出しで使用される有効なアクセストークンを取得するための、アプリのアクセストークンリクエスト形式を定義します。
`refresh_token_mapping`	はい	Object	詳細については、以下のセクションのオブジェクトマッピングを参照してください。	新しい有効なアクセストークンを取得するための、MoEngage とアプリ間のリフレッシュトークンリクエスト形式を定義します。新しいアクセストークンは、以前のアクセストークンの有効期限が近づいているか、すでに切れている場合に、後続の呼び出しで使用されます。
`client_id`	はい	String	Client ID の値です。ここでは入力変数の参照がサポートされています。	アプリの Client ID です。これが顧客のアプリである場合は、App Marketplace の入力変数を通じてこの値を収集できます。
`client_secret`	はい	String	Client Secret の値です。ここでは入力変数の参照がサポートされています。	アプリの Client Secret です。これが顧客のアプリである場合は、App Marketplace の入力変数を通じてこの値を収集できます。
`grant_type`	はい	Array of Strings	アプリでサポートされているグラントタイプのリストです。 `authorization_code` `refresh_token`	アプリでサポートされているグラントタイプです。

MoEngage がアプリケーションから同意とトークンを取得できるようにするには、次のリクエストのパラメータを構成します。

認可リクエスト

キー	必須	タイプ	有効な値	説明
method	はい	String	GET POST 通常、これは GET リクエストです。	認可リクエストの HTTP メソッドです。
headers	はい	Object	`{ "header_name": "header_value" }`	認可リクエストで渡すカスタムヘッダーのキーと値のペアを含めることができます。ここでは入力変数の参照がサポートされています。
url	はい	String	有効な URL。JINJA を使用する場合は、正しい形式である必要があります。	ユーザーが同意を提供するためにリダイレクトされる同意 URL です。ここでは入力変数の参照がサポートされています。
url_params	はい	Object	`{ "url_param": "param_value" }`	認可リクエストにカスタムヘッダーのキーと値のペアを含めることができます。ここでは入力変数の参照がサポートされています。追加するカスタム URL パラメータがない場合は、空のオブジェクトを使用できます。
body_type	はい	String	JSON である必要があります。	認可リクエストのボディタイプです。GET リクエストの場合は、JSON のままにします。
auth_code_mapping	はい	String	ID プロバイダーのレスポンスのキー。	認可サーバーからのコールバックレスポンスの URL パラメータ内で、認可コードを含むキーです。例 1: URL: `https://example-app.com/cb?code=AUTH_CODE_HERE&state=1234zyx` ”auth_code_mapping”: “code” 例 2: URL: `https://example-app.com/cb?my_custom_auth_code=AUTH_CODE_HERE&state=1234zyx` ”auth_code_mapping”: “my_custom_auth_code”

アクセストークンリクエスト

キー	必須	タイプ	有効な値	説明
method	はい	String	GET POST 通常、これは POST リクエストです。	アクセストークンリクエストの HTTP メソッドです。
headers	はい	Object	`{ "header_name": "header_value" }`	アクセストークンリクエストで渡すカスタムヘッダーのキーと値のペアを含めることができます。ここでは入力変数の参照がサポートされています。追加するカスタムヘッダーがない場合は、空のオブジェクトにできます。
url	はい	String	有効な URL。 JINJA を使用する場合は、正しい形式である必要があります。	アクセストークンを取得するための URL です。ここでは入力変数の参照がサポートされています。
url_params	はい	Object	`{ "url_param": "param_value" }`	アクセストークンリクエストで渡すカスタム URL パラメータのキーと値のペアを含めることができます。ここでは入力変数の参照がサポートされています。追加するカスタム URL パラメータがない場合は、空のオブジェクトにできます。
body_type	はい	String	FORM (application/x-www-form-urlencoded) JSON (application/json) 通常、これは FORM である必要があります。	アクセストークンリクエストのボディタイプです。
body	はい	String	FORM タイプの場合は文字列化された JSON 配列、JSON タイプの場合は有効な文字列化された JSON。 FORM タイプの場合はキーと値のペアの文字列化された JSON 配列、JSON タイプの場合は有効な文字列化された JSON。 FORM タイプの例: Structure `"[{\"name\":\"grant_type\",\"value\":\"authorization_code\"},{\"name\":\"code\",\"value\":\"{{AppMarketplaceForm[\"auth_code\"]}}\"}, {\"name\":\"redirect_uri\",\"value\":\"{{AppMarketplaceForm[\"redirect_uri\"]}}\"}, {\"name\":\"client_id\",\"value\":\"{{AppMarketplaceForm[\"client_id\"]}}\"}, {\"name\":\"client_secret\",\"value\":\"{{AppMarketplaceForm[\"client_secret\"]}}\"}]"` FORM タイプの場合は、オブジェクトの配列を渡す必要があります。各オブジェクトには name キーと value キーがあります。 JSON タイプの例: Structure `{ "grant_type": "authorization_code", "code": "{{AppMarketplaceForm[\"auth_code\"]}}", "redirect_uri": "{{AppMarketplaceForm[\"redirect_uri\"]}}", "client_id": "{{AppMarketplaceForm[\"client_id\"]}}", "client_secret": "{{AppMarketplaceForm[\"client_secret\"]}}" }`	アクセストークンを取得するリクエストのボディです。ここでは入力変数の参照がサポートされています。
response_mapping	はい	Object	次のキーを含むオブジェクト: `{"access_token_mapping": ""}{"access_token_expiry_mapping": ""}`	API レスポンス内のキーをアクセストークンとその有効期限にマッピングする方法を定義します。 API レスポンス内のキーをアクセストークンとその有効期限にマッピングする方法を定義します。例 1: レスポンス: Structure `{ "expires_in": 3600, "token_type": "Bearer", "refresh_token": "", "access_token": "" }` マッピング: Structure `{ "code": 200, "message": "success", "data": { "access_token": "", "advertiser_ids": [], "scope": "", "refresh_token": "", "refresh_token_expires_in": 15778800 }, "request_id": "" }` 例 2: レスポンス: Structure `{ "code": 200, "message": "success", "data": { "access_token": "", "advertiser_ids": [], "scope": "", "refresh_token": "", "refresh_token_expires_in": 15778800 }, "request_id": "" }` マッピング: Structure `"response_mapping": { "access_token_mapping": "data.access_token", "access_token_expiry_mapping": null }, "access_token_expiry_time": 15778800`
access_token_expiry_time	はい	Number	秒単位の時間。	アクセストークンのデフォルトの有効期限 (秒単位) です。API レスポンスで有効期限が提供されない場合のフォールバックとして使用されます。 `response_mapping section` でアクセストークンの有効期限のマッピングを指定している場合は、次のようにしておくことができます。 `{"access_token_expiry_time": null}`

リフレッシュトークンリクエスト

キー	必須	タイプ	有効な値	説明
method	はい	String	GET POST 通常、これは POST リクエストです。	リフレッシュトークンリクエストの HTTP メソッドです。
headers	はい	Object	`{ "header_name": "header_value" }`	リフレッシュトークンリクエストで渡すカスタムヘッダーのキーと値のペアを含めることができます。ここでは入力変数の参照がサポートされています。追加するカスタムヘッダーがない場合は、空のオブジェクトにできます。
url	はい	String	有効な URL。JINJA を使用する場合は、正しい形式である必要があります。	リフレッシュトークンを取得するための URL です。ここでは入力変数の参照がサポートされています。
url_params	はい	Object	`{ "url_param": "param_value" }`	リフレッシュトークンリクエストで渡すカスタム URL パラメータのキーと値のペアを含めることができます。ここでは入力変数の参照がサポートされています。追加するカスタム URL パラメータがない場合は、空のオブジェクトにできます。
body_type	はい	String	FORM (application/x-www-form-urlencoded) JSON (application/json) 通常、これは FORM である必要があります。	リフレッシュトークンリクエストのボディタイプです。
body	はい	String	FORM タイプの場合は文字列化された JSON 配列、JSON タイプの場合は有効な文字列化された JSON。 FORM タイプの例: JSON `{{AppMarketplaceForm[\"MOE_ACCESS_TOKEN_DEFAULT\"]}}` JSON `"[{\"name\":\"grant_type\",\"value\":\"refresh_token\"},{\"name\":\"code\",\"value\":\"{{AppMarketplaceForm[\"auth_code\"]}}\"}, {\"name\":\"redirect_uri\",\"value\":\"{{AppMarketplaceForm[\"redirect_uri\"]}}\"}, {\"name\":\"client_id\",\"value\":\"{{AppMarketplaceForm[\"client_id\"]}}\"}, {\"name\":\"client_secret\",\"value\":\"{{AppMarketplaceForm[\"client_secret\"]}}\"}]"` FORM タイプの場合は、オブジェクトの配列を渡す必要があります。各オブジェクトには name キーと value キーがあります。 JSON タイプの例: JSON `{ "grant_type": "refresh_token", "code": "{{AppMarketplaceForm[\"auth_code\"]}}", "redirect_uri": "{{AppMarketplaceForm[\"redirect_uri\"]}}", "client_id": "{{AppMarketplaceForm[\"client_id\"]}}", "client_secret": "{{AppMarketplaceForm[\"client_secret\"]}}" }`	トークンを更新するリクエストのボディです。ここでは入力変数の参照がサポートされています。
response_mapping	はい	Object	次のキーを持つオブジェクト: `{"refresh_token_mapping": ""}{"refresh_token_expiry_mapping": ""}`	API レスポンス内のキーをリフレッシュトークンリクエストとその有効期限にマッピングする方法を定義します。例 1: レスポンス: JSON `{ "expires_in": 3600, "token_type": "Bearer", "refresh_token": "", "refresh_token_expires_in": 21600 "access_token": "" }` マッピング: JSON `"response_mapping": { "refresh_token_mapping": "refresh_token", "refresh_token_expiry_mapping": "refresh_token_expires_in" }` 例 2: レスポンス: JSON `{ "code": 200, "message": "success", "data": { "access_token": "", "advertiser_ids": [], "scope": "", "refresh_token": "", "refresh_token_expires_in": 15778800 }, "request_id": "" }` マッピング: JSON `"response_mapping": { "refresh_token_mapping": "data.refresh_token", "refresh_token_expiry_mapping": "data.refresh_token_expires_in" }, "refresh_token_expiry_time": null`
refresh_token_expiry_time	いいえ	Number	秒単位の時間。	リフレッシュトークンのデフォルトの有効期限 (秒単位) です。API レスポンスで有効期限が提供されない場合のフォールバックとして使用されます。 `response_mapping` セクションでリフレッシュトークンの有効期限のマッピングを指定している場合は、次のようにしておくことができます。 `{"refresh_token_expiry_mapping": null}`

リクエストとレスポンス

このセクションでは、送信される各キャンペーンに対して MoEngage が開始する API リクエストを設定する必要があります。MoEngage からリクエストが行われた後、API リクエストのレスポンスに基づいてキャンペーン統計を計算する方法を設定できます。

現在、MoEngage は非同期またはコールバック駆動の統計をサポートしていません。

キャンペーンリクエスト

MoEngage は、キャンペーンが送信されるたびにアプリへの API リクエストの送信を試みます。
たとえば、キャンペーンが 50 人のユーザーを対象としている場合、MoEngage はそのキャンペーンに対して 50 件の API リクエストを行います。

フリークエンシーキャッピングまたはサイレント時間 (DND)
スロットリング
一括 API リクエスト
複数の API リクエスト (チェーン API リクエスト)

レスポンスを構成するには、Config に次の内容を追加します。

"modules": [
  {
      "name": "default",
      "type": "REQUEST_RESPONSE",
      "params": {
          "request": {},
          "response": []
      }
  }
]

リクエスト形式

リクエスト形式は、リクエストのペイロードについて MoEngage に通知します。

"request": {
    "method": "<HTTP method: GET, POST etc>",
    "headers": {
        "<header_name>": "<header_value>"
    },
    "url": "<API endpoint url>",
    "url_params": {
        "<url_param_name>": "<url_param_value>"
    },
    "body_type": "<body type: JSON, form data etc>",
    "body": "<body content>"
}

キー	必須	タイプ	有効なオプション	説明
`method`	はい	String	`GET` `POST` `PUT` `PATCH` `DELETE`	リクエストの API のメソッドを定義します。
`headers`	はい	Object	`{ "header_name": "header_value" }`	API リクエストで渡すカスタムヘッダーのキーと値のペアを含めることができます。ここでは入力変数の参照がサポートされています。追加するカスタムヘッダーがない場合は、空のオブジェクトにできます。
`url`	はい	String	有効な URL JINJA を使用する場合は、正しい形式である必要があります	API リクエストの完全なエンドポイントを指定するために使用されます。ここでは入力変数の参照がサポートされています。
`url_params`	はい	Object	`{ "url_param": "param_value" }`	API リクエストで渡すカスタムヘッダーのキーと値のペアを含めることができます。ここでは入力変数の参照がサポートされています。追加するカスタム URL パラメータがない場合は、空のオブジェクトにできます。
`body_type`	はい	String	`JSON`	ペイロードの形式です。
`body`	はい	String	NIL	API リクエストのペイロードです。ここでは入力変数の参照がサポートされています。

レスポンスの処理

API リクエストを行った後、レスポンスの解釈方法を MoEngage に通知できます。また、成功や失敗などのすべてのレスポンスをカバーするように、リクエストに複数のレスポンスを追加することもできます。レスポンスは 2 つの部分で構成されます。

レスポンス条件: API によって提供されたレスポンスに基づいて、ステータスコード、ヘッダー値、さらにはボディペイロードに条件を追加できます。これらの条件が満たされると、MoEngage でアクションを実行できます。
レスポンスアクション: アクションは、MoEngage によって実行される操作です。

ユースケース

レスポンス処理にはいくつかのユースケースがあります。さまざまなユースケースで使用されるトラッキングのタイプは次のとおりです。

統計のトラッキング: キャンペーンの正確な成功および失敗の統計を表示します。
イベントのトラッキング: 特定の条件が満たされたときに発生するトリガーイベントです。ユーザー向けの他のジャーニーを作成するのに役立ちます。

レスポンスを追加する

レスポンスを追加するには、次の構造に従います。

"response": [
    {
        "body_type": "<body type: JSON, STRING etc>",
        "datetime_format": "<datetime format if required>",
        "evaluation_criteria": {...} , // Specify your evaluation criteria for success or failure
        "actions": [...] // Actions to be taken based on evaluation
    }
]

キー	必須	タイプ	有効なオプション	説明
`body_type`	はい	String	`JSON`	レスポンスの形式を指定します。現在、MoEngage は JSON レスポンスのみをサポートしています。
`datetime_format`	はい	String	有効な日時形式。	レスポンスが少なくとも 1 つの日時値を返す場合は、MoEngage が正確に解析できるように、想定される日時値の形式を指定することをお勧めします。
`evaluation_criteria`	はい	Object	評価基準については、以下のセクションを参照してください。	レスポンスの評価基準は次のとおりです。条件が満たされた場合、MoEngage は指定されたアクションを実行します。
`actions`	はい	Object	アクションについては、以下のセクションを参照してください。	レスポンス条件が満たされたときに実行する必要があるアクションです。サポートされているアクションのリストは以下に記載されています。
`data_type`	はい	String	ステータスコードの場合: double ヘッダーの場合: string ボディの場合: double string bool datetime object 使用可能な値の完全なリストについては、こちらを参照してください。	値の想定されるデータ型を定義します。

レスポンス条件

ここでは、各レスポンスに複数の条件を含め、AND 演算子と OR 演算子の両方を組み合わせることができます。MoEngage のセグメンテーションを使用した経験がある場合は、それを活用できます。新しい条件を追加するには、次のようにします。

"evaluation_criteria": {
    "filters": [
        {
            "name": "response_code" or "response_body" or "response_headers",
            "data_type": "<data_type>",
            "operator": "<operator>",
            "value": "<value>",
            "negate": true/false,
            "case_sensitive": true/false
        }
    ],
    "filter_operator": "<operator>"
}

各条件は、MoEngage では Filter と呼ばれます。次の条件は、セグメンテーションフィルターと同様に機能します。

キー	必須	タイプ	有効なオプション	説明
`filter_operator`	はい	String	and or	フィルターの適用方法を定義します。フィルター間の論理的な関係です。
`filters`	はい	Array	Filter オブジェクトの配列	具体的な条件は、フィルターオブジェクトの配列を使用して定義されます。
`name`	はい	String	response_code response_headers response_body	レスポンスのどの部分をチェックするかを定義します。たとえば、値は “response_code”、“response_body” などになります。
`data_type`	はい	String	ステータスコードの場合: double ヘッダーの場合: string ボディの場合: double string bool datetime 使用可能な値の完全なリストについては、こちらを参照してください。	値の想定されるデータ型を定義します。
`operator`	はい	String	使用可能な値の完全なリストについては、こちらを参照してください。	比較に使用する演算子を表します
`value`	’exists’ を除くすべての演算子で必須	String Number Boolean	NIL	比較に使用する値です。
`value1`	演算子 ‘between’ で必須	String Number Boolean	NIL	比較に使用する 2 番目の値です。 between の場合、次のように機能します。 value <= attribute_value <= value1
`negate`	オプション	Boolean	true false	現在のクエリが否定であるかどうかを識別するために使用されるフィールドです。デフォルト値は false です。例: email != ‘test.moe.com’ この例では、演算子は ‘is’、negate=true、value=‘[email protected]’ です。
`case_sensitive`	オプション	Boolean	true false	文字列で大文字と小文字を区別するかどうかを示すフィールドです。大文字と小文字を区別する条件を追加するには、case_sensitive=true を選択します。デフォルト値は false です。

以下は、API のレスポンスステータスコードが 200 であり、ペイロードで {"ok": true} が返されるかどうかをチェックする評価基準の例です。

"evaluation_criteria": {
  "filters": [
      {
          "name": "response_code",
          "data_type": "double",
          "operator": "is",
          "value": 200,
          "negate": false,
          "case_sensitive": false
      },
      {
          "name": "response_body",
          "data_type": "object",
          "filter_operator": "and",
          "filters": [
              {
                  "name": "ok",
                  "data_type": "bool",
                  "operator": "is",
                  "value": true,
                  "negate": false,
                  "case_sensitive": false
              }
          ]
      }
  ],
  "filter_operator": "and"
}

アプリ向けにカスタマイズされた条件を作成できます。これらの条件の正確さは、MoEngage がイベントをトリガーし、統計を効果的に表示する能力に直接影響します。

レスポンスアクション

ここでは、上記の条件に基づいて MoEngage にアクションを実行させることができます。現在、MoEngage は Create Event アクションをサポートしています。

Create Event

これは、メッセージの送信、ユーザーの同期などのユースケースをトラッキングします。このアクションを使用すると、MoEngage でイベントをトリガーできます。以下は、レスポンスにイベントを追加するための構造です。

"actions": [
    {
        "type": "CREATE_EVENT",
        "config": {
            "event": {
                "name": "Connected App Campaign Failed"
            },
            "attributes": [
                {
                    "key": "Attribute Name",
                    "value": "Attribute Value"
                }
            ]
        }
    }
]

キャンペーン統計、特に送信イベントと失敗イベントを正確に計算するには、次の 2 つのイベントをアクションの一部として追加する必要があります。

Connected App Campaign Sent
Connected App Campaign Failed

キー	必須	タイプ	有効なオプション	説明
`type`	はい	String	CREATE_EVENT	実行するアクションのタイプを表します。
`config`	はい	Object	NIL	実行する必要があるアクションの必要な詳細を表します。
`event`	はい	Object	NIL	このアクションをトリガーしたイベントです。
`event.name`	はい	String	NIL	イベントの名前です。
`event.attributes`	はい	Object-Array	NIL	イベントの一部としての、属性のさまざまなキーと値のペアの配列です。
`event.attributes[].key`	はい	String	NIL	イベント属性の名前です。属性の表示名を使用できます。
`event.attributes[].value`	はい	String	NIL	イベント属性の値です。ここでは入力変数の参照がサポートされています。

MoEngage には、ユーザーのトラッキングを改善するために、次のデフォルトの標準イベント属性も含まれています。

属性名	説明
App name	Connected App の名前です。
Integration type	チャネルコネクタの名前です。
Campaign name	このイベントに関連付けられたキャンペーンの名前を表します。
Campaign Id	このイベントに関連付けられたキャンペーンの ID です。
Parent Campaign ID	定期キャンペーンの実行時にトラッキングされ、親の定期キャンペーンのキャンペーン ID を表します。この親キャンペーンの子インスタンスは、定期的に再実行されます。
Version Id	ジャーニーキャンペーンが属するバージョン名を表し、キャンペーンの実行中にトラッキングされます。
Version Name	キャンペーンジャーニーの名前を表します。
Campaign Channel	キャンペーンチャネルは常に Connected Apps です。
Readable Campaign Id	識別しやすい、読み取り可能なキャンペーン ID を提供します。
Campaign Type	メッセージが属するキャンペーンのタイプを表します。
Delivery Type	キャンペーンの配信タイプ (1 回限り、定期など) を表します。
Campaign Tags	キャンペーンに追加されたタグを表し、キャンペーン関連のすべてのイベントでトラッキングされます。
Parent Flow Id	親ジャーニーキャンペーンのフロー ID を表し、キャンペーンの実行中にトラッキングされます。
Parent Flow Name	親ジャーニーキャンペーンのフロー名を表し、ジャーニーキャンペーンの実行時にトラッキングされます。

Config ファイルのアップロード

Config ファイルの準備ができたら、こちらを参照して、App marketplace の Connected App にアップロードしてください。

​はじめに

​サンプルファイル

​Config のセクション

​ファイル形式

​基本情報

​入力変数

​可視性スコープ

​App MarketPlace

​キャンペーン作成フォーム (ステップ 2)

​サポートされている入力タイプ

​Text

​Rich-Text (HTML)

​Number

​Boolean

​DateTime

​Password

​ドロップダウンリスト (単一選択および複数選択)

​Hash Maps

​UI の動作

​シナリオの例

​出力形式

​入力の検証

​入力変数の参照

​認証

​No Auth

​Basic Auth

​OAuth2

​特別な認証変数

​Redirect URI

​アプリの OAuth を設定する

​認可リクエスト

​アクセストークンリクエスト

​リフレッシュトークンリクエスト

​リクエストとレスポンス

​キャンペーンリクエスト

​リクエスト形式

​レスポンスの処理

​ユースケース

​レスポンスを追加する

​レスポンス条件

​レスポンスアクション

​Create Event

​Config ファイルのアップロード

はじめに

サンプルファイル

Config のセクション

ファイル形式

基本情報

入力変数

可視性スコープ

App MarketPlace

キャンペーン作成フォーム (ステップ 2)

サポートされている入力タイプ

Text

Rich-Text (HTML)

Number

Boolean

DateTime

Password

ドロップダウンリスト (単一選択および複数選択)

Hash Maps

UI の動作

シナリオの例

出力形式

入力の検証

入力変数の参照

認証

No Auth

Basic Auth

OAuth2

特別な認証変数

Redirect URI

アプリの OAuth を設定する

認可リクエスト

アクセストークンリクエスト

リフレッシュトークンリクエスト

リクエストとレスポンス

キャンペーンリクエスト

リクエスト形式

レスポンスの処理

ユースケース

レスポンスを追加する

レスポンス条件

レスポンスアクション

Create Event

Config ファイルのアップロード