Referência do servidor

A implementação do servidor é opcional. Use o serviço ID da instância se quiser executar essas operações:

Receber informações sobre instâncias do app

Para receber informações sobre uma instância do app, chame o serviço de ID da instância neste endpoint, fornecendo o token da instância do app como mostrado:

 https://iid.googleapis.com/iid/info/IID_TOKEN

Parâmetros

  • Authorization: key=YOUR_API_KEY. Defina esse parâmetro no cabeçalho.
  • [opcional] booleano details: defina esse parâmetro de consulta como true para receber informações de assinatura de tópicos do FCM ou do GCM (se houver) associadas a esse token. Quando não é especificado, o padrão é false.

Resultados

Se for bem-sucedida, a chamada retornará o status HTTP 200 e um objeto JSON contendo:

  • application: nome do pacote associado ao token.
  • authorizedEntity: projectId autorizado a enviar para o token.
  • applicationVersion: versão do aplicativo.
  • appSigner: impressão digital do sha1 aplicada à assinatura do pacote. Indica qual parte assinou o app. Por exemplo,Play Store.
  • platform: retorna ANDROID, IOS ou CHROME para indicar a plataforma do dispositivo a que o token pertence.

Se a sinalização details estiver definida:

  • rel: relações associadas ao token. Por exemplo, uma lista de assinaturas de tópicos.

Exemplo de solicitação GET

https://iid.googleapis.com/iid/info/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA?Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

Exemplo de resultado

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"}
    }
  }
}

Criar mapas de relacionamento para instâncias de aplicativos

A API Instance ID permite criar mapas de relacionamento para instâncias de aplicativos. Por exemplo, é possível mapear um token de registro para um tópico do Google Cloud Messaging, assinando a instância do app para o tópico. A API oferece métodos para criar essas relações individualmente e em massa.

Criar um mapeamento de relação para uma instância do app

Com um token de registro e um relacionamento compatível, é possível criar um mapeamento. Por exemplo, é possível inscrever uma instância de app em um tópico do Google Cloud Messaging chamando o serviço de ID da instância nesse endpoint, fornecendo o token da instância do app como mostrado:

 https://iid.googleapis.com/iid/v1/IID_TOKEN/rel/topics/TOPIC_NAME

Parâmetros

  • Authorization: key=YOUR_API_KEY. Defina esse parâmetro no cabeçalho.

Resultados

Se for bem-sucedida, a chamada retornará o status HTTP 200.

Exemplo de solicitação 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

Exemplo de resultado

HTTP 200 OK
{}

Gerenciar mapas de relacionamento para várias instâncias de apps

Com o uso dos métodos de lote do serviço de ID da instância, é possível realizar o gerenciamento em lote de instâncias do aplicativo. Por exemplo, você pode adicionar ou remover instâncias de aplicativos em massa em um tópico do FCM ou do GCM. Para atualizar até 1.000 instâncias de app por chamada de API, chame o serviço de ID da instância neste endpoint, fornecendo os tokens da instância do app no corpo JSON:

 https://iid.googleapis.com/iid/v1:batchAdd

 https://iid.googleapis.com/iid/v1:batchRemove

Parâmetros

  • Authorization: key=YOUR_API_KEY. Defina esse parâmetro no cabeçalho.
  • to: o nome do tópico.
  • registration_tokens : a matriz de tokens IID das instâncias de apps que você quer adicionar ou remover.

Resultados

Se for bem-sucedida, a chamada retornará o status HTTP 200. Resultados vazios indicam a inscrição bem-sucedida do token. Para assinaturas com falha, o resultado contém um desses códigos de erro:

  • NOT_FOUND: o token de registro foi excluído ou o aplicativo foi desinstalado.
  • INVALID_ARGUMENT: o token de registro fornecido não é válido para o ID do remetente.
  • INTERNO — O servidor de back-end falhou por motivos desconhecidos. Tente fazer a solicitação novamente.
  • TOO_MANY_TOPICS: número excessivo de temas por instância do app.

Exemplo de solicitação 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..."],
}

Exemplo de resultado

HTTP 200 OK
{
  "results":[
    {},
    {"error":"NOT_FOUND"},
    {},
  ]
}

Criar tokens de registro para tokens de APNs

Usando o método batchImport do serviço do ID da instância, é possível importar em massa tokens de APNs do iOS existentes para o Google Cloud Messaging ou o Firebase Cloud Messaging, mapeando-os para tokens de registro válidos. Chame o serviço de ID da instância neste endpoint, fornecendo uma lista de tokens de APNs no corpo JSON:

 https://iid.googleapis.com/iid/v1:batchImport

O corpo da resposta contém uma matriz de tokens de registro de ID de instância prontos para serem usados para enviar mensagens do FCM ou do GCM para o token de dispositivo de APNs correspondente.

Parâmetros

  • Authorization: key=YOUR_API_KEY. Defina esse parâmetro no cabeçalho.
  • application : ID do pacote do aplicativo.
  • sandbox: booleano para indicar o ambiente de sandbox (TRUE) ou produção (FALSE)
  • apns_tokens: a matriz de tokens de APNs para as instâncias de aplicativos que você quer adicionar ou remover. Máximo de 100 tokens por solicitação.

Resultados

Se for bem-sucedida, a chamada retornará o status HTTP 200 e um corpo de resultado JSON. Para cada token de APNs que é fornecido na solicitação, a lista de resultados inclui:

  • O token de APNs.
  • Status. OK ou uma mensagem de erro que descreve a falha.
  • Para resultados bem-sucedidos, o token de registro que o FCM ou o GCM mapeia para o token de APNs.

Exemplo de solicitação POST

