API de etiquetas y alias

La API de dispositivos (Device API) se utiliza para consultar, establecer, actualizar y eliminar la información de etiquetas y alias del dispositivo en el lado del servidor. Al utilizarla, se debe tener cuidado de no permitir que las etiquetas configuradas en el lado del servidor se sobrescriban desde el cliente.

• Si no está familiarizado con la lógica de etiquetas y alias, se recomienda utilizar solo uno de los dos enfoques: lado del cliente o lado del servidor.
• Si utiliza ambos, asegúrese de que la aplicación pueda gestionar la sincronización de etiquetas y alias.

Para obtener más información sobre etiquetas y alias, consulte la descripción de la API de la plataforma de cliente correspondiente.

• Android - etiquetas, alias
• iOS - etiquetas, alias
• HarmonyOS - etiquetas, alias

Reglas y restricciones de uso de etiquetas

• Límite de cantidad de etiquetas: En una sola appkey, se pueden crear hasta 100.000 tags.
• Límite de longitud de etiquetas: La longitud máxima de cada tag es de 40 bytes. Los caracteres válidos incluyen letras (distingue mayúsculas y minúsculas), números, guiones bajos y caracteres chinos.
• Límite de vinculación de etiquetas por dispositivo: Cada dispositivo puede vincular hasta 100 tags.
• Límite de cantidad de dispositivos: En un solo tag, se pueden añadir hasta 100.000 dispositivos.

Si es suscriptor de nuestro plan de pago y desea ajustar el límite de uso de su AppKey de pago, póngase en contacto con nuestro equipo comercial en: Sales@engagelab.com

Reglas y restricciones de uso de alias

• Asignación de dispositivo a alias: Un alias solo puede corresponder a un dispositivo, no a varios. Del mismo modo, cada dispositivo dentro del ámbito de la appkey solo puede asignarse a un alias, no a varios alias.
• Límite de longitud de alias: La longitud máxima de cada alias es de 40 bytes. Los caracteres válidos incluyen letras (distingue mayúsculas y minúsculas), números, guiones bajos y caracteres chinos.

Si es suscriptor de nuestro plan de pago y desea ajustar el límite de uso de su AppKey de pago, póngase en contacto con nuestro equipo comercial en: Sales@engagelab.com

Visión general de la API

La API de dispositivos (Device API) se utiliza para consultar, establecer, actualizar y eliminar la información de etiquetas y alias del dispositivo en el lado del servidor.

Incluye tres API: device, tag, alias:

• device: se utiliza para consultar/establecer varios atributos del dispositivo, incluidas etiquetas y alias;
• tag: se utiliza para consultar/establecer/eliminar el tag del dispositivo;
• alias: se utiliza para consultar/establecer/eliminar el alias del dispositivo.

El ID de registro (registration ID) también es una información clave que se debe utilizar:

El registration_id del dispositivo se obtiene tras la integración en el lado del cliente; para obtener más detalles, consulte la documentación de la API para Android, iOS y HarmonyOS.

El lado del servidor no proporciona una API para obtener el valor registration ID del dispositivo; el desarrollador debe obtener el registration ID en el lado del cliente y cargarlo en el servidor del desarrollador para su almacenamiento.

Dirección de la solicitud

https://pushapi-sgp.engagelab.com/v4/devices

Consultar el número de tags bajo una AppKey

URL de destino

              
              GET /v4/tags_count

            

Ejemplo de solicitud

Encabezados de la solicitud

              
              GET /v4/tags_count
Authorization: Basic (base64 auth string)
Accept: application/json

            

Ejemplo

              
              curl -X GET http://127.0.0.1/v4/tags_count?tags=tag1&tags=tag2&platform=ios -u "appKey:appSecret"

            

Parámetros de la solicitud

• tags: Consultar la cadena de tag especificada; campo obligatorio; se permite consultar hasta 1000 tags por vez (tags=tag1&tags=tag2&tags=tag3).
• platform: Consultar la plataforma especificada; campo obligatorio; los valores opcionales son android, ios, hmos. No se permiten otros valores.

