Verificar o status do registro do app com a API Android Developer ID Status

Use a API Android Developer Status para verificar se o nome do pacote de um app Android está registrado em um desenvolvedor verificado. Se você cria ferramentas de desenvolvimento de software, IDEs ou fluxos de trabalho automatizados de CI/CD, pode integrar essa API de servidor para servidor para fazer o seguinte:

• Verificar se o nome do pacote de um app está registrado em um desenvolvedor verificado
• Validar se a impressão digital SHA-256 do certificado de assinatura de um app corresponde às credenciais registradas para o nome do pacote
• Solicitar que os desenvolvedores na interface da sua ferramenta registrem apps não reconhecidos no programa de verificação de desenvolvedor Android

Essa API foi projetada para oferecer suporte a vários fluxos de trabalho de desenvolvedores:

Este guia explica como concluir as seguintes tarefas:

1. Configurar o acesso e a autenticação da API Google Cloud.
2. Verificar se o nome do pacote e o par de impressão digital do certificado público SHA-256 de um app foram registrados no programa de verificação de desenvolvedor Android por um desenvolvedor verificado, com a impressão digital do certificado público SHA-256 fornecida ou uma impressão digital diferente.
3. Processar estados de registro de API no fluxo de trabalho da sua ferramenta de desenvolvimento ou IDE.

Pré-requisitos

Este documento é destinado a desenvolvedores de apps Android ou de ferramentas de desenvolvimento de software. Antes de começar, você precisa ter:

• Acesso administrativo a um projeto do Google Cloud.
• Noções básicas sobre APIs RESTful, JSON e impressões digitais de certificado SHA-256.

Você também precisa conhecer estes termos:

Endpoint de serviço

Um endpoint de serviço é um URL de base que especifica o endereço de rede de um serviço de API. Esse serviço tem o endpoint a seguir e todos os URIs são relativos a ele:

https://androiddeveloperidstatus.googleapis.com

Ativar a API

Para usar a API Android Developer ID Status, conclua as etapas de configuração para criar um projeto e ativar a API.

Criar um projeto do Google Cloud

1. Crie uma conta do Google Cloud se você não tiver uma.
2. Abra o Console do Google Cloud.
3. Crie um projeto do Google Cloud.

Ativar a API no seu projeto

1. No Console do Google Cloud, acesse APIs e serviços > Biblioteca.
2. Selecione seu projeto no menu suspenso.
3. Pesquise API Android Developer ID Status.
4. Clique em Ativar.

Autenticar

A API oferece suporte a credenciais de chave de API. Para gerar uma chave de API:

1. No Console do Google Cloud, acesse APIs e serviços > Credenciais.
2. Clique em + Criar credenciais e selecione Chave de API.
3. Configure a chave e copie-a. Use essa chave nos cabeçalhos de solicitação.

Verificar o status de registro do app

Você pode consultar o recurso PackageRegistrationStatus para verificar apenas um nome de pacote ou um nome de pacote pareado com uma impressão digital do certificado específica.

Verificar um nome de pacote

Para verificar se o nome do pacote de um app está registrado em um desenvolvedor verificado, faça uma solicitação GET autenticada que contenha o nome do pacote do app Android (por exemplo, com.example.app) para o endpoint packageRegistrationStatus:check sem parâmetros opcionais:

Solicitação:

curl -X GET "https://androiddeveloperidstatus.googleapis.com/v1/packages/com.example.app/packageRegistrationStatus:check" \
  -H "X-Goog-Api-Key: [key]"

Resultados

Resposta (registrado):

Se o nome do pacote estiver registrado, você vai receber o seguinte corpo de resposta HTTP com o código de resposta HTTP 200:

{
  "name": "packages/com.example.app/packageRegistrationStatus",
  "state": "REGISTERED"
}

Ação recomendada: se você estiver realizando essa verificação em nome de outro desenvolvedor, informe que o nome do pacote está registrado.

Resposta (não registrado):

Se o nome do pacote não estiver registrado, você vai receber o seguinte corpo de resposta HTTP com o código de resposta HTTP 200:

{
  "name": "packages/com.example.app/packageRegistrationStatus",
  "state": "NOT_REGISTERED"
}

Ação recomendada: se você estiver realizando essa verificação em nome de outro desenvolvedor, informe que o nome do pacote não está registrado.

Exemplo do Java

Este exemplo do Java chama a API sem parâmetros de consulta para verificar se o nome do pacote está registrado.

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class CheckPackageNameClient {

  private static final String API_ENDPOINT = "https://androiddeveloperidstatus.googleapis.com";

  public static void main(String[] args) {
    String apiKey = "YOUR_API_KEY";
    String packageName = "com.example.app";

    try {
      String response = checkPackageRegistrationStatus(apiKey, packageName);
      System.out.println("Response: " + response);
    } catch (IOException | InterruptedException e) {
      e.printStackTrace();
    }
  }

  /**
   *   Checks the registration status of an Android package.
   */
  public static String checkPackageRegistrationStatus(String apiKey, String packageName)
      throws IOException, InterruptedException {

    String fullUrl = String.format("%s/v1/packages/%s/packageRegistrationStatus:check", API_ENDPOINT, packageName);

    HttpClient client = HttpClient.newHttpClient();
    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(fullUrl))
        .header("Accept", "application/json")
        .header("X-Goog-Api-Key", apiKey)
        .GET()
        .build();

    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

    if (response.statusCode() != 200) {
      throw new IOException("Unexpected response code: " + response.statusCode() + ", body: " + response.body());
    }

    return response.body();
  }
}

