Referência do servidor

A implementação do servidor é opcional. Use o serviço de ID 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 neste endpoint, fornecendo o token da instância do app, conforme mostrado abaixo:

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

Parâmetros

  • Authorization: Bearer <access_token>. Defina esse parâmetro no cabeçalho. Adicione um token OAuth2 de curta duração como o valor do cabeçalho Authorization. Para mais informações sobre como receber esse token, consulte Fornecer credenciais manualmente.
  • access_token_auth: true. 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 (se houver) associadas a esse token. Quando não especificado, o padrão é false.

Resultados

Se a chamada for bem-sucedida, ela 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.
  • platform - retorna ANDROID, IOS ou CHROME para indicar a plataforma do dispositivo a que o token pertence.

Se a flag 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
Content-Type:application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
access_token_auth: true

Exemplo de resultado

HTTP 200 OK
{
  "application":"com.iid.example",
  "authorizedEntity":"123456782354",
  "platform":"Android",
  "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 associar um token de registro a um tópico do FCM, 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

Dado 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 FCM chamando o serviço de ID da instância neste endpoint, fornecendo o token da instância do app, conforme mostrado abaixo:

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

Parâmetros

  • Authorization: Bearer <access_token>. Defina esse parâmetro no cabeçalho. Adicione um token OAuth2 de curta duração como o valor do cabeçalho Authorization. Para mais informações sobre como receber esse token, consulte Fornecer credenciais manualmente.
  • access_token_auth: true. Defina esse parâmetro no cabeçalho.

Resultados

Se a chamada for bem-sucedida, ela 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: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
access_token_auth: true

Exemplo de resultado

HTTP 200 OK
{}

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

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

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

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

Parâmetros

  • Authorization: Bearer <access_token>. Defina esse parâmetro no cabeçalho. Adicione um token OAuth2 de curta duração como o valor do cabeçalho Authorization. Para mais informações sobre como receber esse token, consulte Fornecer credenciais manualmente.
  • access_token_auth: true. Defina esse parâmetro no cabeçalho.
  • to : o nome do tópico.
  • registration_tokens : a matriz de tokens de IID para as instâncias de apps que você quer adicionar ou remover.

Resultados

Se a chamada for bem-sucedida, ela retornará o status HTTP 200. Resultados vazios indicam uma assinatura bem-sucedida para o 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 app foi desinstalado.
  • INVALID_ARGUMENT: o token de registro fornecido não é válido para o ID do remetente.
  • INTERNAL: o servidor de back-end falhou por motivos desconhecidos. Tente fazer a solicitação novamente.
  • TOO_MANY_TOPICS: número excessivo de tópicos por instância de app.
  • RESOURCE_EXHAUSTED: muitas solicitações de assinatura ou cancelamento de assinatura em um curto período de tempo. Tentar novamente com a espera exponencial.

Exemplo de solicitação POST

https://iid.googleapis.com/iid/v1:batchAdd
Content-Type:application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
access_token_auth: true
{
   "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 para o Firebase Cloud Messaging, associando-os a 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 da instância prontos para serem usados no envio de mensagens do FCM para o token de dispositivo de APNs correspondente.

Parâmetros

  • Authorization: Bearer <access_token>. Defina esse parâmetro no cabeçalho. Adicione um token OAuth2 de curta duração como o valor do cabeçalho Authorization. Para mais informações sobre como receber esse token, consulte Fornecer credenciais manualmente.
  • access_token_auth: true. Defina esse parâmetro no cabeçalho.
  • application : ID do pacote do app.
  • sandbox : booleano para indicar o ambiente de sandbox (TRUE) ou de 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

Se a chamada for bem-sucedida, ela retornará 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 resultados bem-sucedidos, o token de registro que o FCM associa ao token de APNs.

Exemplo de solicitação POST

https://iid.googleapis.com/iid/v1:batchImport
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
access_token_auth:true
{
  "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"
        },
     ]
  }

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 de solicitação estão ausentes ou são inválidos. Confira as mensagens de erro para 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 inválido ou token de IID não encontrado. Confira as mensagens de erro para informações detalhadas.
  • HTTP status 503 (Service unavailable): o serviço está indisponível. Tente fazer a solicitação novamente com a espera exponencial.