# Custom Channel Access Document

# 1. Introduction

Custom Channel of the TE operation module defines an API, the purpose of which is to connect any message or message-like system to the downstream client.

Clients can quickly support a built-in trigger channel of the non-TE operation module through docking development of relatively lightweight REST API.

Refer to the following figure for the specific call link:

First, the TE operation module will read event data and user data from Thinking Analytics (TA) to calculate the number of target audiences.
According to the target audience and message content, the TE operation module will send a Custom Channel request to one of your own HTTP Custom Channel servers.
After your own Custom Channel server has received the request, you can convert the format, join other business data, enter the asynchronous processing queue and perform other tasks, and finally call any other internal or external message/message-like systems. Examples of systems that may be called:
- Game mail system
- Game announcement system
- Account banning system
- SMS system
- Third-party push system
Recovery of receipt event data
- If data is pushed to the game mail system, then the mail opening event is reported in the mail of the game app, so that TA can get the push receipt event for subsequent analysis of conversion effect.

# 2. Custom Channel server

To dock with Custom Channel of the TE operation module, you need to develop an HTTP Endpoint Server. See below for applicable API definition.

# 2.1 Format definition of input and output parameters

# Custom Channel Request

The input parameters of the server are generated by the TE operation module. The POST method is used, and the Content-Type is set to application/json. request_body is a JSONArray, which supports sending multiple messages in one batch. Each message represents a message with a specific content sent to a user.

WARNING

Note that Custom Channel of the TE operation module contains trigger messages of multiple users in one request body to facilitate downstream batch processing, thereby improving the efficiency of sending messages. The number of users contained in one batch can be customized.

Examples of parameters are as follows:

// request input parameter format
[
    {"push_id":"3e156c91-f039-4d48-9b6f-72b76111af24","custom_params":{"gameuid":"123acb123","name":"Zhang San",...},"params":{"title":"daily activities",...},"#ops_receipt_properties":{"ops_task_id":"0050",...}}
    {"push_id":"5c190470-d81e-4f8e-841a-fe19b95ae47a","custom_params":{"gameuid":"123acb123","name":"Li Si",...},"params":{"title":"daily activities",...},"#ops_receipt_properties":{"ops_task_id":"0050",...}}
]

// specific input parameter format of each message
{
    //id Send id, push id of Custom Channel
    "push_id": "3e156c91-f039-4d48-9b6f-72b76111af24",
    //template parameter, the specific parameter content under this parameter can be defined by 'TE operation module-channel management'
    "params": {
        "title": "daily activities",
        "content": "Hello, Zhang San, come and join the activity!",
        //array row
        "attachment": [{
            {
                "item_id":"xx1",
                "count":"5"
            },
            {
                "item_id":"xx2",
                "count":"10"
            }
        }]
    },
    //custom parameters can specify user properties. The specific parameter content under this parameter can be defined by 'TE operation module-channel management'
     "custom_params": {
         "gameuid":"123acb123",
         "name": "Zhang San"
    },
    //channel receipt property, this parameter is added by default by the TE operation module system for subsequent data statistics, and no analysis is required on the business side. It can be transparently transmitted to the downstream
    "#ops_receipt_properties": {
        "ops_request_id": "f7b66eb7-3363-4a46-a402-601a64b45f76",
        "ops_task_id": "0050",
        "ops_task_instance_id": "31",
        "ops_project_id": 1
    }
}

Parameter name	Parameter type	Required (Yes/No)	Parameter description	Remark
push_id	String	Yes	Push ID	Specific parameter fields can be defined by 'TE operation module-channel management-push ID'
params	Object	No	Template parameters	Some channel parameters need to be filled in by the operator when pushing, such as pushed content. Specific parameter content can be defined by 'TE operation module-channel management-template parameters'.
custom_params	Object	No	Custom parameters	User properties of push target audiences need to be automatically generated by the system. Specific parameter content can be defined by 'TE operation module-channel management-custom parameters'.
#ops_receipt_properties	Object	Yes	Receipt field of TE operation module	The TE operation module system is added by default. If the downstream system needs to observe the message CTR, this field needs to be transparently transmitted and reported directly in the click event. In conversion events, this field does not need to be reported.

