menu
Is this helpful?

# カスタムチャネル接続ドキュメント

# 概要

TEエンゲージモジュールのカスタムチャネルは、ユーザーのメッセージまたはクラスメッセージシステムと接続するためのAPIを定義しています。軽量なREST API統合開発を通じて、TEエンゲージモジュールに組み込まれていないトリガーチャネルを迅速にサポートできます。

具体の呼び出しフローは、以下の図を参照してください。

  1. まず、TEのエンゲージモジュール（Engage）は、アナリティクスモジュール（Analytics）のイベントデータとユーザーデータを読み取り、ターゲットユーザーセグメントを計算します。
  2. ターゲットユーザーに応じて、プッシュメッセージの内容を整えます。TEエンゲージモジュールは、設定したカスタムチャネルサービスにHTTPリクエストをバッチで送信します。
  3. カスタムチャネルサービスは、HTTPの呼び出しを受け取り、リクエスト内容を取得した後、フォーマット変換や他のビジネスデータの結合など、任意の操作を行い、非同期処理キューに入れることができます。そして最終的には内部または外部のメッセージ/クラスメッセージシステムを呼び出すことができます。可能な呼び出されるシステム例：
    1. ゲーム内メール（メッセージ）システム
    2. ゲーム内お知らせシステム
    3. アカウントログイン制限（Ban）システム
    4. SMSシステム
    5. サードパーティプッシュシステム
  4. 処理が完了した後（非同期処理フローを除く）、規定の形式でリクエストの処理結果を返します。処理に失敗したデータがある場合、そのデータの序番と失敗原因を明示的に返す必要があります。TEエンゲージモジュールは、処理に失敗したデータを記録します。
  5. 受信確認イベントデータ回収（任意）
    1. ゲームのメールシステムにプッシュする場合、ユーザーがゲームのメールを開く際にトラッキングデータを発火し、「メールをクリック」をプッシュのクリックとしてトラッキングし、関連する透過パラメータも指定された通りに付けて、より正確な到達段階のファネル分析を実現できます。

# カスタムチャネルサービス

TEエンゲージモジュールとのカスタムチャネル接続のために、HTTP Endpoint Serverを開発する必要があります。以下に示すAPI定義に従う必要があります。

# 2.1 入力出力フォーマット定義

# カスタムチャネルRequest

サービスの入力パラメータは、TEエンゲージモジュールによって構築され、POSTメソッドで送信されます。Content-Typeはapplication/jsonと設定されています。リクエストボディrequest_bodyはJSONArrayであり、複数のメッセージデータを一括して送信することができます。各メッセージデータは、特定の内容を持つ1人のユーザーに対してメッセージを送信することを表します。

DANGER

注意、TEエンゲージモジュールのカスタムチャネルは、1つのリクエストボディに複数のユーザーのトリガーメッセージを含んでいます。これは下流側が一括処理を容易にするためであり、送信効率を向上させるためです。1つのバッチに含まれるユーザー数は、カスタム設定に対応しています。

パラメータ例：

// リクエストの入力形式
[
    {"push_id":"accountid123987001","custom_params":{"gameuid":"123acb001","name":"TA",...},"params":{"title":"デイリーイベント",...},"#ops_receipt_properties":{"ops_task_id":"0050",...}}
    ,{"push_id":"accountid123987002","custom_params":{"gameuid":"123acb002","name":"TE",...},"params":{"title":"デイリーイベント",...},"#ops_receipt_properties":{"ops_task_id":"0050",...}}
]

