チャネルコネクタ設定ファイルを作成する

紹介

設定ファイル(または設定ファイル)は、接続されたチャネル内の各コネクタを定義します。新しいコネクタを追加するか、既存のコネクタに変更を加える際には、コネクタが正しく構成されていることを確認するために、設定ファイルをアップロードする必要があります。

サンプルファイル

これらのサンプル構成ファイルをダウンロードして始めましょう。

ファイルタイプ 説明
ボイラープレートコード このファイルを使用して、コネクタの構築を開始してください。
完全な構成ファイル このファイルには、入力タイプ、リクエスト、およびレスポンスが含まれています。

構成セクション

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

セクション キー 詳細

基本情報

基本情報

名前、説明、種類などの基本的なコネクタの詳細が含まれています。

入力変数

input_variables

コネクタを使用しているときに入力フィールドが表示されます。次のフィールドを設定できます:

  • データ型 : これには、整数 (Int)、文字列、ブール値、JSON、ドロップダウンなどが含まれます。
  • 可視性 : このフィールドは、キャンペーンの作成時やAppマーケットプレイスでの統合時に表示されます。

認証

auth

これは、認証なしと基本認証を含むアプリの認証メカニズムです。

リクエストとレスポンス モジュール

これは、キャンペーン実行中にMoEngageがアプリに行うAPI呼び出しを構築し、MoEngageがAPIレスポンスを解釈する概要を提供します。

ファイル形式

以下は、構成ファイルのファイル形式です:

