API de alias de etiquetas

La API de dispositivos se utiliza para consultar, establecer, actualizar y eliminar la información de etiquetas y alias de un dispositivo en el servidor. Al utilizarla, ten cuidado de evitar que las etiquetas establecidas en el servidor sean sobrescritas por el cliente.

• Si no estás familiarizado con la lógica de etiquetas y alias, se recomienda utilizar solo uno de los dos lados: el cliente o el servidor.
• Si ambos lados se utilizan al mismo tiempo, asegúrate de que tu aplicación pueda gestionar correctamente la sincronización de etiquetas y alias.

Para obtener información detallada sobre las etiquetas y los alias, consulta la documentación de la API de la plataforma cliente correspondiente.

• web - etiqueta, alias

Restricciones y reglas para el uso de TAG

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

Si eres usuario de un plan de pago y deseas ajustar los límites de uso de una AppKey de pago, ponte en contacto con nuestro equipo comercial en Sales@engagelab.com.

Restricciones y reglas para el uso de alias

• Relación de asignación entre dispositivo y alias: Un alias solo puede corresponder a un dispositivo y no puede corresponder a varios dispositivos. Del mismo modo, cada dispositivo solo puede asignarse a un alias dentro del ámbito de la appkey y no puede asignarse a varios alias.
• Límite de cantidad de alias: En una sola appkey, puedes 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 (distinguiendo mayúsculas de minúsculas), números, guiones bajos y caracteres chinos.

Si eres usuario de un plan de pago y deseas ajustar los límites de uso de una AppKey de pago, ponte en contacto con nuestro equipo comercial en Sales@engagelab.com.

Resumen de la API

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

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

• device se utiliza para consultar o establecer varias propiedades de un dispositivo, incluidas tags y alias;
• tag se utiliza para consultar, establecer o eliminar etiquetas de dispositivos;
• alias se utiliza para consultar, establecer o eliminar alias de dispositivos.

Otra información clave que necesitas es el registration_id:

El registration_id del dispositivo se obtiene después de la integración del cliente. Para más detalles, consulta la documentación de la API web.

El servidor no proporciona una API para obtener el valor registration_id del dispositivo. Los desarrolladores deben obtener el registration_id desde el cliente y subirlo al servidor del desarrollador para almacenarlo.

Consultar el número de tags de una AppKey

Endpoint

              
              GET /v4/tags_count

            

Ejemplo de solicitud

Encabezados de la solicitud

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

            

Ejemplo de solicitud

              
              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: Consulta las cadenas de tags especificadas. Obligatorio. Se pueden consultar hasta 1000 tags en una sola solicitud (tags=tag1&tags=tag2&tags=tag3).
• platform: Consulta la plataforma especificada. Obligatorio. Los valores válidos son android, ios, hmos y web. No se permiten otros valores.

Ejemplo de respuesta

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

Respuesta correcta

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

            

Respuesta fallida

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

            

Consultar el alias y las tags de un dispositivo

• Obtiene todas las propiedades del dispositivo actual, incluidas tags y alias.

Endpoint

              
              GET /v4/devices/{registration_id}

            

Ejemplo de solicitud

Encabezados de la solicitud

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

            

Parámetros de la solicitud

• registration_id: Obligatorio. El registration_id del dispositivo.

Ejemplo de respuesta

Respuesta correcta

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

            

Datos de respuesta

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

            

• Si no se puede encontrar el elemento estadístico, será null; en caso contrario, será el valor de ese elemento.

Establecer el alias y las tags de un dispositivo

• Actualiza las propiedades especificadas del dispositivo actual. Actualmente admite tags y alias.

Endpoint

              
              POST /v4/devices/{registration_id}

            

Ejemplo de solicitud

Encabezados 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

• registration_id: Obligatorio. El registration_id del dispositivo.
• tags: Admite add, remove o una cadena vacía. Cuando el parámetro tags es una cadena vacía, significa que se eliminarán todas las tags. add/remove se utiliza para añadir o eliminar las tags especificadas.
• alias: Actualiza la propiedad alias del dispositivo. Cuando el alias es una cadena vacía, se elimina el alias del dispositivo especificado.

Ejemplo de respuesta

Respuesta correcta

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

            

Datos de respuesta

              
              success

            

Respuesta fallida

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

            

Consultar la lista de tags

• Obtiene la lista de todas las tags de la aplicación actual.

Endpoint

              
              GET /v4/tags/

            