// 具体の各メッセージの入力パラメータ形式 
{
    //チャネルの送信IDは、通常ユーザーのユニークIDであり、アカウントIDまたはロールIDなどです。運営担当者が「エンゲージ-チャネル管理」で定義します。
    "push_id": "accountid123987001",
    
    //テンプレートパラメータ、このパラメータの具体的な内容は、「エンゲージ-チャネル管理」で定義することができます。
    "params": {
        "title": "デイリーイベント",
        "content": "おはようございます！早く日課を終わらせましょう！",
        //オブジェクトグループ
        "attachment": [
            {
                "item_id":"xx1",
                "count":"5"
            },
            {
                "item_id":"xx2",
                "count":"10"
            }
        ]
    },
    //カスタムパラメーターは、ユーザープロパティを持ち出すことができます。このパラメータの具体的な内容は「エンゲージ-チャネル管理」で定義することができます。
     "custom_params": {
         "zone_id":"17281",
         "name": "TE"
    },
    //チャネル受領プロパティ、このパラメータはエンゲージモジュールによってデフォルトで追加され、後続のデータ分析に使用されます。通常、ビジネス側では解析する必要はありませんので、下流へ透過的に転送してください。下流へ転送する際は、このJSONオブジェクトを直接送信し、toString() を使わないように注意してください。
    "#ops_receipt_properties": {   
        "ops_project_id": 1,  //TEのプロジェクトID
        "ops_task_id": "0050", //エンゲージタスクID
        "ops_task_instance_id": "0050_2023-01-01",  //エンゲージタスクインスタンス
        "ops_task_exec_detail_id": "17795",  //エンゲージタスクインスタンスのプッシュ
        "ops_request_id": "f7b66eb7-3363-4a46-a402-601a64b45f76", //一つのバッチリクエストに対応するため、同じリクエスト内のすべてのops_request_idは同じです。また、リクエストが再試行される場合でも、このIDは変わりません。ゲームシステムがリクエストを冪等性検証する必要がある場合、このフィールドを使用できます。
        "ops_push_language": "default",  //エンゲージタスクのプッシュ言語
        "ops_exp_group_id": "122" //エンゲージタスクのABテストグループID
    }
}
パラメータ タイプ 必須 意味 備考
push_id String Yes プッシュID 具体のパラメータフィールドは、'エンゲージ-チャネル管理-プッシュID'で定義することができます。
params Object No テンプレートパラメータ 運営側が入力する必要のあるいくつかのチャネルパラメータ、例えばプッシュコンテンツについて。 具体のパラメータフィールドは、'エンゲージ-チャネル管理-テンプレート管理'で定義することができます。
custom_params Object No カスタムパラメータ 自動的に抽出されるプッシュの対象ユーザーのプロパティ 具体のパラメータフィールドは、'エンゲージ-チャネル管理-カスタムパラメータ'で定義することができます。
#ops_receipt_properties Object Yes エンゲージモジュールの受領フィールド TEエンゲージモジュールでデフォルト追加 下流システムがメッセージのクリック状況を観測する必要がある場合、このフィールドを直接透過して送信する必要があります。 タスクの目標設定で変換イベントが設定されている場合、このフィールドを送信する必要はありません。
> テンプレートパラメータ、カスタムパラメータのkeyの命名規則：アンダースコアで区切って命名し、パラメータは英数字とアンダースコアで構成されており、先頭文字はアンダースコアと英字のみ可能です。 > 注意：paramsとcustom_paramsのパラメーターでは、すべてのデータタイプ（整数、小数、日付など）について、リクエストを送信する際にすべてのフィールドが文字列に変換されるよう処理されます。

# カスタムチャネルResponse

{
    "return_code": 0,
    "return_message": "success",
    "data": {
        // fail_listの各要素は、失敗したオブジェクトの情報であり、エラーメッセージとエラーオブジェクトの番号が含まれています。エラーオブジェクトの番号は1から始まります。例えば、5つのオブジェクト情報を送信し、番号が1〜5であるとします。成功したものが3つあり、失敗したものが2つあります。そのうち2番目と4番目が失敗した場合は、以下を返します。
        "fail_list": [{
            "index": 2
            "message": "プッシュする必要のあるトークン情報は存在しません。",
        }, {
            "index": 4
            "message": "push id not found",
        }]
    }
}
パラメータ タイプ 必須 説明
return_code Integer Yes 返り値： 0　成功（もしくは部分成功） 1　失敗
return_message String No 返信情報
data Object No 返信データ
data.fail_list Array No return_codeが0の場合、 data.fail_listが[]またはnullである場合、全体が成功と見なされます。 data.fail_listが空ではない場合、一部の失敗とみなされ、失敗の詳細はリストに定義されています。 ビジネス上部分的な失敗の状況が存在しない場合は、単に[]を渡してください。 注意： 1. 一部不可用PushIdの検証は、接続処理ロジックの前段で行うことを推奨します。これにより、fail_listに返却してTEに伝えることで、タスクのトリガー成功指標の統計がより正確になります。 1. 失敗リストのオブジェクトのindexプロパティは、番号で表します。番号は1から始まり、0ではありません！ 1. messageフィールドは必須ではありませんが、返すことを強くお勧めします。これにより、異常時のトラブルシューティングが容易になります。 return_codeが1の場合、data.fail_listに何が渡されているかに関係なく、すべてを失敗とみなします。

