API de Tag y Alias

La API de dispositivos se utiliza en el lado del servidor para consultar, establecer, actualizar y eliminar la información de tags y alias del dispositivo. Al utilizarla, tenga cuidado de no permitir que los tags establecidos por el servidor sean sobrescritos por el cliente.

• Si no está familiarizado con la lógica de los tags y los alias, se recomienda usar solo el lado del cliente o solo el lado del servidor.
• Si ambos lados se utilizan al mismo tiempo, asegúrese de que su aplicación pueda gestionar correctamente la sincronización de tags y alias.

Para obtener información detallada sobre tags y alias, consulte la documentación de la API de la plataforma cliente correspondiente.

• Android - tag, alias
• iOS - tag, alias
• HarmonyOS - tag, alias

Límites y reglas para el uso de TAG

• Límite de cantidad de TAG: En una única AppKey, puede 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 un único tag, puede añadir hasta 100.000 dispositivos.

Si es usuario de un plan de pago y desea ajustar los límites de uso de su AppKey, póngase en contacto con nuestro equipo comercial en Sales@engagelab.com.

Límites y reglas para el uso de Alias

• Asignación entre dispositivo y alias: Un alias solo puede corresponder a un dispositivo y no puede corresponder a varios dispositivos. Del mismo modo, dentro del alcance de una AppKey, cada dispositivo solo puede asignarse a un alias y no puede asignarse 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 (distinguiendo mayúsculas de minúsculas), números, guiones bajos y caracteres chinos.

Si es usuario de un plan de pago y desea ajustar los límites de uso de su AppKey, póngase en contacto con nuestro equipo comercial en Sales@engagelab.com.

Resumen de la API

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

Incluye tres grupos de API: device, tag y alias. Entre ellos:

• device se utiliza para consultar o establecer varios atributos del dispositivo, incluidos tags y alias;
• tag se utiliza para consultar, establecer o eliminar tags del dispositivo;
• alias se utiliza para consultar, establecer o eliminar alias del dispositivo.

Otra información clave necesaria es el ID de registro:

El registration_id del dispositivo se obtiene después de la integración del cliente. Para 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. Los desarrolladores deben obtener el registration ID en el lado del cliente y cargarlo en el servidor del desarrollador para su almacenamiento.

Consultar el número de tags en una AppKey

Endpoint

              
              GET /v4/tags_count

            

Ejemplo de solicitud

Request Header

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

            

Request Example

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

            

Request Parameters

• tags: Consulta las cadenas de tag especificadas. Obligatorio. Se pueden consultar hasta 1.000 tags a la vez (tags=tag1&tags=tag2&tags=tag3).
• platform: Consulta la plataforma especificada. Obligatorio. Los valores válidos son android, ios y hmos. 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 donde la clave es el nombre del tag y el valor es el recuento de ese 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.

Successful Response

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

            

Failed Response

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

            

Consultar el alias y los tags de un dispositivo

• Obtiene todos los atributos del dispositivo actual, incluidos tags y alias.

Endpoint

              
              GET /v4/devices/{registration_id}

            

Ejemplo de solicitud

Request Header

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

            

Request Parameters

• registration_id: Obligatorio. El registration_id del dispositivo.

Ejemplo de respuesta

Successful Response

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

            

Response Data

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

            

• Si no se encuentra un elemento estadístico, será null; en caso contrario, será el valor del elemento estadístico.

Establecer el alias y los tags de un dispositivo

• Actualiza los atributos especificados del dispositivo actual. Actualmente admite tags y alias.

Endpoint

              
              POST /v4/devices/{registration_id}

            

Ejemplo de solicitud

Request Header

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

            

Request Data

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

            

Request Parameters

• 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, se eliminan todos los tags. add/remove significa añadir o eliminar los tags especificados.
• alias: Actualiza el atributo alias del dispositivo. Cuando el alias es una cadena vacía, se elimina el alias del dispositivo especificado.

Ejemplo de respuesta

Successful Response

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

            

Response Data

              
              success

            

Failed Response

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

            