Ejemplo de solicitud

Encabezados de la solicitud

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

            

Parámetros de la solicitud

• Ninguno

Ejemplo de respuesta

Respuesta correcta

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

            

Datos de respuesta

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

            

• Si no se puede encontrar el elemento estadístico, será null; en caso contrario, será el valor de ese elemento.

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

• Consulta si un dispositivo pertenece a una tag.

Endpoint

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

            

Ejemplo de solicitud

Encabezados de la solicitud

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

            

Parámetros de la solicitud

• tag_value: Obligatorio. La tag que se va a consultar.
• registration_id: Obligatorio. El registration_id del dispositivo.

Ejemplo de respuesta

Respuesta correcta

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

            

Datos de respuesta

              
              {"result": true}

            

Actualizar una tag

• Añade o elimina dispositivos de una tag.

Endpoint

              
              POST /v4/tags/{tag_value}

            

Ejemplo de solicitud

Encabezados 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

• tag_value: Obligatorio. La tag que se va a consultar.
• action: Tipo de operación, con dos opciones: "add" y "remove", que indican si esta solicitud es para añadir o eliminar.
• registration_ids: Los valores registration_id de los dispositivos que se van a añadir o eliminar.
• add/remove: Admite hasta 1000 elementos cada uno.

Ejemplo de respuesta

Respuesta correcta

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

            

Datos de respuesta

              
              success

            

Respuesta fallida

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

            

Eliminar una tag

Elimina una tag y la asociación entre la tag y los dispositivos.

Endpoint

              
              DELETE /v4/tags/{tag_value}

            

Ejemplo de solicitud

Encabezados de la solicitud

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

            

Parámetros de la solicitud

• tag_value: Obligatorio. La tag que se va a consultar.
• platform: Opcional. Si se omite, el valor predeterminado es todas las plataformas.

Ejemplo de respuesta

Respuesta correcta

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

            

Datos de respuesta

              
              success

            

Respuesta fallida

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

            

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

              
              GET /v4/aliases/{alias_value}
Get the device under the specified alias.

            

Consultar un alias

• Obtiene el dispositivo asociado al alias especificado.

Endpoint

              
              GET /v4/aliases/{alias_value}

            

Ejemplo de solicitud

Encabezados de la solicitud

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

            

Parámetros de la solicitud

• alias_value: Obligatorio. El alias que se va a consultar.
• platform: Opcional. Si se omite, el valor predeterminado es todas las plataformas.

Ejemplo de respuesta

Respuesta correcta

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

            

Datos de respuesta

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

            

• Si no se puede encontrar el elemento estadístico, será null; en caso contrario, será el valor de ese elemento.

Eliminar un alias

Elimina un alias y la relación de vinculación entre el alias y los dispositivos.

              
              DELETE /v4/aliases/{alias_value}

            

Ejemplo de solicitud

Encabezados de la solicitud

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

            

Parámetros de la solicitud

• alias_value: Obligatorio. El alias que se va a eliminar.
• platform: Opcional. Si se omite, 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

Endpoint

              
              POST /v4/devices/status/

            

Ejemplo de solicitud

Encabezados 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: Los valores registration_id de usuario para los que se necesita el estado en línea. Se admiten hasta 1000 valores registration_id por consulta.
• Esta API solo puede llamarse para AppKeys que hayan solicitado y habilitado este servicio.

Ejemplo de respuesta

Respuesta correcta

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

            

Datos de respuesta

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

            

Datos de respuesta

• online
  • true: en línea en los últimos 10 minutos
  • false: no ha estado en línea en los últimos 10 minutos
• last_online_time
  • cuando online es true, este campo no se devuelve
  • cuando online es false y este campo no se devuelve, significa que la última vez en línea fue hace más de dos días
• Para valores regid no válidos o valores regid que no pertenezcan a la appkey, la validación fallará.

API de consulta de información de cuota de TAG/alias

Consulta la información de cuota correspondiente para la AppKey, la plataforma y la tag especificadas. No se pueden consultar más de 1000 tags a la vez.

Endpoint

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

            

Ejemplo de solicitud

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

            

Respuesta correcta

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

            

Descripciones de los campos de respuesta:

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

Respuesta fallida

              
              {
  "error": {
    "code": 27002,
    "message": "Invalid parameters"
  }
}

            

Códigos de estado HTTP

Documento de referencia: Http-Status-Code

Códigos de respuesta de negocio