API de push

Envío de notificaciones o mensajes a un dispositivo único o a una lista de dispositivos. El contenido enviado solo puede ser un objeto de solicitud en formato JSON.

Límites de frecuencia de las solicitudes

Nuestra API impone límites a la frecuencia de llamadas para garantizar la estabilidad y la equidad del servicio. Los límites de QPS (consultas por segundo) para cada AppKey son los siguientes:

• Límite estándar: máximo de 500 solicitudes por segundo.
• Límite avanzado: si está suscrito a nuestro plan de pago y su AppKey de pago requiere un límite de QPS más alto, se recomienda ponerse en contacto con nuestro equipo comercial: sales@engagelab.com.

Método de solicitud

POST

Dirección de llamada

La dirección del servicio de la interfaz corresponde uno a uno con el punto de acceso del centro de datos seleccionado. Se debe seleccionar la dirección de llamada correspondiente al punto de acceso del servicio de la aplicación.

En la actualidad, EngageLab ha desplegado y admite dos puntos de acceso de centros de datos, y los datos entre diferentes puntos de acceso de servicio están completamente aislados. Se puede seleccionar la dirección de invocación según el punto de acceso del centro de datos elegido al crear el producto.

              
              POST /v4/push

            

Validación de la llamada

Para obtener más información, se recomienda consultar la descripción de la visión general de la API REST de Método de autenticación (Authentication Method)。

Ejemplo de solicitud

Encabezado de la solicitud

              
              > POST /v4/push HTTP/1.1
> Authorization: Basic Yzk2ZjQyZTBkMmU2NjJlNDVkMDM1YWIxOmRmNGQ1OWU4NGVhYzJmOWQ1M2IzNmYxMg==

            

Cuerpo de la solicitud

              
              {
    "from": "push",
    "to": "all",
    "body": {
        "platform": "all",
        "notification": {
            "alert": "Hello, Push!",
            "android": {
                "alert": "Hi, Push!",
                "title": "Send to Android",
                "builder_id": 1,
                "extras": {
                    "newsid": 321
                }
            },
            "ios": {
                "alert": "Hi, MTPush!",
                "sound": "default",
                "badge": "+1",
                "extras": {
                    "newsid": 321
                }
            }
        },
        "options": {
            "time_to_live": 60,
            "apns_production": false
        }
    },
    "request_id": "12345678",
    "custom_args": {
        "EngageLab": "push to you"
    }
}

            

Parámetros de solicitud

La estructura de parámetros del push se detalla en la siguiente tabla:

from

Remitente del servicio actual, tipo String, campo opcional.

Ejemplo de solicitud

              
              {
    "from": "push"
}

            

to

Objeto de dispositivo push (Push Device Object), que indica la lista de dispositivos a los que se puede realizar un push. Para confirmar el objeto de dispositivo push, AppPush proporciona diversos métodos, como: alias, tag, registration_id, subgrupo, difusión (broadcast), etc.

Destino de push

Existen varias formas de seleccionar dispositivos además de la difusión, como se indica a continuación:

Ejemplo

• Push a todos (difusión):

              
              {
  "to": "all"
}

            

• Push a múltiples etiquetas (siempre que se cumpla cualquiera de las etiquetas): en Shenzhen, Guangzhou o Beijing

              
              {
  "to": {
    "tag": [
      "Shenzhen",
      "Guangzhou",
      "Beijing"
    ]
  }
}

            

• Push a múltiples etiquetas (debe estar dentro del alcance de varias etiquetas al mismo tiempo): en Shenzhen y "female"

              
              {
  "to": {
    "tag_and": [
      "Shenzhen",
      "female"
    ]
  }
}

            

• Push a múltiples alias:

              
              {
  "to": {
    "alias": [
      "4314",
      "892",
      "4531"
    ]
  }
}

            

• Push a múltiples registration_id:

              
              {
  "to": {
    "registration_id": [
      "4312kjklfds2",
      "8914afd2",
      "45fdsa31"
    ]
  }
}

            

• Se puede enviar simultáneamente a varios tipos de destinos de push específicos: en Shenzhen o Guangzhou y son "female" "members"

              
              {
  "to": {
    "tag": [
      "Shenzhen",
      "Guangzhou"
    ],
    "tag_and": [
      "female",
      "members"
    ]
  }
}

            