Consultar la lista de tags

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

Endpoint

              
              GET /v4/tags/

            

Ejemplo de solicitud

Request Header

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

            

Request Parameters

• Ninguno

Ejemplo de respuesta

Successful Response

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

            

Response Data

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

            

• Si no se encuentra un elemento estadístico, será null; en caso contrario, será el valor del elemento estadístico.

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

• Consulta si un dispositivo está asociado a un tag.

Endpoint

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

            

Ejemplo de solicitud

Request Header

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

            

Request Parameters

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

Ejemplo de respuesta

Successful Response

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

            

Response Data

              
              {
  "result": true
}

            

Actualizar un tag

• Añade o elimina dispositivos de un tag.

Endpoint

              
              POST /v4/tags/{tag_value}

            

Ejemplo de solicitud

Request Header

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

            

Request Data

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

            

Request Parameters

• tag_value: Obligatorio. El tag que se va a consultar.
• action: Tipo de operación, con dos opciones: add y remove, que indican si esta solicitud añade o elimina dispositivos.
• registration_ids: Los valores registration_id del dispositivo que se van a añadir o eliminar.
• add/remove: Admite hasta 1.000 entradas en cada caso.

Ejemplo de respuesta

Successful Response

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

            

Response Data

              
              success

            

Failed Response

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

            

Eliminar un tag

Elimina un tag y la asociación entre el tag y los dispositivos.

Endpoint

              
              DELETE /v4/tags/{tag_value}

            

Ejemplo de solicitud

Request Header

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

            

Request Parameters

• tag_value: Obligatorio. El tag que se va a consultar.
• platform: Opcional. Si no se especifica, se utilizan todas las plataformas por defecto.

Ejemplo de respuesta

Successful Response

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

            

Response Data

              
              success

            

Failed Response

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

            

Consultar Alias (relación de vinculación con dispositivos)

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

            

Consultar Alias

• Obtiene los dispositivos asociados al alias especificado.

Endpoint

              
              GET /v4/aliases/{alias_value}

            

Ejemplo de solicitud

Request Header

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

            

Request Parameters

• alias_value: Obligatorio. El alias que se va a consultar.
• platform: Opcional. Si no se especifica, se utilizan todas las plataformas por defecto.

Ejemplo de respuesta

Successful Response

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

            

Response Data

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

            

• Si no se encuentra un elemento estadístico, será null; en caso contrario, será el valor del elemento estadístico.

Eliminar 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

Request Header

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

            

Request Parameters

• alias_value: Obligatorio. El alias que se va a eliminar.
• platform: Opcional. Si no se especifica, se utilizan todas las plataformas por defecto.

Ejemplo de respuesta

• Éxito

              
              success

            

• Error

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

            

Obtener el estado en línea del usuario

Endpoint

              
              POST /v4/devices/status/

            

Ejemplo de solicitud

Request Header

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

            

Request Data

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

            

Request Parameters

• registration_ids: Los valores registration_id del usuario cuyo estado en línea se desea consultar. Se admiten hasta 1.000 valores registration_id por consulta.
• Esta API solo puede llamarse para una AppKey que haya sido aprobada para esta función.

Ejemplo de respuesta

Successful Response

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

            

Response Data

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

            

Response Data

• 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.
• Los valores regid no válidos o los valores regid que no pertenecen a la AppKey no superarán la validación.

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

Consulta la información de cuota relacionada con la AppKey, la plataforma y el tag especificados. No se pueden consultar más de 1.000 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://pushapi-sgp.engagelab.com/v4/tags/quota-info?platform=android&tags=tag1&tags=tag2' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YjA2MTBmZGE0M2JmNmFkMTczNGNjMWY2OmQyNGMzZDk1Yzk1M2M3YmFkNzRkM2Q5YQ=='

            

Successful Response

              
              {
  "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 de dispositivos para un único tag.
• useUidQuota: Indica el número detallado de dispositivos vinculados a cada tag.

Failed Response

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

            

Códigos de estado HTTP

Documento de referencia: Http-Status-Code

Códigos de retorno de negocio