Verificar pares de nome de pacote e impressão digital do certificado

Para verificar se o nome do pacote de um app está registrado com uma impressão digital de certificado público SHA-256 específica, transmita o parâmetro de consulta certificateFingerprint:

Solicitação:

curl -X GET "https://androiddeveloperidstatus.googleapis.com/v1/packages/com.example.app/packageRegistrationStatus:check?certificateFingerprint=d6ac89ed1d0a805aad4b087d06d5f41645b814480b133fbc867ef7498d069e06" \
  -H "X-Goog-Api-Key: [key]"

Resultados

Resposta (registrado com impressão digital de certificado correspondente):

Se o nome do pacote estiver registrado com a impressão digital do certificado público SHA-256 fornecida, você vai receber o seguinte corpo de resposta HTTP com o código de resposta HTTP 200:

{
  "name": "packages/com.example.app/packageRegistrationStatus",
  "state": "REGISTERED"
}

Ação recomendada: se você estiver realizando essa verificação em nome de outro desenvolvedor, informe que o nome do pacote está registrado com a impressão digital do certificado fornecida.

Resposta (registrado com impressão digital de certificado diferente):

Se o nome do pacote estiver registrado com uma impressão digital de certificado SHA-256 diferente da fornecida, você vai receber o seguinte corpo de resposta HTTP com o código de resposta HTTP 200:

{
  "name": "packages/com.example.app/packageRegistrationStatus",
  "state": "REGISTERED_WITH_ANOTHER_CERTIFICATE_FINGERPRINT"
}

Ação recomendada: se você estiver realizando essa verificação em nome de outro desenvolvedor, informe que o nome do pacote está registrado, mas com uma impressão digital do certificado diferente da fornecida.

Resposta (não registrado):

Se o nome do pacote não estiver registrado com a impressão digital do certificado público SHA-256 fornecida, você vai receber o seguinte corpo de resposta HTTP com o código de resposta HTTP 200:

{
  "name": "packages/com.example.app/packageRegistrationStatus",
  "state": "NOT_REGISTERED"
}

Ação recomendada: se você estiver realizando essa verificação em nome de outro desenvolvedor, informe que o nome do pacote não está registrado com a impressão digital do certificado fornecida.

Exemplo do Java

Este exemplo do Java inclui explicitamente a certificateFingerprint como um parâmetro de consulta codificado por URL para verificar um pacote e um pareamento de impressão digital específicos.

import java.io.IOException;
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;

public class CheckPackageAndFingerprintClient {

  private static final String API_ENDPOINT = "https://androiddeveloperidstatus.googleapis.com";

  public static void main(String[] args) {
    String apiKey = "YOUR_API_KEY";
    String packageName = "com.example.app";
    String certificateFingerprint = "d6ac89ed1d0a805aad4b087d06d5f41645b814480b133fbc867ef7498d069e06";

    try {
      String response = checkPackageAndFingerprintRegistrationStatus(apiKey, packageName, certificateFingerprint);
      System.out.println("Response: " + response);
    } catch (IOException | InterruptedException e) {
      e.printStackTrace();
    }
  }

  /**
   *   Checks the registration status of a specific Android package and certificate fingerprint pair.
   */
  public static String checkPackageAndFingerprintRegistrationStatus(
      String apiKey, String packageName, String certificateFingerprint)
      throws IOException, InterruptedException {

    String path = String.format("/v1/packages/%s/packageRegistrationStatus:check", packageName);

    String encodedFingerprint = URLEncoder.encode(certificateFingerprint, StandardCharsets.UTF_8);
    String fullUrl = API_ENDPOINT + path + "?certificateFingerprint=" + encodedFingerprint;

    HttpClient client = HttpClient.newHttpClient();
    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(fullUrl))
        .header("Accept", "application/json")
        .header("X-Goog-Api-Key", apiKey)
        .GET()
        .build();

    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

    if (response.statusCode() != 200) {
      throw new IOException("Unexpected response code: " + response.statusCode() + ", body: " + response.body());
    }

    return response.body();
  }
}

Entender os estados de registro e o tratamento de erros

Quando uma solicitação de API falha, a API Android Developer ID Status retorna um objeto de erro JSON padrão do Google Cloud no corpo da resposta. Esse objeto fornece uma estrutura consistente para entender e processar o erro.

Exemplo de resposta de erro:

{
  "error": {
    "code": 400,
    "message": "Request contains an invalid argument.",
    "status": "INVALID_ARGUMENT"
  }
}

O objeto de erro contém os seguintes campos de chave:

• code: o código de status HTTP (por exemplo, 400, 403, 500).
• message: uma descrição do erro em inglês para desenvolvedores. Essa mensagem não é estável e pode mudar. Portanto, não crie uma lógica de análise com base nela.
• status: um código de erro canônico que identifica programaticamente o tipo de erro (por exemplo, INVALID_ARGUMENT, PERMISSION_DENIED). A lógica de tratamento de erros precisa ser criada com base nesse identificador estável.

A tabela a seguir lista os erros mais comuns retornados pela API e o curso de ação recomendado.

Limites de cotas

As cotas de uso são aplicadas por projeto para garantir a confiabilidade do serviço.

Monitorar seu uso

É possível monitorar o uso atual da API do seu projeto e verificar a proximidade dos limites de cota diretamente no Console do Google Cloud.

1. Acesse a página APIs e serviços > Painel.
2. Selecione a API Android Developer ID Status.
3. Clique na guia Cotas.

Esse painel fornece um detalhamento detalhado do volume de solicitações ao longo do tempo.