https://iid.googleapis.com/iid/v1:batchImport
{
  "application": "com.google.FCMTestApp",
  "sandbox":false,
  "apns_tokens":[
      "368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12",
      "76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86"
   ]
  }
}

Exemplo de resultado

HTTP 200 OK
{
 "results":[
       {
        "apns_token": "368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12",
         "status": "OK",
         "registration_token":"nKctODamlM4:CKrh_PC8kIb7O...clJONHoA"
       },
       {
         "apns_token": "76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86",
         "status":"Internal Server Error"
        },
     ]
  }

Gerenciar tokens de registro para assinaturas de push

Usando os métodos da Web do serviço do ID da instância, é possível importar assinaturas existentes para o Firebase Cloud Messaging. Também é possível atualizá-los e excluí-los.

Ao importar uma assinatura de push, você recebe um token de registro. Esse token permite usar recursos do FCM, como mensagens de tópicos e mensagens de grupos de dispositivos, para segmentar notificações para seus apps da Web.

Importar assinaturas de push

Você pode importar assinaturas de push usando o endpoint da Web do InstanceID'

 https://iid.googleapis.com/v1/web/iid

A solicitação precisa conter um cabeçalho de autorização definido como um token de acesso do OAuth 2.0, um cabeçalho de chave criptográfica definido como sua chave do servidor de aplicativos e o objeto PushSubscription no corpo da solicitação.

O corpo da resposta contém um token de registro pronto para ser usado para enviar mensagens do FCM ou do GCM para a instância correspondente do app da Web sem precisar criptografar o payload.

Fazer upload do par de chaves VAPID para o console

Para importar chaves, você precisa ter acesso de proprietário ao projeto do Firebase. Importe a chave pública e a particular existentes no formato codificado seguro de URL base64:

  1. Abra a guia Cloud Messaging do painel Configurações do Console do Firebase e vá até a seção Configuração da Web.
  2. Na guia Certificados de push da Web, encontre e selecione o texto do link e importe um par de chaves existente.
  3. Na caixa de diálogo Importar um par de chaves, forneça suas chaves pública e privada nos campos correspondentes e clique em Importar. O console exibe a string de chave pública e a data adicionada.

Recuperar um token OAuth2: usar credenciais para gerar tokens de acesso

Para criar um token de acesso para a solicitação, você precisará gerar o token de acesso e adicioná-lo à solicitação 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 o acesso ao FCM, solicite o escopo https://www.googleapis.com/auth/firebase.messaging.

Parâmetros

  • Autorização: Bearer <access_token>. Defina esse parâmetro no cabeçalho.
  • Chave criptográfica: p256ecdsa=APPLICATION_PUBLIC_KEY. Defina esse parâmetro no cabeçalho.
  • Corpo da solicitação: PushSubscription.toJson(). Transmita a assinatura de push para o corpo HTTP sem analisá-la. O conteúdo corresponde à codificação W3C de PushSubscription.

Resposta

Se for bem-sucedida, a chamada retornará o status HTTP 200 OK e um corpo de resultado JSON contendo o token IID.

Exemplo de solicitação 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"
    }
 }

Exemplo de resultado

HTTP 200 OK
{
 "token":"KctODamlM4:CKrh_PC...cl"
}

Atualizar assinaturas de push

É possível atualizar a assinatura de push associada ao token de registro usando o seguinte endpoint:

 https://iid.googleapis.com/v1/web/iid/REGISTRATION_TOKEN:refresh

Parâmetros

  • Autorização: Bearer <access_token>. Defina esse parâmetro no cabeçalho.
  • Chave criptográfica: p256ecdsa=APPLICATION_PUBLIC_KEY. Defina esse parâmetro no cabeçalho.
  • Corpo da solicitação: PushSubscription.toJson(). Transmita a assinatura de push para o corpo HTTP sem analisá-la. O conteúdo corresponde à codificação W3C de PushSubscription.

Resultados

Se for bem-sucedida, a chamada retornará o status HTTP 200 e um token de registro. Pode ser o mesmo token transmitido na solicitação ou um novo token.

HTTP 200 OK
{
 "token":"KctODamlM4:CKrh_PC...cl"
}

Exemplo de solicitação 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"
    }
 }

Exemplo de resultado

 HTTP 200 OK
 {
  "token":"KctODamlM4:CI2k_HHw...3P1"
 }

Excluir assinaturas de push

Uma solicitação DELETE remove os detalhes da assinatura de push do banco de dados do FCM. Você ainda pode receber mensagens no seu aplicativo da Web usando o protocolo da API Push.

Para excluir uma assinatura push, envie uma solicitação DELETE para:

 https://iid.googleapis.com/v1/web/iid/REGISTRATION_TOKEN

Exemplo de solicitação DELETE

 https://iid.googleapis.com/v1/web/iid/KctODamlM4:CI2k_HHw...3P1
 Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

Exemplo de resultado

 HTTP 200 OK {}

Respostas de erro

As chamadas para a API do servidor de ID da instância retornam os seguintes códigos de erro HTTP:

  • HTTP status 400 (Bad request): os parâmetros da solicitação estão ausentes ou são inválidos. Verifique as mensagens de erro para ver informações detalhadas.
  • HTTP status 401 (Unauthorized): o cabeçalho de autorização é inválido.
  • HTTP status 403 (Forbidden): o cabeçalho de autorização não corresponde ao authorizedEntity.
  • HTTP status 404 (Not found): caminho HTTP ou token IID inválido não encontrado. Verifique as mensagens de erro para ver informações detalhadas.
  • HTTP status 503 (Service unavailable): o serviço não está disponível. Tente fazer a solicitação novamente com espera exponencial.