# Custom Channel Access Document
# Introduction
Custom Channel of the TE operation module defines an API whose purpose 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 webhook request to one of your own HTTP webhook servers.
- After your own webhook 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.
# Webhook server
To dock with Webhook of the TE operation module, you need to develop an HTTP Endpoint Server. See below for applicable API definition.
# Format definition of input and output parameters
# Webhook 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.
TIP
Note that Webhook 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 webhook
"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 |
# Webhook 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. |
# Request authentication
If webhook needs to support authentication, the server also needs to implement a signature verification logic. 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;
}
# Request concurrency
To ensure the message push speed, the higher the concurrency of the endpoint server, the better. At least 1000TPS is recommended.
# Request and result integrity test example
// request information
curl -X POST "http://localhost:8999/v1/hermes/webhook/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"
}
# Introduction to configurable parameters of Webhook
| Configuration item | Optional value | Default value | Configuration description | Productized (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 webhook 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 webhook 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 webhook 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 webhook 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 webhook 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 |
# Example of channel configuration page
| Parameter | Description | Remark |
|---|---|---|
| Channel name | Webhook 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 | webhook authentication method | Optionally enabled. 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 transmitted | 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 body 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 |
# Acquisition of click push events
Based on messages pushed through webhook, you can acquire click events on the client/server 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 acquired from the #ops_receipt_properties field in the message sent by webhook and all transparently transmitted.
Example codes:
JSONObject properties = new JSONObject();
//get #ops_receipt_properties from the message body sent by webhook, and report it as #ops_receipt_properties
properties.put("#ops_receipt_properties",message.get("#ops_receipt_properties"));
instance.track("ops_push_click",properties);