> Template parameters, naming convention of custom parameter Key: names are split by underlines, parameters consist of letters, numbers and underlines, and the leading characters can only be underlines or letters > Note: In params and custom_params, for any type of data (such as integer, decimal and date), when sending requests, all fields are converted to strings for processing

# Custom Channel Response

Examples of parameters are as follows:

{
    "return_code": 0,
    "return_message": "success",
    "data": {
        // each element in the fail_list is the failed object information, including the error message and the serial number of the error object, and the serial number of the error object starts from 1. Assumed that 5 objects are sent and the serial number is 1-5, in which 3 succeeded and 2 failed and the 2nd and 4th objects failed, then the following are returned:
        "fail_list": [{
            "index": 2
            "message": "the player token information to be pushed does not exist",
        }, {
            "index": 4
            "message": "push id not found",
        }]
    }
}

Parameter name	Parameter type	Required (Yes/No)	Parameter description
return_code	Integer	Yes	Return code 0 means success (or partial success) 1 means failure
return_message	String	No	Return message
data	Object	No	Return data
data.fail_list	Array	No	If return_code=0, data.fail_list is [] or null, all will be considered successful If data.fail_list is not null, it is a partial failure, and the failure details are defined in the list. Note: The index property of the object in the failure list represents the serial number, starting from 1, not from 0! If no partial failure occurs in the business, just pass [] directly; If return_code=1, no matter what is passed in data.fail_list, it will be considered as a failure.

# 2.2 Request Authentication

If authentication is required in the custom channel, the server side needs to have a signature verification logic in advance. The sender will add the signature to the http header file, and the Key is X-TE-OPS-Signature.

The server needs to perform a HmacSHA1 signature on the key and the Request Body and generate a signature, and then compare it with the signature on the server. If it is found consistent through comparison, the authentication is passed.

The Java implementation of the signature algorithm is as follows:

import org.apache.commons.codec.digest.HmacAlgorithms;
import org.apache.commons.codec.digest.HmacUtils;
/*
   HmacSHA1 signature algorithm
   
   secretKeyYes key configured by the client
   requestBodyYes JSONString of the request content
*/
public static String HmacSHA1(String secretKey,String requestBody) throws Exception {
    String signature = (new HmacUtils(HmacAlgorithms.HMAC_SHA_1,secretKey)).hmacHex(requestBody)
    return signature;
}

# 2.3 Request Concurrency

To ensure the message push speed, the higher the concurrency of the endpoint server, the better. At least 1000TPS is recommended.

# 2.4 Request and Result Integrity Test Example

// request information
curl -X POST "http://localhost:8999/v1/hermes/Custom Channel/test/sample" 
-H "accept: */*" 
-H "X-TE-OPS-Signature: 2e1ee1eeaDA121"
-H "Content-Encoding: gzip" 
-H "Content-Type: application/json" 
-d "[{\"push_id\":\"3e156c91-f039-4d48-9b6f-72b76111af24\",\"costom_params\":{\"name\":\"Zhang San\"},\"params\":{\"title\":\"daily activities\",\"content\":\"Hello, Zhang San, come and join the activity!\"},\"#ops_receipt_properties\":{\"ops_task_id\":\"0050\",\"ops_request_id\":\"f7b66eb7-3363-4a46-a402-601a64b45f76\",\"ops_task_instance_id\":\"31\",\"ops_project_id\":1}}]"

// return result
{
  "data": {
      "fail_list": []
  },
  "return_code": 0,
  "return_message": "success"
}

# 3. Introduction to Configurable Parameters of Custom Channel

