API de etiquetas y alias

La API de dispositivos (Device API) se utiliza para consultar, configurar, actualizar y eliminar información de etiquetas (tag) 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 sean sobrescritas por el lado del cliente.

• Si no está familiarizado con las etiquetas y la lógica de alias, se recomienda utilizar únicamente el cliente o el servidor.
• Si se utiliza en ambos lados al mismo tiempo, asegúrese de que la aplicación puede 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 cliente correspondiente.

• web-tag,alias

Reglas y restricciones para el uso de etiquetas

• Límite de cantidad de etiquetas: Con una sola appkey, se pueden crear hasta 100.000 etiquetas.
• Límite de longitud de la etiqueta: La longitud máxima de cada etiqueta 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 para dispositivos: Cada dispositivo puede vincular hasta 100 etiquetas.
• Límite de cantidad de dispositivos: Bajo una sola etiqueta, 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 para el 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 alcance de la appkey solo puede asignarse a un alias, no a varios alias.
• Límite de cantidad de alias: Con una sola appkey, se pueden crear hasta 100.000 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, configurar, actualizar y eliminar información de etiquetas y alias del dispositivo en el lado del servidor.

Incluye tres conjuntos de API: device, tag y alias. En concreto:

• device se utiliza para consultar y configurar varias propiedades del dispositivo, incluidas etiquetas y alias;
• tag se utiliza para consultar, configurar y eliminar la etiqueta del dispositivo;
• alias se utiliza para consultar, configurar y eliminar el alias del dispositivo.

La información clave que se debe utilizar es el ID de registro (registration_id):

El ID de registro (registration_id) del dispositivo se obtiene después de integrar el cliente; consulte la documentación de la API en Web para obtener más detalles.

El servidor no proporciona una API para obtener el valor de registration_id; el desarrollador debe obtener el registration_id desde el cliente y cargarlo en el servidor del desarrollador para su almacenamiento.

Consultar el número de etiquetas 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

• Tag: Consultar la cadena de la etiqueta (tag) especificada; campo obligatorio; se permite consultar hasta 1000 etiquetas a la vez (tags=tag1&tags=tag2&tags=tag3).
• platform: Consultar la plataforma especificada; campo obligatorio; los valores permitidos son android e ios.

Ejemplos de respuesta

Respuesta correcta

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

            

Respuesta fallida

              
              {
    "error": {
        "code": 21008,
        "message": "la app_key no es una cadena de 24 caracteres o no existe."
    }
}

            

Consultar alias y etiquetas del dispositivo

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

Dirección de llamada

              
              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

Devuelto correctamente

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

            

Datos devueltos

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

            

Configurar el alias y la etiqueta del dispositivo

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

Dirección de llamada

              
              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ámetros de la solicitud

• tags: admite add, remove o una cadena vacía. Cuando es una cadena vacía, significa borrar todas las etiquetas; en add/remove, se añade o elimina la etiqueta especificada.
• alias: Actualizar el atributo alias del dispositivo; cuando el alias es una cadena vacía, se elimina el alias del dispositivo especificado.

Ejemplo de respuesta

Devuelto correctamente

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

            

Datos devueltos

              
              success

            

Eliminar el dispositivo

Dirección de llamada

              
              DELETE /v4/devices/{registration_id}

            

Consultar lista de etiquetas

• Obtener una lista de todas las etiquetas de la aplicación actual.

Dirección de llamada

              
              GET /v4/tags/

            

Parámetros de la solicitud

• Ninguno

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

• Consultar si un dispositivo está bajo una etiqueta.

Dirección de llamada

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

            

Actualizar etiquetas

• Añadir o eliminar dispositivos para una etiqueta.

Dirección de llamada

              
              POST /v4/tags/{tag_value}

            

Parámetros de la solicitud

• action: tipo de acción, add o remove.
• registration_ids: El registration_id del dispositivo que se va a añadir o eliminar.
• add/remove: admite hasta 1000 dispositivos cada uno.

Eliminar etiqueta

Eliminar una etiqueta y la asociación entre la etiqueta y el dispositivo.

Dirección de llamada

              
              DELETE /v4/tags/{tag_value}

            

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

              
              GET /v4/aliases/{alias_value}

            

Eliminar alias

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

              
              DELETE /v4/aliases/{alias_value}

            

Obtener el estado en línea del usuario

Dirección de llamada

              
              POST /v4/devices/status/

            

Datos devueltos

• online
  • true: ha estado en línea durante 10 minutos o menos;
  • false: no ha estado en línea durante 10 minutos;
• last_online_time
  • Cuando online es true, no se devuelve este campo.
  • Cuando online es false y no se devuelve el campo, la última vez en línea fue hace dos días.

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

Consultar la información de cuota relacionada de la AppKey, la plataforma y la etiqueta especificadas. El número de etiquetas en una sola consulta no puede superar 1.000.

Definición de campos devueltos:

• totalTagQuota: Indica la cuota total de etiquetas bajo la aplicación.
• useTagQuota: Indica la cuota de etiquetas utilizada.
• totalAliasQuota: Indica la cuota total de alias bajo la aplicación.
• useAliasQuota: Indica la cuota de alias utilizada.
• totalUidQuota: Indica la cuota total de dispositivos para una sola etiqueta.
• useUidQuota: Indica el detalle de la cantidad de dispositivos vinculados a cada etiqueta.

Código de retorno de negocio