# 2.2 リクエスト認証

認証機能はデフォルトでオフになっています。カスタムチャネルの場合、serverが認証を必要としない場合は、このセクションをスキップしてください。

認証をサポートする場合、チャネルの設定時に認証スイッチをオンにする必要があります。送信側は署名をHTTPリクエストヘッダーに追加します。keyはX-TE-OPS-Signatureです。サーバーサイドでは、秘密キーとRequest Bodyを使用してHmacSHA1署名を生成し、signatureと送信側の署名を比較します。一致した場合は認証が通過したことになります。

署名アルゴリズムのJava実装の参考：

import org.apache.commons.codec.digest.HmacAlgorithms;
import org.apache.commons.codec.digest.HmacUtils;
/*
   HmacSHA1署名アルゴリズム
   
   secretKeyは顧客が設定した秘密鍵
   requestBodyはリクエストの内容のJSONString
*/
public static String HmacSHA1(String secretKey,String requestBody) throws Exception {
    String signature = (new HmacUtils(HmacAlgorithms.HMAC_SHA_1,secretKey)).hmacHex(requestBody)
    return signature;
}

署名アルゴリズムのPHP実装の参考：

/**
 * HmacSHA1署名アルゴリズム
 * @param $secretKey : 設定した秘密キー
 * @param $requestBody : リクエスト内容のJSONString
 * @return string サイン値
 */
function HmacSHA1($secretKey, $requestBody) {
    return hash_hmac('sha1', $requestBody, $secretKey);
}

# 2.3 リクエスト並行性能

メッセージの送信速度を確保するために、カスタムチャネルサービスがサポートする並行性は高ければ高いほど良いです。100以上のTPSをサポートできることをお勧めします。同時に、TEエンゲージモジュールは、下流のカスタムチャネルサービスの並行性能力上限に応じて適切な制限設定が可能です。

# 2.4 リクエストと結果のフルテスト例

// リクエスト
curl -X POST "http://localhost:8999/v1/カスタムチャネル/test/sample" 
-H "accept: */*" 
-H "X-TE-OPS-Signature: 2e1ee1eeaDA121"
-H "Content-Type: application/json" 
-d "[{\"push_id\":\"3e156c91-f039-4d48-9b6f-72b76111af24\",\"costom_params\":{\"name\":\"ティッキー\"},\"params\":{\"title\":\"デイリーイベント\",\"content\":\"こんにちはティッキー，早く日課を終わらせましょう！\"},\"#ops_receipt_properties\":{\"ops_task_id\":\"0050\",\"ops_request_id\":\"f7b66eb7-3363-4a46-a402-601a64b45f76\",\"ops_task_instance_id\":\"31\",\"ops_project_id\":1}}]"

// リスポンス
{
  "data": {
      "fail_list": []
  },
  "return_code": 0,
  "return_message": "success"
}

# カスタムチャネルの設定可能のパラメータ

以下のパラメータはデフォルトでバックエンドに設定されています。変更が必要な場合は、弊社スタッフまでお問い合わせください。

構成項目 設定可能値 デフォルト 構成説明
送信制限 -1，[1,10000] 制限なし 単位：回/秒 -1に設定する場合は，制限なし 1-10000の数値を設定する場合，例えば500，1秒あたりに最大500回のリクエストを受け付けることができる下流カスタムチャネルサーバーを表します。
バッチサイズ [1,500] 100 パラメータのJsonArrayに含まれるエレメントの数を示します。 バッチサイズを大きく設定すると、メッセージの送信効率が向上します。 バッチサイズを小さく設定すると、送信速度は遅くなりますが、信頼性が高くなります。 推奨値は100であり、最大値は500です。
タイムアウト時間 [0,600] 60 単位：秒 HTTPリクエストのsocketタイムアウト時間はデフォルトで60秒です。 設定が<=0になっている場合、タイムアウトは発生しません。
失敗の再試行回数 [0,10] 0 重複したビジネスプッシュを避けるために、デフォルトでは0回、つまり再試行しないようにしています。 もし＞0値が設定されている場合、インターフェースのタイムアウトまたはインターフェースのreturn_code!=0が返された場合には、再試行ロジックが実行されます。
再試行間隔時間 [0,600] 5 単位：秒 デフォルトで5sごと一回再試行
返り値の強検証 On / off ON ONすると、TE オペレーション モジュール サービスは、下流サーバーが返す response の形式を検証します。上記のカスタム チャネル response パラメータ定義規格に準拠していない場合、失敗と見なされます。 例：タイムアウト時間は5sに設定 返り値の強検証を有効にしない場合、カスタムチャネルサービスは5秒以内に正常に返され、返り値はHTTP 200であり、Bodyが存在しません。TEエンゲージモジュールでは、この呼び出しは成功と見なされます。 返り値の強検証を有効にする場合、カスタムチャネルサービスは5秒以内に正常に返され、返り値はHTTP 200であり、本体が存在しないか、または本体の形式と規約が一致していない場合、TEエンゲージモジュールでは呼び出し失敗と見なされます。