Configuration item	Optional value	Default value	Configuration description	Configure on product interface (Yes/No)
Channel authentication	Enabled, disabled	Disabled	To enable channel authentication, you need to provide a key, then the TE operation module will add the signature to the X-TE-OPS-Signature field in the Http header when requesting the Custom Channel service, and provide it for downstream verification.	Yes
Request compression	Enabled, disabled	Enabled	Set whether the http protocol needs to perform content compression.	No
Sending traffic limit	-1，[1,10000]	No traffic limit	Unit: times/second If it is set to -1, this means no traffic limit. It is set to a number from 1-10000. If it is set to 500, this means the downstream Custom Channel server accepts up to 500 requests per second.	No
Size of sending batch	[1,500]	100	It indicates the number of elements contained in the JsonArray of the parameters of one call. A large batch size can improve the efficiency of sending. A small batch size will slow down the sending speed, but the sending accuracy will be improved in extreme exceptions. If the number of users is small and the push accuracy is required, the recommended value is 1 If the number of users is large (>500w) and the push speed is required, the recommended value is 100 and the maximum value is 500.	No
Timeout	-1，[0,3600]	60	Unit: second After the timeout is set, the http request will have a timeout, and the status return value of the http request of the downstream server will be determined. The call is deemed successful only when status=200, otherwise the call is considered failed. If -1 is set, it will not check whether it is timed out. Even if it is timed out, the call is considered successful.	No
Strict verification of return value	Enabled, disabled	Enabled	After enabled, the TE operation module server will verify the format of the response returned by the downstream server. If it does not meet the above Custom Channel response parameter definition specification, it will be considered a failure. Example: Suppose the timeout is set to 5s. If strict verification of the return value is disabled, the Custom Channel server returns normally within 5 seconds, and the return value is HTTP 200 without Body. In this case, the TE operation module considers this call to be successful. If strict verification of the return value is enabled, the Custom Channel server returns normally within 5 seconds, and the return value is HTTP 200 without Body or the Body format is inconsistent with the convention specification. In this case, the TE operation module considers this call to be failed.	No

# 4. Example of Channel Configuration Page

Parameter	Description	Remark
Channel name	Custom Channel name (for display and selection)	Uniqueness verification
Channel URL	Interface address for receiving message push	Support the same URL address with multiple channels
Send ID	ID type of target audience who receives the message, for example, role ID (role_id) of the user used to send mail.	The send ID needs to be reported as a user property. When estimating the number of target audiences, users whose send ID is null will be filtered.
Channel authentication	Custom Channel authentication method	Enable by option. It currently supports Token keys. For details, refer to [request authentication].
Reach funnel settings	Name of meta event associated with funnel steps	Optionally enabled
Content template	Template of specific content sent to the user by this channel. It supports field types such as text, dynamic text, value, and array row. For example, the channel for sending mails can configure the item content (item ID and item quantity) by the array row type, which can be displayed on the front end of the reach task and filled in by the operation staff who configure the operation tasks	Field: parameter name, used in the message body when sending Field name: field displayed when creating a task Field type: text, dynamic text, number, array row, etc. Prompt: prompt in the input box when creating a task (optional) Required: Yes/No (multiple choice, yes by default)
Custom parameters	Optionally added according to channel requirements. This parameter is transparently passed-through.	Not required Field: parameter name, used in the message body when sending Associated field: user properties associated with the field. The field value is this property value when sending the message. Default value: optional, default value is set. When the property value is null, the default value is used; if the default value is not set, a null value is returned when the property value is null

# 5. Acquisition of Click Push Events

Based on the different channels your messages are sent through, you can acquire click events on the client/server side as needed. For the acquisition method, please refer to the method of reporting events in the data integration manual. The event name can be customized, and event data needs to be reported in the #ops_receipt_propertiesfield by your channel and all information needs to be transparently transmitted.

Note: The property field name must be #ops_receipt_properties, and the type can not be changed at will. If the field name is changed, the contents inside the field are modified, or the field is incorrectly reported as a text type, subsequent data usage may be abnormal.

Example codes:

JSONObject properties = new JSONObject();
//get #ops_receipt_properties from the message body sent by Custom Channel, and report it as #ops_receipt_properties
properties.put("#ops_receipt_properties",message.get("#ops_receipt_properties"));
instance.track("ops_push_click",properties);

← Best Practices Android Push Integration Document →