• Enviar un mensaje de actividad en tiempo real

              
              {
  "to": {
    "live_activity_id": "LiveActivity-1"
  }
}

            

Enviar al ID de segmentación de usuario:

              
              {
  "to": {
    "seg": {
      "id": "segid"
    }
  }
}

            

Body

Cuerpo de la solicitud de envío. Los campos admitidos son los siguientes:

Platform

AppPush actualmente admite push para las plataformas Android, iOS y HarmonyOS. Las palabras clave son: "android", "ios", "hmos".

Push a todas las plataformas:

              
              { "platform" : "all" }

            

Designación de plataformas de push específicas:

              
              {
  "platform": [
    "android",
    "ios",
    "hmos"
  ]
}

            

Notification

El objeto "Notification" es uno de los objetos de contenido de entidad de un push (el otro es "Message") y se envía al cliente como "Notification".

Alert

La propiedad "alert" en esta ubicación (directamente bajo el objeto notification) es una definición abreviada; si el mensaje de alert es el mismo en todas las plataformas, puede no definirse bajo cada plataforma y prevalecerá este valor. Si existe una definición para cada plataforma, esta sobrescribirá la definición de aquí.

              
              {
  "notification" : {
    "alert" : "Hello, Push!"
  }
}

            

El objeto notification definido anteriormente se enviará a varias plataformas especificadas por "platform" y todas tendrán el mismo mensaje de alert de notificación.

Android

Las notificaciones en la plataforma Android se muestran mediante el SDK de AppPush conforme a estilos específicos de la barra de notificaciones. Los campos admitidos son los siguientes:

              
              {
    "notification": {
        "android": {
            "alert": "hello, MTPush!",
            "title": "Push test",
            "builder_id": 3,
            "style": 1,
            "big_text": "big text content",
            "inbox":JSONObject,
            "big_pic_path": "picture url",
            "priority": 0,
            "category": "category str",
            "large_icon": "http://pushapi-sgp.engagelab.comlargeIcon.jpg",
            "small_icon": "http://www.small.com/small_icon.jpg",
            "intent": {
                "url": "intent:#Intent;component=push.pushapi-sgp.engagelab.com/com.example.mtpushdemo.SettingActivity;end"
            },
            "extras": {
                "news_id": 134,
                "my_key": "a value"
            }
        }
    }
}

            

iOS

Notificaciones de APNs en la plataforma iOS.

El contenido de la notificación se envía mediante el agente de AppPush al servidor APNs de Apple y se presenta en el dispositivo iOS como una notificación del sistema.

El contenido de la notificación cumple con la especificación de APNs y admite los siguientes campos:

Ejemplo de envío del lado del servidor:

              
              {
    "notification": {
        "ios": {
            "alert": "hello, Push!",
            "sound": "sound.caf",
            "badge": 1,
            "extras": {
                "news_id": 134,
                "my_key": "a value"
            }
        }
    }
}

            

Mensaje recibido por el cliente:

              
              {
  "_j_msgid" = 813843507;
  aps =     {
  alert = "hello,Push!";
  badge = 1;
  sound = "sound.caf";
};
"my_key" = "a value";
"news_id" = 134;
}

            

hmos

Las notificaciones en la plataforma HarmonyOS se muestran mediante el SDK de AppPush conforme a estilos de la barra de notificaciones. Los campos admitidos son:

Ejemplo:

              
              {
  "notification": {
    "hmos": {
      "alert": "Hi, MTPush!",
      "title": "",
      "category": "",
      "intent": {"url": ""},
      "badge_add_num": 1,
      "test_message": true,
      "receipt_id": "",
      "extras": {},
      "style": 0,
      "inbox_content": [],
      "push_type": 0,
      "extra_data": "",
      "display_foreground": "1"
    }
  }
}

            

Message

Mensajes dentro de la aplicación. También denominados: mensajes personalizados, mensajes de paso directo.

• Esta parte no se muestra en la barra de notificaciones; el SDK de AppPush recibe el contenido del mensaje y lo transmite a la aplicación.
• iOS obtiene esta parte en un canal de mensajes in-app de push (no APNs) con la aplicación en primer plano.

Los campos admitidos son los siguientes:

Ejemplo:

              
              {
  "message": {
    "msg_content": "Hi,Push",
    "content_type": "text",
    "title": "msg",
    "extras": {
      "key": "value"
    }
  }
}

            