ファイル形式
{
"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 はい 文字列 これはあなたのコネクタ名です。アプリマーケットプレイスで接続を作成するときに表示されます。
説明 はい 文字列 これは、コネクタによって解決されるユースケースの1行説明です。例えば、このコネクタを使用すると、Telegram Botを介してTelegramユーザーにテキストメッセージを送信できます。
タイプ はい 文字列 これはあなたの接続されたアプリのアプリタイプです。

入力変数

入力変数は、アプリマーケットプレイスで入力フィールドのレンダリングを可能にします。彼らは、MoEngageをあなたのアプリに接続し、それを通じてキャンペーンを効果的に実行するために必要な情報の収集を容易にします。

入力変数を定義するには、 input_variables セクションに次の内容を追加する必要があります。

キー 必要 タイプ 有効な値 説明
可視性スコープ はい 文字列
  • アプリマーケットプレイス
  • キャンペーン

それはあなたの入力変数の場所、または次のいずれかである可能性があります。

  • アプリマーケットプレイス
  • キャンペーン作成(ステップ2)
キー はい 文字列
  • 小文字のアルファベットのみ
  • 空白スペースなし
  • _(アンダースコア)、-(ハイフン)

これは、後続のステップで入力変数の値にアクセスするために使用されます。

event_export_key はい 文字列
  • 小文字のアルファベットのみ
  • 空白スペースなし
  • _ (アンダースコア), - (ハイフン)

MoEngageから他のサードパーティアプリ(データウェアハウスなど)にイベントをエクスポートする際にキーが送信されます。

名前 はい 文字列

英数字 [0-9, a to z, A to Z], および_(アンダースコア),-(ハイフン) とスペース

これはあなたの入力変数のラベルです。

必要 はい 文字列
  • true
  • false

この条件が真の場合、この入力はUI上で必須としてマークされます。

タイプ はい 文字列
  • 文章
  • 番号
  • bool
  • datetime
  • パスワード
  • ドロップダウン
  • ラジオ
  • json
  • コード
  • キー_バリュー

それは、期待される値に基づいてUIに表示する内容を決定します。

バリデーション いいえ オブジェクト

検証については こちら を参照してください。

値を制限したいときに使用してください。フロントエンドのバリデーションを追加するために、正規表現ルールを追加できます。

可視範囲

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

  • アプリマーケットプレイス
  • キャンペーン作成フォーム(ステップ2)

アプリマーケットプレイス

チャンネルアプリへの接続は、以下に示すようにアプリマーケットプレイスから追加されます。

アプリマーケットプレイスでは、認証要件として機能するフィールドやすべてのキャンペーンに共通するフィールドを収集する必要があります。これらのフィールドは、キャンペーン情報から独立している必要があります。

例えば、アプリマーケットプレイスでTelegram Bot IDを収集することが推奨されます。これにより、同じTelegramボットを使用して複数のキャンペーンを実行できます。一方で、アプリマーケットプレイスでTelegramのチャットIDを収集することはお勧めしません。これらはキャンペーンに依存しており、各エンドユーザーごとに変更する必要があります。

情報

情報

MoEngageは、デフォルトでアプリマーケットプレイス内の各コネクタに対して接続名を表示します。これは、接続を区別するための視覚的な識別子を提供します。

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

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

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

情報

情報

すべての入力タイプは、アプリマーケットプレイスとキャンペーン作成フォーム(ステップ2)で利用可能です。

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

文章

この入力タイプでは、ユーザーが任意の基本テキストや文字列の値を入力できます。これはUIに単純な一行のテキストボックスとして表示され、ユーザー名やメールアドレスのような短い自由形式の入力を求めるのに便利です。

テキストを追加するには、次の構造に従ってください:

構造
{
  "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}}]
}

番号

この入力タイプは数字用です。数値のみを受け付けるテキストボックスのように見えます。年齢、ID、数量などの数値を収集する際に使用します。

番号を追加するには、次の構造に従ってください:

構造
{
    "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つの必須の選択肢から選ぶことができます。これは、ユーザーに機能を有効/無効にする、同意/不同意する、または二者択一の選択をさせる場合に使用されます。

ブール値を追加するには、次の構造に従います。

構造
{
"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を追加するには、次の構造を使用してください:

構造
{
    "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"
}

パスワード

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

パスワードを追加するには、次の構造に従ってください:

構造
{
    "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" } ] }

ハッシュマップ

この入力タイプは、キーと値のペア入力に使用されます。キーと値のために2つの相互接続された入力ボックスとして表示されます。設定や構成のようなキーと値のデータが必要な場合に使用してください。
Hashmap.png

ハッシュマップを追加するには、次の構造に従います:

構造
{
  "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"
}

入力検証

テキストやパスワードなどのバリデーションをサポートする入力タイプを定義する際には、UIでユーザーが入力した値を検証するための事前に決められたルールを設定する必要があります。入力変数の中に次のキーを使用して検証を追加できます。

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

ここに、3つの個別ルールを持つフルネームフィールドの例があります。

構造
"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のパーソナライゼーションに似ています。例えば、次の入力変数を考えてみましょう。

  • アプリマーケットプレイスから:
    ユーザー名: String
  • キャンペーン作成フォーム(ステップ2):
    携帯電話番号:文字列

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

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

これらの入力変数は、認証時に使用されたり、APIリクエストのペイロードの一部として含まれたりするユーザーの入力をキャプチャします。

認証

このセクションでは、アプリに必要な認証を定義できます。MoEngageは、リクエストをアプリに送信できるようにし、接続されたチャネルは次の組み込み認証タイプをサポートします。

  • 認証なし
  • ベーシック認証
  • APIキー認証
  • OAuth2
キー 必須 タイプ 説明
auth_type はい 文字列

これは、コネクタに使用したい認証のタイプを表します。有効なオプションは

  • no_auth
  • basic_auth
  • oauth
auth_info はい オブジェクト それは、選択した認証タイプに依存する認証の詳細を表します。
エイリアス はい 文字列 NIL

認証なし

アプリが認証を必要としない場合や、標準的な認証方法のカスタム実装がある場合は、 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トークンの一部として渡すことができます。

Basic認証を追加するには、次の構造を使用します:

構造
"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 ヘッダーに含めます。

例えば、アカウントIDが ABC123 で、アカウントキーが 123XYZ の場合、各リクエストに次のヘッダーを渡す必要があります。

Authorization: Basic QUJDMTIzOjEyM1hZWg==

OAuth2

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

情報

情報

MoEngageは、次のOAuth2認可タイプをサポートしています。

  • 認証コード
  • リフレッシュトークン

特別認証変数

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

名前 JINJA Reference Code 説明
リダイレクトURI
Jinja
{{AppMarketplaceForm["redirect_uri"]}}
リダイレクトURIは、アプリの同意ページからユーザーをリダイレクトするために使用されます。これは、ユーザーのデータセンターに基づいて動的に計算されます。最新の認証済みMoEngage URLについては、以下の表を参照してください。
状態
Jinja
{{AppMarketplaceForm["state"]}}

MoEngageが初期リクエストに追加する不透明で任意の英数字の文字列。アプリはMoEngageにリダイレクトする際にこの文字列を含める必要があります。
認証コード
Jinja
{{AppMarketplaceForm["auth_code"]}}
これは、ユーザーの同意を得た後にアプリが受け取る認証コードです。
アクセストークン
Jinja
{{AppMarketplaceForm["MOE_ACCESS_TOKEN_DEFAULT"]}}

これは、MoEngageがユーザーを認証するために後続の呼び出しで送信するアクセストークンです。
リフレッシュトークン
Jinja
{{AppMarketplaceForm["refresh_token"]}}

これは、アクセストークンの有効期限が切れたときに更新するために使用されるリフレッシュトークンです。

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

リダイレクトURI

リダイレクトURIは、アプリが追加されたデータセンターによって異なります。

データセンター リダイレクト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

すべてのデータセンターにアプリをリストする場合は、各リダイレクトURIを承認する必要があります。

アプリのOAuthを設定する

OAuth2を追加するには、次の構造に従ってください:

JSON
"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の認証モジュールには次のキーが必要です。

キー

必要

タイプ

有効な値

説明

authorization_mapping はい

オブジェクト

詳細については、以下のセクションを参照してオブジェクトマッピングをご確認ください。 MoEngageがユーザーの同意を得るためのアプリの認証リクエストを定義します。
access_token_mapping はい

オブジェクト

詳しくは、以下のオブジェクトマッピングのセクションを参照してください。 MoEngageへの後続の呼び出しで使用する有効なアクセストークンを収集するための、アプリのアクセストークンリクエスト形式を定義します。
refresh_token_mapping はい

オブジェクト

詳細については、以下のセクションを参照してオブジェクトマッピングを確認してください。 MoEngage を使用してアプリのリフレッシュ トークン要求形式を定義し、新しい有効なアクセス トークンを取得します。このアクセス トークンは、以前のアクセス トークンの有効期限が近づいている場合、またはすでに有効期限が切れている場合に、後続の呼び出しで使用されます。
client_id はい

文字列

これはクライアントIDの値です。ここでは入力変数の参照がサポートされています。

あなたのアプリのクライアントID。これが顧客のアプリである場合、App Marketplaceの入力変数を通じてこの値を収集できます。

client_secret はい

文字列

これはクライアントシークレットの値です。ここでは入力変数の参照がサポートされています。 アプリのクライアントシークレット。これが顧客のアプリの場合、App Marketplaceの入力変数を通じてこの値を収集できます。
grant_type はい

文字列の配列

これはアプリがサポートする助成金の種類のリストです:

  • authorization_code
  • refresh_token
あなたのアプリがサポートする認可タイプ。

MoEngageがあなたのアプリケーションから同意とトークンを取得できるようにするために、次のリクエストのパラメータを設定してください。

認可リクエスト

キー 必要 タイプ 有効な値 説明
メソッド はい 文字列
  • 取得
  • POST
通常、これはGETリクエストです .
認証リクエストのHTTPメソッド。
ヘッダー はい オブジェクト { "header_name": "header_value" }

認証リクエストに渡したいカスタムヘッダーのキーと値のペアを含めることができます。ここでは入力変数の参照がサポートされています。

url はい 文字列 有効なURL。JINJAが使用される場合、正しく形成されている必要があります。 ユーザーが同意を提供するためにリダイレクトされる同意URL。ここで入力変数の参照がサポートされています。
url_params はい オブジェクト { "url_param": "param_value" }

  • 認証リクエストにカスタムヘッダーのキーと値のペアを含めることができます。
  • このコンテキストでは、入力変数への参照がサポートされています。
  • カスタムURLパラメータを追加する必要がない場合は、単に空のオブジェクトを使用できます。

ボディタイプ はい 文字列 これはJSONであるべきです。 認証リクエストのボディタイプ。GETリクエストの場合、これをJSONのままにしておいてください。
auth_code_mapping はい 文字列 アイデンティティプロバイダーの応答からのキー。 認証サーバーからのコールバック応答の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”

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

キー 必要 タイプ 有効な値 説明
メソッド はい 文字列
  • GET
  • POST
通常、これはPOSTリクエストです。
アクセストークンリクエストのためのHTTPメソッド。
ヘッダー はい オブジェクト { "header_name": "header_value" }

  • アクセストークンリクエストに渡したいカスタムヘッダーのキーと値のペアを含めることができます。ここでは入力変数参照がサポートされています。
  • カスタムヘッダーを追加する必要がない場合は、これを空のオブジェクトにすることができます。
url はい 文字列
  • 有効なURL。
  • JINJAが使用される場合は、正しく形成されている必要があります。
アクセス トークンを取得するための URL。ここでは入力変数の参照がサポートされています。
url_params はい オブジェクト { "url_param": "param_value" }

  • アクセス トークン リクエストで渡したいカスタム URL パラメーターのキーと値のペアを含めることができます。入力変数の参照はここでサポートされています。
  • カスタムURLパラメータを追加する必要がない場合は、これを空のオブジェクトにすることができます。
体型 はい 文字列 FORM(application/x-www-form-urlencoded)
JSON(application/json)

通常、これはFORMであるべきです。
アクセストークンリクエストのボディタイプ。
本文 はい 文字列

FORMタイプの文字列化されたJSON配列、またはJSONタイプの有効な文字列化されたJSON。

FORMタイプの場合はキーと値のペアの文字列化されたJSON配列、またはJSONタイプの場合は有効な文字列化されたJSON。

フォームタイプの例:


構造
"[{\"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タイプの場合、オブジェクトの配列を渡す必要があります。各オブジェクトには名前と値のキーがあります。

構造
{
  "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 はい オブジェクト 次のキーを含むオブジェクト:
{"access_token_mapping": "<PATH_TO_KEY>"}
{"access_token_expiry_mapping": "<PATH_TO_KEY>"}

APIレスポンス内のキーをアクセストークンとその有効期限にマッピングする方法を定義します。

APIレスポンス内のキーをアクセストークンとその有効期限にマップする方法を定義します。

Example 1:

応答:

構造
{
   "expires_in": 3600,
"token_type": "Bearer",
"refresh_token": "<refresh_token_value_here>",
"access_token": "<access_token_value_here>"
}


マッピング:

構造
{
"code": 200,
"message": "success",
"data": {
"access_token": "<access_token_value_here>",
"advertiser_ids": [],
"scope": "",
"refresh_token": "<refresh_token_value_here>",
"refresh_token_expires_in": 15778800
},
"request_id": ""
}


例2:

応答:

構造
{
"code": 200,
"message": "success",
"data": {
"access_token": "<access_token_value_here>",
"advertiser_ids": [],
"scope": "",
"refresh_token": "<refresh_token_value_here>",
"refresh_token_expires_in": 15778800
},
"request_id": ""
}


マッピング:

構造
"response_mapping": {
"access_token_mapping": "data.access_token",
"access_token_expiry_mapping": null
},
"access_token_expiry_time": 15778800
access_token_expiry_time はい 番号 秒単位の時間。

アクセストークンのデフォルトの有効期限(秒単位)。これは、APIの応答が有効期限を提供しない場合のフォールバックとして使用されます。

もし、 response_mapping section でアクセストークンの有効期限のマッピングを提供している場合、次のように残しておくことができます:


{"access_token_expiry_time": null}

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

キー 必要 タイプ 有効な値 説明
方法 はい 文字列
  • 取得
  • POST
リフレッシュトークンリクエストのHTTPメソッド。
ヘッダー はい Object { "header_name": "header_value" }

  • リフレッシュトークンリクエストに渡したいカスタムヘッダーのキーと値のペアを含めることができます。ここでは入力変数の参照がサポートされています。
  • カスタムヘッダーを追加する必要がない場合は、これを空のオブジェクトにすることができます。
url はい 文字列 有効なURL。JINJAが使用されている場合、それは正しく形成されているべきです。 リフレッシュトークンを取得するためのURL。ここでは入力変数参照がサポートされています。
url_params はい オブジェクト { "url_param": "param_value" }

  • リフレッシュトークンリクエストに渡したいカスタムURLパラメータのキーと値のペアを含めることができます。Input variables' references are supported here.
  • カスタムURLパラメータを追加する必要がない場合は、これを空のオブジェクトにすることができます。
ボディタイプ はい 文字列 FORM(application/x-www-form-urlencoded)
JSON(application/json)

通常、これはFORMであるべきです。
リフレッシュトークンリクエストのボディタイプ。
はい 文字列

FORMタイプの文字列化されたJSON配列またはJSONタイプの有効な文字列化されたJSON。

フォームタイプの例:

JSON
{{AppMarketplaceForm[\"MOE_ACCESS_TOKEN_DEFAULT\"]}}
"[{\"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タイプの場合は、オブジェクトの配列を渡す必要があります。各オブジェクトには、名前キーと値キーがあります。

JSON
{
"grant_type": "refresh_token",
"code": "{{AppMarketplaceForm[\"auth_code\"]}}",
"redirect_uri": "{{AppMarketplaceForm[\"redirect_uri\"]}}",
"client_id": "{{AppMarketplaceForm[\"client_id\"]}}",
"client_secret": "{{AppMarketplaceForm[\"client_secret\"]}}"
}

トークンを更新するリクエストの本文。ここでは入力変数参照がサポートされています。

レスポンス マッピング はい オブジェクト オブジェクトのキー:
{"refresh_token_mapping": "<PATH_TO_KEY>"}
{"refresh_token_expiry_mapping": "<PATH_TO_KEY>"}
APIレスポンスのキーをリフレッシュトークンリクエストとその有効期限にマッピングする方法を定義します。

例1:

レスポンス:

JSON
{
"expires_in": 3600,
"token_type": "Bearer",
"refresh_token": "<refresh_token_value_here>",
"refresh_token_expires_in": 21600
"access_token": "<access_token_value_here>"
}


マッピング:

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": "<access_token_value_here>",
"advertiser_ids": [],
"scope": "",
"refresh_token": "<refresh_token_value_here>",
"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 いいえ 番号 秒単位の時間。
  • リフレッシュトークンのデフォルトの有効期限(秒)。これは、APIレスポンスが有効期限を提供しない場合のフォールバックとして使用されます。
  • リフレッシュトークンの有効期限に対するマッピングを response_mapping セクションに提供している場合は、これを次のようにしておくことができます:

{"refresh_token_expiry_mapping": null}

リクエストとレスポンス

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

警告

警告

MoEngageは、今日の非同期またはコールバックによって駆動される可能性のある統計をサポートしていません。

キャンペーンリクエスト

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

警告

警告
以下はサポートされていません:

  • 頻度キャッピングまたはドンットディスターブ(DND)
  • スロットリング
  • 一括APIリクエスト
  • 複数のAPIリクエスト(連鎖APIリクエスト)

応答を構成するには、これを設定に追加します:

構造
"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>"
}

キー 必須 タイプ 有効なオプション 説明
メソッド はい 文字列
  • GET
  • POST
  • PUT
  • パッチ
  • 削除

このメソッドはリクエストのAPIを定義します。

ヘッダー はい オブジェクト

{ "header_name": "header_value" }

APIリクエストに渡したいカスタムヘッダーのキーと値のペアを含めることができます。ここでは入力変数の参照がサポートされています。

カスタムヘッダーを追加する必要がない場合は、これを空のオブジェクトにすることができます。

url はい 文字列
  • 有効なURL
  • JINJAが使用されている場合、正しく形成されている必要があります

これは、APIリクエストの完全なエンドポイントを指定するために使用されます。

ここでは入力変数の参照がサポートされています。

url_params はい オブジェクト

{ "url_param": "param_value" }

APIリクエストで渡したいカスタムヘッダーのキーと値のペアを含めることができます。

ここでは入力変数の参照がサポートされています。

カスタムURLパラメータを追加する必要がない場合は、これを空のオブジェクトにすることができます。

ボディタイプ はい 文字列

JSON

ペイロード形式。
はい 文字列

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
    }
]

キー 必須 タイプ 有効なオプション 説明
ボディタイプ はい 文字列

JSON

それは応答の形式を指定します。現在、MoEngageはJSONレスポンスのみをサポートしています。

datetime_format はい 文字列

有効な日付時刻形式。

応答に少なくとも1つの日時値が含まれている場合、MoEngageが正確に解析できるように、期待される日時値の形式を提供することをお勧めします。

評価基準 はい オブジェクト

評価基準については、以下のセクションを参照してください。

回答の評価基準は次のとおりです。

  • 条件が満たされた場合、MoEngage は指定されたアクションを実行します。
アクション はい オブジェクト

アクションについては次のセクションを参照してください。

応答条件が満たされたときにアクションを実行する必要があります。 サポートされているアクションのリストを以下に示します。
data_type はい 文字列

ステータスコードの場合: double

ヘッダーの場合: 文字列

ボディ用:

  • ダブル
  • bool
  • datetime
  • 物体

受け入れられる値の完全なリストについては、 ここを 参照してください。

これは、値の予想されるデータ型を定義します。

応答条件

ここでは、AND 演算子と OR 演算子の両方を組み合わせて、各応答に複数の条件を含めることができます。 MoEngage Segmentation の使用経験がある場合は、それを活用できます。

新しい条件を追加するには、次のようになります。

構造
"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_operator はい 文字列
  • and
  • または

フィルターを適用する方法を定義します。 フィルター間の論理関係です。

フィルター はい 配列 Filterオブジェクトの配列

特定の条件は、フィルター オブジェクトの配列を使用して定義されます。

名前 はい 文字列
  • response_code
  • response_headers
  • response_body

応答のどの部分をチェックするかを定義します。

たとえば、値は「response_code」、「response_body」などになります。

data_type はい 文字列

ステータス コードの場合:

  • ダブル

ヘッダーの場合:

ボディ用:

  • ダブル
  • ブール
  • datetime

受け入れられる値の完全なリストについては、 ここを 参照してください。

これは、値の予想されるデータ型を定義します。
オペレーター はい 文字列

受け入れられる値の完全なリストについては、 ここを 参照してください。

比較に使用する演算子を表します
価値 「exists」を除くすべての演算子に必須
  • 文字列
  • 番号
  • ブール

NIL

比較に使用される値です。
値1 演算子「between」に必須
番号
ブール値

NIL

比較に使用される 2 番目の値です。

の場合には、次のように動作します。

値 <= 属性値 <= 値1

否定する オプション ブール
  • true
  • false

このフィールドは、現在のクエリが否定的であるかを識別するために使用されます。 デフォルト値は false です。

たとえば、 email != 'test.moe.com'

この例では、演算子は「is」、否定はtrue、値は「test@moe.com」です。

case_sensitive オプション ブール
  • 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 は イベント作成 アクションをサポートしています。

イベントを作成

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

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

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

  • 接続されたアプリキャンペーンが送信されました
  • 接続されたアプリキャンペーンが失敗しました
キー 必要 タイプ 有効なオプション 説明
タイプ はい 文字列

CREATE_EVENT

実行するアクションの種類を表します。

設定 はい オブジェクト

NIL

実行する必要があるアクションの必要な詳細を表します。

イベント はい オブジェクト

NIL

これは、このアクションをトリガーしたイベントです。

event.name はい 文字列

NIL

イベントの名前です。

event.attributes はい Object-Array

NIL

イベントの一部としての属性のさまざまなキーと値のペアの配列。

event.attributes[].key はい 文字列

NIL

イベント属性の名前です。 これは属性の表示名になります。

event.attributes[].value はい 文字列

NIL

イベント属性の値です。 ここでは入力変数の参照がサポートされています。

MoEngage には、ユーザーの追跡を容易にするために、次のデフォルトの標準イベント属性も含まれています。

属性名 説明
アプリ名

接続されているアプリの名前です。

統合タイプ

チャネル コネクタの名前です。

キャンペーン名 このイベントに関連付けられたキャンペーンの名前を表します。
キャンペーンID このイベントに関連付けられたキャンペーンの ID です。

親キャンペーンID
これは定期キャンペーンの実行時に追跡され、親定期キャンペーンのキャンペーン ID を表します。 この親キャンペーンの子インスタンスは定期的に再実行されます。
バージョンID これは、ジャーニー キャンペーンが属し、キャンペーン実行中に追跡されるバージョン名を表します。
バージョン名 これはキャンペーン ジャーニーの名前を表します。
キャンペーン チャンネル キャンペーン チャネルは常に接続されたアプリです。
読みやすいキャンペーンID 簡単に識別できるように、読み取り可能なキャンペーン ID を提供します。
キャンペーンタイプ それはメッセージが属するキャンペーンの種類を表します。
配送タイプ それは、キャンペーンの配信タイプ(一回限り、定期的など)を表します。
キャンペーンタグ これはキャンペーンに追加されたタグを表しており、すべてのキャンペーン関連イベントで追跡されます。
親フローID

これは親ジャーニー キャンペーンのフロー ID を表し、キャンペーンの実行中に追跡されます。
親フロー名 これは親ジャーニー キャンペーンのフロー名を表し、ジャーニー キャンペーンの実行時に追跡されます。

設定ファイルをアップロードする

構成ファイルの準備ができたら、 こちらを 参照して、アプリ マーケットプレイスの接続済みアプリにアップロードしてください。

この記事は役に立ちましたか?
0人中0人がこの記事が役に立ったと言っています

How can we improve this article?