Ejemplos de respuesta

• Una respuesta correcta devolverá un objeto JSON que contiene un campo tagsCount. Se trata de una colección de pares clave-valor en la que la clave es el nombre del tag y el valor es el recuento de ese tag.
• Si la solicitud falla, se devolverá un objeto JSON que contiene información de error. El campo code indica el código de error y el campo message indica el mensaje de error.

Devolución correcta

              
              {
    "tagsCount": {
        "tag1": 0,
        "tag2": 1,
        "tag3": 2
    }
}

            

Devolución con error

              
              {
    "error": {
        "code": 21008,
        "message": "app_key is not a 24 size string or does not exist"
    }
}

            

Consulta de alias y etiquetas del dispositivo

• Obtener todos los atributos del dispositivo actual, incluidas etiquetas y alias.

Dirección de la solicitud

              
              GET /v4/devices/{registration_id}

            

Ejemplo de solicitud

Encabezado de la solicitud

              
              GET /v4/devices/{registration_id}
  Authorization: Basic (base64 auth string) 
  Accept: application/json

            

Parámetro de la solicitud

• N/A

Ejemplo de respuesta

Devolución correcta

              
              HTTP/1.1 200 OK 
  Content-Type: application/json; charset=utf-8

            

Datos devueltos

              
              {
  "tags": ["tag1", "tag2"],
  "alias": "alias1"
}

            

• Si no se encuentra el valor, es null; de lo contrario, es el valor devuelto.

Establecer el alias y la etiqueta del dispositivo

• Actualizar los atributos especificados del dispositivo actual; actualmente se admiten tags y alias.

Dirección de la solicitud

              
              POST /v4/devices/{registration_id}

            

Ejemplo de solicitud

Encabezado de la solicitud

              
              POST /v4/devices/{registration_id}
  Authorization: Basic (base64 auth string) 
  Accept: application/json

            

Datos de la solicitud

              
              {
    "tags": {
        "add": [
            "tag1",
            "tag2"
        ],
        "remove": [
            "tag3",
            "tag4"
        ]
    },
    "alias": "alias1"
}

            

Parámetro de la solicitud

• tags: admite add, remove o cadena vacía. Cuando el parámetro tags es una cadena vacía, significa que se borran todos los tags; en add/remove, se añade o elimina el tag especificado.
• alias: Actualizar el atributo alias del dispositivo; cuando alias es una cadena vacía, se elimina el alias del dispositivo especificado.

Ejemplo de respuesta

Devolución correcta

              
              HTTP/1.1 200 OK 
  Content-Type: application/json; charset=utf-8

            

Datos devueltos

              
              success

            

Devolución con error

              
              {
  "error":{
    "code":27002, 
    "message":"unknown error"
  }
}

            

Eliminar el dispositivo

• Eliminar el dispositivo.

Dirección de la solicitud

              
              DELETE /v4/devices/{registration_id}

            

Ejemplo de solicitud

Encabezado de la solicitud

              
              DELETE /v4/devices/{registration_id}
   Authorization: Basic (base64 auth string)
   Accept: application/json

            

Datos de la solicitud

• N/A

Parámetros de la solicitud

• N/A

Ejemplo de respuesta

Devolución correcta

              
              HTTP/1.1 200 OK
   Content-Type: application/json; charset=utf-8

            

Datos devueltos

              
              success

            

Devolución con error

              
              {
  "error":{
    "code":27002, 
    "message":"unknown error"
  }
}

            

Consultar lista de tags

• Obtener una lista de todos los tags de la aplicación actual.

Dirección de la solicitud

              
              GET /v4/tags/

            

Ejemplo de solicitud

Encabezado de la solicitud

              
              GET /v4/tags/
  Authorization: Basic (base64 auth string) 
  Accept: application/json

            

Parámetros de la solicitud

• Ninguno

Ejemplo de respuesta

Devolución correcta

              
              HTTP/1.1 200 OK 
  Content-Type: application/json; charset=utf-8

            