# チャネル設定ページの例

パラメータ 説明 備考
チャネル名 カスタムチャネルの名前（表示、選択用） 一意性検証
チャネルURL メッセージプッシュ受信インターフェースのURL 同じURLアドレスで複数のチャネルを設定可能
送信ID メッセージの受信対象のユーザーID。例えば、メール送信では、ユーザーのキャラID(role_id) 送信IDはユーザープロパティに格納する必要がある 推定人数を計算する際には送信IDないユーザーを排除される
チャネル検証 カスタムチャネルの認証方法 デフォルトではOFF，必要時にON
リーチファネル設定 チャネル関連の元イベント名 オプションで有効にできる
コンテンツテンプレート チャネルがユーザーに送信する具体的な内容のテンプレートは、テキスト、動的テキスト、数値、オブジェクトグループなどのフィールドタイプをサポートします。たとえば、メール送信チャネルでは、オブジェクトグループタイプを使用してアイテムの内容（アイテムIDとアイテム数）を構成できます。これは、ターゲティングタスクのフロントエンドページに表示され、エンゲージタスクを構成する運営担当者が入力できます。 フィールド：パラメータの名前、メッセージボディで送信されるときに使用します フィールド名：タスク作成時に表示されるフィールド フィールドタイプ：テキスト、ダイナミックテキスト、数値、オブジェクトグループなど ヒント文：タスク作成時の入力欄のヒント（必須ではありません） 必須かどうか：yes/no（単一選択、デフォルトは「yes」）
カスタムパラメータ チャネルの要件に基づいて選択的に追加されます。このパラメータは透過用です。 必須ではありません フィールド：パラメータの名前、メッセージ本文で送信されるときに使用されます 関連フィールド：フィールドに関連するユーザー属性、メッセージ本文を送信する際には、この属性値がデフォルト値として使用されます。オプションですが、既定値が設定されており、属性値が空の場合は既定値が使用されます。既定値が設定されていない場合は、属性値が空の場合は空の値を返します。

# プッシュのクリックイベントの収集

カスタムチャネルからプッシュされたメッセージを使用して、必要に応じてクライアント/サーバー上でクリックイベントを収集できます。収集方法は、TEのデータアクセスガイドの「イベントの送信」を参照してください。イベント名はカスタマイズできます。イベントデータは、カスタムチャネルから送信されたメッセージの#ops_receipt_propertiesフィールドを取得し、オブジェクトプロパティとしてまとめて送信するだけです。その他の分析シナリオがある場合は、このイベントに他のフィールドプロパティを追加することもできます。

注意：プロパティフィールド名は必ず #ops_receipt_properties で、データタイプはオブジェクトです。任意に変更することはできません。フィールド名を変更したり、フィールド内部の内容を変更したり、フィールドをテキストプロパティとして誤って送信したりすると、後続のデータ使用に異常が発生する可能性があります。

コード例：

JSONObject properties = new JSONObject();
//カスタムチャネルから送信されたメッセージの本文から、JSON構造のops_receipt_propertiesオブジェクトを取得し、それをオブジェクトのプロパティとして送信します。
JSONObject opsReceiptProperties = message.get("#ops_receipt_properties")
//プロパティ名は必ずops_receipt_properties，変更不可です。イベント名はカスタムできます
properties.put("#ops_receipt_properties",opsReceiptProperties);
//propertiesオブジェクト内容例： "#ops_receipt_properties":{"ops_task_id":"0062","ops_project_id":2,"ops_task_instance_id":"62","ops_request_id":"967ea854-2c42-490b-9c33-c1792ea637ec"}
instance.track("ops_push_click",properties);

← Android App-push 統合 →