Live_activity

Nota: Los mensajes de actividad en tiempo real requieren el uso de un certificado iOS P8, que corresponde a seleccionar "Token Authentication Configuration" en la configuración del método de autenticación iOS de WebPortal.

El cuerpo de contenido del mensaje de actividad en tiempo real incluye la siguiente información de campos:

Objeto JSON de iOS

Objeto JSON alert de iOS

• Los mensajes de actividad en tiempo real de iOS para EngageLab Push se reenvían a los servidores de Apple. Apple exige que los datos de actualización dinámica de los mensajes de actividad en tiempo real (ActivityKit) no superen los 4096 bytes.
• EngageLab Push, debido a los requisitos de reempaquetado y considerando la redundancia de seguridad, estipula que la longitud total dentro de los parámetros "live_activity" para "iOS": { } y el contenido dentro de las llaves no debe exceder 3584 bytes. JPush utiliza codificación UTF-8, lo que significa que un carácter chino ocupa 3 bytes.

Ejemplo de push de actividad en tiempo real

El attributes-type y el live_activity_id utilizados para las actividades en tiempo real se reportan desde el SDK del desarrollador. Antes de usar actividades en tiempo real, se deben reportar el token de inicio por push del dispositivo y el update-token. Para obtener procedimientos detallados, consultar las instrucciones de actividad en tiempo real del fabricante Apple.

• Creación

  { "from": "push", "to": { "registration_id": [ "161a3797c816b134042" ] }, "body": { "platform": "ios", "live_activity": { "ios": { "event": "start", "content-state": { "eventStr": "hello", "eventTime":1685952000 }, "attributes": { "name": "1", "number": 2, "tag": "mytag" }, "alert": { "title": "hello", "body": "welcome" }, "attributes-type": "my_la_type", "relevance-score": 100, "apns-priority": 10 } } }, "request_id": "12345678", "custom_args": "12345678" }

                
                {
      "from": "push",
     "to": {
          "registration_id": [
              "161a3797c816b134042"
          ]
      },
      "body": {
          "platform": "ios",
          "live_activity": {
              "ios": {
                  "event": "start",
                  "content-state": {
                      "eventStr": "hello",
                      "eventTime":1685952000
                  },
                  "attributes": {
                      "name": "1",
                      "number": 2,
                      "tag": "mytag"
                  },
                  "alert": {
                      "title": "hello",
                      "body": "welcome"
                  },
                  "attributes-type": "my_la_type",
                  "relevance-score": 100,
                  "apns-priority": 10
              }
          }
      },
      "request_id": "12345678",
      "custom_args": "12345678"
  }
  
              

  Este bloque de código se muestra en una ventana flotante

• Actualización

  { "from": "push", "to": { "live_activity_id": "my_la_id" }, "body": { "platform": "ios", "live_activity": { "ios": { "event": "update", "content-state": { "eventStr": "test_live", "eventTime": 198 }, "alert": { "title": "123411", "body": "123411" } } } }, "request_id": "12345678", "custom_args": "12345678" }

                
                {
     "from": "push",
     "to": {
           "live_activity_id": "my_la_id"
      },
      "body": {
          "platform": "ios",
          "live_activity": {
              "ios": {
                  "event": "update",
                  "content-state": {
                      "eventStr": "test_live",
                      "eventTime": 198
                  },
  
                  "alert": {
                      "title": "123411",
                      "body": "123411"
                  }
              }
          }
      },
      "request_id": "12345678",
      "custom_args": "12345678"
  }
  
              

  Este bloque de código se muestra en una ventana flotante

VoIP

Funcionalidad VoIP de iOS. Este tipo no admite coexistencia con otros tipos de mensajes iOS. Se puede consultar la estructura de parámetros de la solicitud:

              
              { 
    "from": "push", 
    "to": { 
        "registration_id": [ "1a0018970a91da03de5" ] 
    }, 
    "request_id": "12345", 
    "custom_args": "12345", 
    "body": { 
        "platform": "ios", 
        "voip": { 
            "key": "value // Any custom key/value pair that will be passed to the APP" 
        } 
    } 
}

            

Options

Las opciones actuales de notificación push incluyen lo siguiente:

Multi_language

