Referência do servidor

A implementação do servidor é opcional. Use o serviço de código da instância se quiser realizar estas operações:

Receber informações sobre instâncias de apps

Para receber informações sobre uma instância de app, chame o serviço de ID da instância nesse endpoint fornecendo o token da instância do app, conforme 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ópico do FCM ou GCM (se houver) associadas a esse token. Quando não especificado, o padrão é false.

Resultados

Se a chamada 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 sha1 da assinatura aplicada ao 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 apps

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

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

Com um token de registro e um relacionamento compatível, é possível criar um mapeamento. Por exemplo, você pode assinar 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, conforme 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 app

Com os métodos em lote do serviço de código de instância, é possível executar o gerenciamento em lote de instâncias de aplicativos. Por exemplo, é possível adicionar ou remover instâncias de apps em massa para um tópico do FCM ou do GCM. Para atualizar até 1.000 instâncias de apps por chamada de API, chame o serviço de código de instância nesse endpoint, fornecendo os tokens de instância do app no corpo do 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 uma assinatura bem-sucedida do token. Para assinaturas com falha, o resultado contém um destes 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 de remetente.
  • INTERNO - O servidor de back-end falhou por razões desconhecidas. Tente fazer a solicitação novamente.
  • TOO_MANY_TOPICS: número excessivo de tópicos por instância do aplicativo.
  • RESOURCE_EXHAUSTED: excesso de solicitações de assinatura ou cancelamento de assinatura em um curto período. Tente novamente com espera exponencial.

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 de 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 nesse 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 FCM ou 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 app.
  • sandbox : booleano para indicar o ambiente de sandbox (TRUE) ou a produção (FALSE).
  • apns_tokens : a matriz de tokens de APNs para as instâncias de apps que você quer adicionar ou remover. Máximo de 100 tokens por solicitação.

Resultados

Em caso de sucesso, a chamada retorna o status HTTP 200 e um corpo de resultado JSON. Para cada token de APNs fornecido na solicitação, a lista de resultados inclui:

  • O token de APNs.
  • Status. OK ou uma mensagem de erro descrevendo a falha.
  • Para obter 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

Com os métodos da Web do serviço de código de instância, é possível importar assinaturas de push 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

É possível 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 FCM ou GCM à instância do app da Web correspondente sem precisar criptografar o payload.

Fazer upload do par de chaves VAPID no console

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

  1. Abra a guia Cloud Messaging do painel Configurações do Console do Firebase e role até a seção Configuração da Web.
  2. Na guia Certificados de push da Web, localize e selecione o texto do link "Importar um par de chaves existente".
  3. Na caixa de diálogo Importar um par de chaves, insira suas chaves públicas e privadas 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 produzir tokens de acesso

Para criar um token de acesso para a solicitação, será necessário produzir 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);
      });
}
index.js

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
configure.py

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();
}
Configure.java

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

Em caso de sucesso, a chamada retorna 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 Push API.

Para excluir uma assinatura de 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 Instance ID Server 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 está indisponível. Tente fazer a solicitação novamente com espera exponencial.