Referência do servidor

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

 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 inscrição em tópicos do FCM (se houver) associadas a esse token. Quando não especificado, o padrão é false.

Resultados

Se a chamada for bem-sucedida, ela vai retornar o status HTTP 200 e um objeto JSON com:

  • 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 app

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 FCM, inscrevendo a instância do app no tópico. A API oferece métodos para criar essas relações individualmente e em massa.

Criar um mapeamento de relacionamento para uma instância de app

Com um token de registro e uma relação compatível, é possível criar um mapeamento. Por exemplo, é possível inscrever uma instância do app em um tópico do FCM chamando o serviço Instance ID neste ponto de extremidade e 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: 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 vai 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 Instance ID, é possível realizar o gerenciamento em lote de instâncias de apps. Por exemplo, é possível adicionar ou remover em massa instâncias de apps de um tópico do FCM. Para atualizar até 1.000 instâncias de app por chamada de API, chame o serviço Instance ID 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 do app que você quer adicionar ou remover.

Resultados

Se a chamada for bem-sucedida, ela vai retornar o status HTTP 200. Resultados vazios indicam uma inscrição 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 do app.
  • RESOURCE_EXHAUSTED: muitas solicitações de inscrição ou cancelamento de inscrição em um curto período. 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 da APNs

Usando o método batchImport do serviço ID da instância, é possível importar em massa tokens de APNs do iOS para o Firebase Cloud Messaging, atribuindo-os a tokens de registro válidos. Chame o serviço Instance ID neste endpoint, fornecendo uma lista de tokens do 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 no envio de mensagens do FCM ao token de dispositivo 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 sandbox (TRUE) ou de produção (FALSE)
  • apns_tokens : a matriz de tokens do APNs para as instâncias do app que você quer adicionar ou remover. Máximo de 100 tokens por solicitação.

Resultados

Se a chamada for bem-sucedida, ela vai retornar o status HTTP 200 e um corpo de resultado JSON. Para cada token do 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 mapeia para o 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 da 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 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 de novo com a espera exponencial.