La implementación del servidor es opcional. Usa el servicio de ID de instancia si deseas realizar estas operaciones:
- Obtén información sobre las instancias de la app. Verifica los tokens de la app, o bien obtén más información sobre la instancia de la app que creó el token.
- Crea mapas de relaciones para instancias de apps. Crea relaciones entre las instancias de la app y las entidades como temas de FCM o GCM.
- Crea tokens de registro para tokens de APNS. Esta API te permite importar de forma masiva tokens existentes de APNS a fin de asignarlos a tokens de registro válidos para FCM o GCM.
- Administrar tokens de registro para suscripciones de envío En las aplicaciones web que se implementaron con la API de envío, importa tus suscripciones de envío existentes y asígnalas a tokens de registro válidos para FCM.
Obtén información sobre las instancias de la app
Para obtener información sobre una instancia de la app, llama al servicio de ID de instancia en este extremo y proporciona el token de la instancia de la app como se muestra a continuación:
https://iid.googleapis.com/iid/info/IID_TOKEN
Parámetros
Authorization
: clave=YOUR_API_KEY. Establece este parámetro en el encabezado.- [opcional] booleano
details
: configura este parámetro de consulta entrue
para obtener la información de suscripción a un tema de FCM o GCM (si existe) asociada con este token. Si no se especifica, el valor predeterminado esfalse
.
Resultados
Si se realiza correctamente, la llamada muestra el estado HTTP 200 y un objeto JSON que contiene lo siguiente:
application
: nombre del paquete asociado con el token.authorizedEntity
: El ID del proyecto está autorizado a enviar el token.applicationVersion
: Es la versión de la aplicación.appSigner
: huella digital desha1
para la firma aplicada al paquete. Indica qué parte firmó la app; por ejemplo,Play Store
.platform
: MuestraANDROID
,IOS
oCHROME
para indicar la plataforma del dispositivo a la que pertenece el token.
Si la marca details
está configurada, ocurre lo siguiente:
rel
: relaciones asociadas con el token Por ejemplo, una lista de suscripciones a temas.
Ejemplo de solicitud GET
https://iid.googleapis.com/iid/info/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA?Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
Resultado de ejemplo
HTTP 200 OK
{
"application":"com.iid.example",
"authorizedEntity":"123456782354",
"platform":"Android",
"appSigner":"1a2bc3d4e5"
"rel":{
"topics":{
"topicname1":{"addDate":"2015-07-30"},
"topicname2":{"addDate":"2015-07-30"},
"topicname3":{"addDate":"2015-07-30"},
"topicname4":{"addDate":"2015-07-30"}
}
}
}
Crea mapas de relaciones para instancias de apps
La API de Instance ID te permite crear mapas de relaciones para instancias de apps. Por ejemplo, puedes asignar un token de registro a un tema de Google Cloud Messaging y suscribir la instancia de la app al tema. La API proporciona métodos para crear esas relaciones de forma individual y masiva.
Crea una asignación de relación para una instancia de app
Con un token de registro y una relación admitida, puedes crear una asignación. Por ejemplo, para suscribir una instancia de app a un tema de Google Cloud Messaging, puedes llamar al servicio de ID de instancia en este extremo y proporcionar el token de la instancia de app como se muestra a continuación:
https://iid.googleapis.com/iid/v1/IID_TOKEN/rel/topics/TOPIC_NAME
Parámetros
Authorization
: clave=YOUR_API_KEY. Establece este parámetro en el encabezado.
Resultados
Si se ejecuta de forma correcta, la llamada muestra el estado HTTP 200.
Ejemplo de solicitud POST
https://iid.googleapis.com/iid/v1/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA/rel/topics/movies
Content-Type:application/json
Content-Length: 0
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
Resultado de ejemplo
HTTP 200 OK
{}
Administra las asignaciones de relaciones para varias instancias de app
Con los métodos por lotes del servicio de ID de instancia, puedes realizar la administración por lotes de las instancias de la app. Por ejemplo, puedes agregar o quitar de forma masiva instancias de apps a un tema de FCM o GCM. Para actualizar hasta 1, 000 instancias de app por llamada a la API, llama al servicio de ID de instancia en este extremo y proporciona los tokens de instancia de la app en el cuerpo JSON:
https://iid.googleapis.com/iid/v1:batchAdd
https://iid.googleapis.com/iid/v1:batchRemove
Parámetros
Authorization
: clave=YOUR_API_KEY. Establece este parámetro en el encabezado.to
: el nombre del tema.registration_tokens
: Es el arreglo de tokens de IID para las instancias de app que deseas agregar o quitar.
Resultados
Si se ejecuta de forma correcta, la llamada muestra el estado HTTP 200. Los resultados vacíos indican que la suscripción para el token se realizó correctamente. Para las suscripciones fallidas, el resultado contiene uno de estos códigos de error:
- NOT_FOUND — Se borró el token de registro o se desinstaló la aplicación.
- INVALID_ARGUMENT: El token de registro proporcionado no es válido para el ID de remitente.
- INTERNO: el servidor de backend falló por razones desconocidas. Reintenta la solicitud.
- TOO_MANY_TOPICS: cantidad excesiva de temas por instancia de app.
- RESOURCE_EXHAUSTED: demasiadas solicitudes de suscripción o anulación de suscripción en un período corto. Vuelve a intentarlo con una retirada exponencial.
Ejemplo de solicitud POST
https://iid.googleapis.com/iid/v1:batchAdd
Content-Type:application/json
Authorization:key=API_KEY
{
"to": "/topics/movies",
"registration_tokens": ["nKctODamlM4:CKrh_PC8kIb7O...", "1uoasi24:9jsjwuw...", "798aywu:cba420..."],
}
Resultado de ejemplo
HTTP 200 OK
{
"results":[
{},
{"error":"NOT_FOUND"},
{},
]
}
Crear tokens de registro para tokens de APNS
Con el método batchImport
del servicio de ID de instancia, puedes importar de forma masiva tokens existentes de APNS de iOS a Google Cloud Messaging o Firebase Cloud Messaging, y asignarlos a tokens de registro válidos. Llama al servicio de ID de instancia en este extremo y proporciona una lista de tokens de APNS en el cuerpo JSON:
https://iid.googleapis.com/iid/v1:batchImport
El cuerpo de la respuesta contiene una serie de tokens de registro de ID de instancia listos para usarse a fin de enviar mensajes de FCM o GCM al token de dispositivo de APNS correspondiente.
Parámetros
Authorization
: clave=YOUR_API_KEY. Establece este parámetro en el encabezado.application
: Es el ID del paquete de la app.sandbox
: booleano para indicar el entorno de la zona de pruebas (TRUE) o el de producción (FALSE).apns_tokens
: Es el array de tokens de APNS para las instancias de la app que quieres agregar o quitar. 100 tokens por solicitud como máximo.
Resultados
Si se ejecuta de forma correcta, la llamada muestra el estado HTTP 200 y un cuerpo de resultado JSON. Para cada token de APNS proporcionado en la solicitud, la lista de resultados incluye lo siguiente:
- El token de APNS.
- Estado. Es correcto o aparece un mensaje de error que describe el error.
- Para obtener resultados exitosos, indica el token de registro que FCM o GCM asignan al token de APNS.
Ejemplo de solicitud POST
https://iid.googleapis.com/iid/v1:batchImport
{
"application": "com.google.FCMTestApp",
"sandbox":false,
"apns_tokens":[
"368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12",
"76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86"
]
}
}
Resultado de ejemplo
HTTP 200 OK
{
"results":[
{
"apns_token": "368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12",
"status": "OK",
"registration_token":"nKctODamlM4:CKrh_PC8kIb7O...clJONHoA"
},
{
"apns_token": "76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86",
"status":"Internal Server Error"
},
]
}
Administra tokens de registro para suscripciones de envío
Con los métodos web del servicio de ID de instancia, puedes importar suscripciones de envío existentes para Firebase Cloud Messaging. También puedes actualizarlos y borrarlos.
Cuando importas una suscripción de envío, recibes un token de registro. Este token te permite usar funciones de FCM, como la mensajería por temas y la mensajería a grupos de dispositivos, para orientar las notificaciones a tus apps web.
Importar suscripciones de envío
Puedes importar suscripciones de envío mediante el extremo web de InstanceID:
https://iid.googleapis.com/v1/web/iid
La solicitud debe contener un encabezado de autorización establecido en un token de acceso OAuth 2.0, un encabezado de clave criptográfica configurado en tu clave del servidor de aplicaciones y el objeto PushSubscription
en el cuerpo de la solicitud.
El cuerpo de la respuesta contiene un token de registro listo para usar con el fin de enviar mensajes de FCM o GCM a la instancia de app web correspondiente sin tener que encriptar la carga útil.
Sube tu par de claves de VAPID a la consola
Para importar claves, debes tener acceso de nivel propietario al proyecto de Firebase. Importa tus claves públicas y privadas existentes en forma de una URL base64 con codificación segura:
- Abre la pestaña Cloud Messaging del panel Configuración de Firebase console y desplázate hasta la sección Configuración web.
- En la pestaña Certificados push web, encuentra y selecciona el texto del vínculo "cómo importar un par de claves existente".
- En el cuadro de diálogo Importar un par de claves, ingresa tus claves públicas y privadas en los campos correspondientes y haz clic en Importar. La consola muestra la string de la clave pública y la fecha en que se agregó.
Recuperar un token de OAuth2: usa credenciales para crear tokens de acceso
A fin de crear un token de acceso para la solicitud, debes crear el token de acceso y agregarlo a la solicitud HTTP.
Node.js
function getAccessToken() {
return admin.credential.applicationDefault().getAccessToken()
.then(accessToken => {
return accessToken.access_token;
})
.catch(err => {
console.error('Unable to get access token');
console.error(err);
});
}
Python
def _get_access_token():
"""Retrieve a valid access token that can be used to authorize requests.
:return: Access token.
"""
credentials = ServiceAccountCredentials.from_json_keyfile_name(
'service-account.json', SCOPES)
access_token_info = credentials.get_access_token()
return access_token_info.access_token
Java
private static String getAccessToken() throws IOException {
GoogleCredentials googleCredentials = GoogleCredentials
.fromStream(new FileInputStream("service-account.json"))
.createScoped(Arrays.asList(SCOPES));
googleCredentials.refreshAccessToken();
return googleCredentials.getAccessToken().getTokenValue();
}
Para autorizar el acceso a FCM, solicita el permiso https://www.googleapis.com/auth/firebase.messaging
.
Parámetros
- Autorización:
Bearer <access_token>
. Establece este parámetro en el encabezado. - Clave criptográfica:
p256ecdsa=APPLICATION_PUBLIC_KEY
. Establece este parámetro en el encabezado. - Cuerpo de la solicitud:
PushSubscription.toJson()
. Pasa la suscripción de envío al cuerpo HTTP sin analizarla. El contenido coincide con la codificación W3C dePushSubscription
.
Respuesta
Si se ejecuta de forma correcta, la llamada muestra el estado HTTP 200 OK y un cuerpo de resultado JSON que contiene el token IID.
Ejemplo de solicitud POST
https://iid.googleapis.com/v1/web/iid
Content-Type:application/json
Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
Crypto-Key:p256ecdsa=BFv5XHxdkZgpQzCb-...8uI42kf4A4USEIMo
{
"endpoint": "https://fcm.googleapis.com/fcm/send/dS4xerbSlqU:APb...aRs4QP",
"keys": {
"auth": "7cdY...xxjwz46Q",
"p256dh": "BH7xPjScJe...z9lbIZDmOV_c"
}
}
Resultado de ejemplo
HTTP 200 OK
{
"token":"KctODamlM4:CKrh_PC...cl"
}
Actualizar suscripciones de envío
Puedes actualizar la suscripción de envío asociada con el token de registro mediante el siguiente extremo:
https://iid.googleapis.com/v1/web/iid/REGISTRATION_TOKEN:refresh
Parámetros
- Autorización:
Bearer <access_token>
. Establece este parámetro en el encabezado. - Clave criptográfica:
p256ecdsa=APPLICATION_PUBLIC_KEY
. Establece este parámetro en el encabezado. - Cuerpo de la solicitud:
PushSubscription.toJson()
. Pasa la suscripción de envío al cuerpo HTTP sin analizarla. El contenido coincide con la codificación W3C dePushSubscription
.
Resultados
Si se ejecuta de forma correcta, la llamada muestra el estado HTTP 200 y un token de registro. Puede ser el mismo token que pasaste en la solicitud o uno nuevo.
HTTP 200 OK
{
"token":"KctODamlM4:CKrh_PC...cl"
}
Ejemplo de solicitud POST
https://iid.googleapis.com/v1/web/iid/KctODamlM4:CKrh_PC...cl:refresh
Content-Type:application/json
Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
Crypto-Key:p256ecdsa=BFv5XHxdkZgpQzCb-...8uI42kf4A4USEIMo
{
"endpoint": "https://fcm.googleapis.com/fcm/send/dS4xerbSlqU:APb...aRs4QP",
"keys": {
"auth": "7cdY...xxjwz46Q"",
"p256dh": "BH7xPjScJe...z9lbIZDmOV_c"
}
}
Resultado de ejemplo
HTTP 200 OK
{
"token":"KctODamlM4:CI2k_HHw...3P1"
}
Borrar suscripciones de envío
Una solicitud DELETE
quita los detalles de la suscripción de envío de la base de datos de FCM. Aún puedes recibir mensajes en tu aplicación web con el protocolo de la API de Push.
Para borrar una suscripción de envío, envía una solicitud DELETE
a:
https://iid.googleapis.com/v1/web/iid/REGISTRATION_TOKEN
Ejemplo de solicitud DELETE
https://iid.googleapis.com/v1/web/iid/KctODamlM4:CI2k_HHw...3P1
Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
Resultado de ejemplo
HTTP 200 OK {}
Respuestas de error
Las llamadas a la API del servidor de Instance ID muestran los siguientes códigos de error HTTP:
HTTP status 400 (Bad request)
: Los parámetros de solicitud faltan o no son válidos. Revisa los mensajes de error para obtener información detallada.HTTP status 401 (Unauthorized)
: El encabezado de autorización no es válido.HTTP status 403 (Forbidden)
: El encabezado de autorización no coincide conauthorizedEntity
.HTTP status 404 (Not found)
: no se encontró la ruta HTTP o el token IID no válido. Revisa los mensajes de error para obtener información detallada.HTTP status 503 (Service unavailable)
: El servicio no está disponible. Vuelve a intentar la solicitud con una retirada exponencial.