Datos devueltos

              
              {
  "tags": [
    "tag1",
    "tag2"
  ]
}

            

• El valor es null si no se encuentra ningún dato; de lo contrario, se devuelve el valor correspondiente.

Consultar la relación de vinculación entre dispositivo y tag

• Consultar si un dispositivo está bajo el tag.

Dirección de la solicitud

              
              GET /v4/tags/{tag_value}/registration_ids/{registration_id}

            

Ejemplo de solicitud

Encabezado de la solicitud

              
              GET /v4/tags/{tag_value}/registration_ids/090c1f59f89
  Authorization: Basic (base64 auth string) 
  Accept: application/json

            

Parámetros de la solicitud

• registration_id: Obligatorio; registration_id del dispositivo.

Ejemplo de respuesta

Devolución correcta

              
              HTTP/1.1 200 OK 
  Content-Type: application/json; charset=utf-8

            

Datos devueltos

              
              {"result": true/false}

            

Actualizar tags

• Añadir o eliminar dispositivos de un tag.

Dirección de la solicitud

              
              POST /v4/tags/{tag_value}

            

Ejemplo de solicitud

Encabezado de la solicitud

              
              POST /v4/tags/{tag_value}
  Authorization: Basic (base64 auth string) 
  Accept: application/json

            

Datos de la solicitud

              
              {  
  "registration_ids":{
    "add": [
      "registration_id1",
      "registration_id2"
    ],
    "remove": [
      "registration_id1",
      "registration_id2"
    ]
  }
}

            

Parámetros de la solicitud

• action: Tipo de acción, con dos opciones: "add", "remove", que identifica si la solicitud es para añadir o eliminar.
• registration_ids: registration_id del dispositivo que se va a añadir/eliminar.
• add/remove: admite hasta 1000 dispositivos en cada caso.

Ejemplo de respuesta

Devolución correcta

              
              HTTP/1.1 200 OK 
 Content-Type: application/json; charset=utf-8

            

Datos devueltos

              
              success

            

Devolución con error

              
              {
    "error": {
        "code": 27005,
        "message": "registration id is illegal",
        "data": "{\"invalid_regids\":[\"18071adc021ff8df80\",\"100d85592955c1f1058\"]}"
    }
}

            

Eliminar tag

Se elimina un tag y la asociación entre el tag y el dispositivo.

Dirección de la solicitud

              
              DELETE /v4/tags/{tag_value}

            

Ejemplo de solicitud

Encabezado de la solicitud

              
              DELETE /v4/tags/{tag_value}?platform=android,ios,hmos
  Authorization: Basic (base64 auth string) 
  Accept: application/json

            

Parámetros de la solicitud

• platform es un parámetro opcional; si no se especifica, el valor predeterminado es todas las plataformas.

Ejemplo de respuesta

Devolución correcta

              
              HTTP/1.1 200 OK 
 Content-Type: application/json; charset=utf-

            

Datos devueltos

              
              success

            

Devolución con error

              
              {
  "error":{
    "code":27002, 
    "message":"unknown error"
  }
}

            

Consultar alias (relación de vinculación con el dispositivo)

• Obtener los dispositivos bajo el alias especificado.

Dirección de la solicitud

              
              GET /v4/aliases/{alias_value}

            

Ejemplo de solicitud

Encabezado de la solicitud

              
              GET /v4/aliases/{alias_value}?platform=android,ios,hmos
  Authorization: Basic (base64 auth string) 
  Accept: application/json

            

Parámetros de la solicitud

• platform es un parámetro opcional; si no se especifica, el valor predeterminado es todas las plataformas.

Ejemplo de respuesta

Devolución correcta

              
              HTTP/1.1 200 OK 
  Content-Type: application/json; charset=utf-8

            

Datos devueltos

              
              {
   "registration_ids": [
     "registration_id1",
     "registration_id2"
   ]
}

            

• El valor es null si no se encuentra ningún dato; de lo contrario, se devuelve el valor correspondiente.

Eliminar alias

