API de callback

Visión general

Los datos de estado del mensaje se devuelven mediante callback al sistema de negocio de la empresa, y se puede realizar un análisis estadístico basado en la información.

Dirección de callback

La empresa debe configurar la dirección de callback para recibir los cambios del estado del mensaje. Actualmente no existe una interfaz web. Contactar con el personal técnico de Engagelab para configurar la dirección de callback.

Verificación de validez de la dirección de callback

Al configurar la dirección de callback en la gestión de backend de Push, en Configuración de la aplicación, se enviará una solicitud POST con una cadena aleatoria de 8 caracteres como parámetro echostr en el cuerpo de la solicitud. Se debe devolver el valor de echostr en el Response Body, siguiendo el formato indicado a continuación:

Request Body:

              
              {
    "echostr": "12345678"
}

            

Response Body:

              
              12345678

            

Mecanismo de seguridad

Se utiliza para la autenticación del cliente; opcional.

Para garantizar que el origen de los mensajes sea Engagelab, se puede optar por autenticar el origen de los datos POST. Alternativamente, se pueden analizar directamente los datos POST sin autenticación.

El método de autenticación es el siguiente:

• Configurar un nombre de usuario de callback (username) y un secreto de callback (secret) en la consola de Engagelab para la dirección de callback.

Obtener X-CALLBACK-ID del encabezado de la solicitud, como se muestra en el siguiente ejemplo:

              
              X-CALLBACK-ID: timestamp=1681991058;nonce=123123123123;username=test;signature=59682d71e2aa2747252e4e62c15f6f241ddecc8ff08999eda7e0c4451207a16b

            

Aquí:

• timestamp es la marca de tiempo del mensaje de callback (en formato estándar),
• nonce es un número aleatorio,
• signature es la información de firma.

El método de firma es el siguiente:

              
              signature=HMAC-SHA256(secret, timestamp+nonce+username)

            

Mecanismo de respuesta

Después de que el servicio del desarrollador reciba el callback de Engagelab, debe responder en un plazo de 3 segundos conforme a los siguientes requisitos:

• Recepción correcta: el código de estado de la respuesta HTTP debe devolver 200 o 204, y no se requiere ningún mensaje de respuesta.
• Error de recepción: el código de estado de la respuesta HTTP debe devolver 5XX o 4XX y un mensaje de respuesta. El formato es el siguiente:

              
              {
    "code": 2002,
    "message": "error"
}

            

Explicación de campos del callback

Cuerpo del mensaje

Campos del array rows

Campos del objeto status

Valores de estado del mensaje

Contenido del callback

Método de callback: POST
Content-Type: application/json

Ejemplo

Request Header

              
              POST /developer_define_url HTTP/1.1
Content-Type: application/json

            

Request Body

              
              {
    "total": 1,
    "rows": [
        {
            "message_id": "1666165485030094861",
            "from": "",
            "to": "",
            "server": "AppPush",
            "channel": "FCM",
            "custom_args": {},
            "itime": 1640707579,
            "status": {
                "message_status": "delivered",
                "status_data": {
                    "channel_message_id": "wamid.123321abcdefed==",
                    "ntf_msg": 1,
                    "platform": "a",
                    "uid": 100,
                    "app_version": "",
                    "channel": "",
                    "msg_time": 1640707579,
                    "time_zone": "+8",
                    "loss_valid_type": 0,
                    "plan_user_total": 0,
                    "callback_type": 0
                },
                "error_code": 0,
                "error_detail": {
                    "message": ""
                },
                "loss": {
                    "loss_source": "vivo",
                    "loss_step": 1
                }
            }
        }
    ]
}

            

Descripción de parámetros

Fase de pérdida

1. Destinos planificados → Destinos válidos
2. Destinos válidos → Enviados
3. Enviados → Entregados
4. Entregados → Clics