Este campo corresponde a la función de push multilingüe del servicio EngageLab Push. Permite enviar contenido de notificación personalizado a usuarios en diferentes idiomas. Al especificar varios idiomas junto con su contenido de mensaje, títulos y subtítulos de iOS correspondientes en la solicitud de push, se pueden enviar notificaciones push adecuadas según la configuración de idioma del usuario.

Parámetros de solicitud

• Nota sobre HarmonyOS: al usar HarmonyOS, utilizar third_party_channel.hmos.distribution_new. No se ve afectado por la configuración global.

Ejemplo de solicitud

              
                 HTTP Request Method: POST
   Request URL: /v4/grouppush or /v4/push
   Request Data Format: JSON
   Request Example:
   {
    "options": {
      "multi_language": {
        "en": {
          "content": "",
          "title": "",
          "ios_subtitle": ""
        }
      }
    }
   }

            

Ejemplo de solicitud

              
              Successful Response:
{
   
}

            

              
              
Failed Response:
{   
    "code": 400,  
    "data": "",
  "message": "Error Message"
}   

            

Third_party_channel

Este campo se utiliza para rellenar la información personalizada del canal de proveedor Android. La clave admite los siguientes canales de proveedor: xiaomi, huawei, meizu, oppo, vivo, fcm, honor, hmos. Pueden existir uno o varios al mismo tiempo. La clave (KEY) de cada tipo de proveedor puede contener actualmente las siguientes opciones:

Parámetros de solicitud

Para unificar las estrategias de canales de múltiples proveedores y simplificar la lógica de configuración, el método de configuración del campo distribution_new se ajusta de la siguiente manera. Sus configuraciones heredadas a nivel de proveedor seguirán siendo válidas, pero se recomienda migrar gradualmente a configuraciones globales para evitar riesgos de compatibilidad en el futuro. (Las nuevas reglas entrarán en vigor a partir del 2025.04.03):

• Prioridad de configuración (nuevas reglas)
  • Primera prioridad: configuración global third_party_channel.distribution_new (nuevo método recomendado)
    Ejemplo: "distribution_new": "pns_mtpush"
  • Segunda prioridad: configuración a nivel de proveedor third_party_channel.{vendor_key}.distribution_new (método heredado compatible)
    Solo tiene efecto cuando no se establece la configuración global
  • Sin configuración: estrategia predeterminada: pns_mtpush

Ejemplo de solicitud

              
              {
    "third_party_channel": {
        "distribution_new": "pns_mtpush",
        "xiaomi": {
            "channel_id": "*******",
            "small_icon_uri": "http://f6.market.xiaomi.com/download/MiPass/x/x.png",
            "small_icon_color": "#ABCDEF"
        },
        "huawei": {
            "importance": "NORMAL",
            "small_icon_uri": "https://xx.com/xx.jpg",
            "only_use_vendor_style": true
        },
        "oppo": {
            "channel_id": "*******",
            "big_picture_id": "",
            "small_picture_id": ""
        },
        "vivo": {
            "pushMode": 0
        },
        "hmos": {
            "distribution_new": "pns_mtpush"
        }
    }
}

            

request_id

ID de solicitud (request id), campo opcional definido por el cliente. Se utiliza para que el cliente identifique qué solicitud se está realizando y se devuelve en la respuesta.

Ejemplo de solicitud

              
              {
      "request_id":"12345678"
}

            

Ejemplo de retorno

              
              {
    "msg_id": "1225764",
    "request_id": "12345678"
}

            

Custom_args

Campo opcional definido por el cliente, que no se devuelve en la respuesta y se devuelve en el callback.

Ejemplo de solicitud

              
              {
  "custom_args":{
    "args1": "args1"
  }
}

            

Parámetros de retorno

Respuesta correcta

              
              < HTTP/1.1 200 OK
< Content-Type: application/json
{"request_id":"18","msg_id":"1828256757"}

            

Respuesta fallida

El código de estado HTTP es 4xx o 5xx y el cuerpo de la respuesta contiene los siguientes campos:

              
              {
    "error":{
    "code": 3002,
    "message": "Push.template field must be set correctly when type is template"
    }
}

            

Respuestas de la llamada

Código de estado HTTP

Documento de referencia: HTTP-Status-Code

Código de error

Limitaciones de push

Código de varios idiomas