Se elimina un alias y la relación de vinculación entre el alias y el dispositivo.

              
              DELETE /v4/aliases/{alias_value}

            

Ejemplo de solicitud

Encabezado de la solicitud

              
              DELETE /v4/aliases/{alias_value}?platform=android,ios,hmos
  Authorization: Basic (base64 auth string) 
  Accept: application/json

            

Parámetros de la solicitud

• platform es un parámetro opcional; si no se especifica, el valor predeterminado es todas las plataformas.

Ejemplo de respuesta

• Correcto

              
              success

            

• Error

              
              {
  "error":{
    "code":27002, 
    "message":"unknown error"
  }
}

            

Obtener el estado en línea del usuario

Dirección de la solicitud

              
              POST /v4/devices/status/

            

Ejemplo de solicitud

Encabezado de la solicitud

              
              POST /v4/devices/status/
  Authorization: Basic (base64 auth string) 
  Accept: application/json

            

Datos de la solicitud

              
              {
  "registration_ids": [
    "010b81b3582",
    "0207870f1b8",
    "0207870f9b8"
  ]
}

            

Parámetros de la solicitud

• registration_ids: registration_id del usuario cuyo estado en línea se debe consultar; se admite consultar hasta 1000 registration_ids.
• Antes de poder invocar esta API, se debe solicitar un Appkey que tenga habilitado este servicio.

Ejemplo de respuesta

Devolución correcta

              
              HTTP/1.1 200 OK 
  Content-Type: application/json; charset=utf-8

            

Datos devueltos

              
              [
  {
    "regid": "010b81b3582",
    "online": true
  },
  {
    "regid": "0207870f1b8",
    "online": false,
    "last_online_time": "2014-12-16 10:57:07"
  },
  {
    "regid": "0207870f9b8",
    "online": false
  }
]

            

Datos devueltos

• online
  • true: en línea durante 10 minutos o menos;
  • false: no está en línea durante 10 minutos;
• last_online_time
  • Cuando online es true, este campo no se devuelve.
  • Cuando online es false y el campo no se devuelve, la última vez en línea fue hace dos días.
• La verificación fallará para regid no válido o para regid que no pertenezca a la appkey.

Interfaz de consulta de información de cuota de tag/alias

Consultar la información de cuota relacionada del AppKey, la plataforma y el tag especificados. El número de tags en una sola consulta no puede superar 1.000.

Dirección de la solicitud

              
              GET /v4/tags/quota-info?tags=tag1&platform=android
Authorization: Basic (base64 auth string)
Accept: application/json

            

Ejemplo de solicitud

              
              curl --location 'https://pushapi-sgp.engagelab.com/v4/tags/quota-info?platform=android&tags=tag1&tags=tag2' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YjA2MTBmZGE0M2JmNmFkMTczNGNjMWY2OmQyNGMzZDk1Yzk1M2M3YmFkNzRkM2Q5YQ=='

            

Devolución correcta

              
              {
    "data": {
        "totalTagQuota": 100000,
        "useTagQuota": 1,
        "totalAliasQuota": 100000,
        "useAliasQuota": 3,
        "tagUidQuotaDetail": [
            {
                "tagName": "tag1",
                "totalUidQuota": 100000,
                "useUidQuota": 0
            },
            {
                "tagName": "tag2",
                "totalUidQuota": 100000,
                "useUidQuota": 0
            }
        ]
    }
}

            

Definición de campos devueltos:

• totalTagQuota: Indica la cuota total de tags en la aplicación.
• useTagQuota: Indica la cuota de tags utilizada.
• totalAliasQuota: Indica la cuota total de alias en la aplicación.
• useAliasQuota: Indica la cuota de alias utilizada.
• tagUidQuota: Indica la cuota de número de dispositivos para un solo tag.
• useUidQuota: Indica el detalle del número de dispositivos vinculados a cada tag.

Devolución con error

              
              {
    "error": {
        "code": 27002,
        "message": "Illegal parameter"
    }
}

            

Códigos de estado HTTP

Documento de referencia: Http-Status-Code

Código de retorno de negocio