Controllare lo stato di registrazione dell'app con l'API Android Developer ID Status

Utilizza l'API Android Developer Status per verificare se il nome del pacchetto applicativo di un'app per Android è registrato da uno sviluppatore verificato. Se crei strumenti di sviluppo software, IDE o workflow CI/CD automatizzati, puoi integrare questa API server-to-server per eseguire le seguenti operazioni:

• Verificare se il nome del pacchetto applicativo di un'app è registrato da uno sviluppatore verificato
• Verificare se la fingerprint SHA-256 del certificato di firma di un'app corrisponde alle credenziali registrate per il nome del pacchetto registrato
• Chiedere agli sviluppatori nell'interfaccia dello strumento di registrare le app non riconosciute nel programma di verifica dello sviluppatore Android

Questa API è progettata per supportare vari workflow degli sviluppatori:

Questa guida spiega come completare le seguenti attività:

1. Configurare l'accesso e l'autenticazione dell'API Google Cloud.
2. Verificare se una coppia di nome del pacchetto e fingerprint SHA-256 del certificato pubblico di un'app è stata registrata nel programma di verifica dello sviluppatore Android da uno sviluppatore verificato, con la fingerprint SHA-256 del certificato pubblico fornita o con una fingerprint SHA-256 del certificato pubblico diversa.
3. Gestire gli stati di registrazione dell'API nel workflow dell'IDE o dello strumento per sviluppatori.

Prerequisiti

Questo documento è destinato agli sviluppatori di app per Android o di strumenti di sviluppo software. Prima di iniziare, devi avere:

• Accesso amministrativo a un progetto Google Cloud.
• Una conoscenza di base delle API RESTful, di JSON e delle fingerprint dei certificati SHA-256.

Dovresti anche conoscere i seguenti termini:

Endpoint di servizio

Un endpoint di servizio è un URL di base che specifica l'indirizzo di rete di un servizio API. Questo servizio ha il seguente endpoint di servizio e tutti gli URI sono relativi a questo endpoint di servizio:

https://androiddeveloperidstatus.googleapis.com

Abilita l'API

Per utilizzare l'API Android Developer ID Status, devi completare i passaggi di configurazione per creare un progetto e abilitare l'API.

Creare un progetto Google Cloud

1. Crea un account Google Cloud se non ne hai uno.
2. Apri la console Google Cloud.
3. Crea un progetto Google Cloud.

Abilitare l'API nel progetto

1. Nella console Google Cloud, vai ad API e servizi > Libreria.
2. Seleziona il progetto dal menu a discesa.
3. Cerca API Android Developer ID Status.
4. Fai clic su Attiva.

Autentica

L'API supporta le credenziali della chiave API. Per ottenere una chiave API:

1. Nella console Google Cloud, vai ad API e servizi > Credenziali.
2. Fai clic su + Crea credenziali e seleziona Chiave API.
3. Configura la chiave e copiala. Utilizza questa chiave nelle intestazioni delle richieste.

Controllare lo stato di registrazione dell'app

Puoi eseguire una query sulla risorsa PackageRegistrationStatus per verificare un solo nome di pacchetto o controllare un nome di pacchetto abbinato a una fingerprint del certificato specifica.

Controllare un nome di pacchetto

Per verificare se il nome del pacchetto applicativo di un'app è registrato da uno sviluppatore verificato, invia una richiesta GET autenticata contenente il nome del pacchetto applicativo dell'app per Android (ad esempio, com.example.app) all'endpoint packageRegistrationStatus:check senza parametri facoltativi:

Richiesta:

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

Risultati

Risposta (registrata):

Se il nome del pacchetto è registrato, riceverai il seguente corpo della risposta HTTP con il codice di risposta HTTP 200:

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

Azione consigliata: informa lo sviluppatore che il nome del pacchetto è già registrato.

Risposta (non registrata):

Se il nome del pacchetto non è registrato, riceverai il seguente corpo della risposta HTTP con il codice di risposta HTTP 200:

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

Verificare le coppie di nome del pacchetto e fingerprint del certificato

Per verificare se il nome del pacchetto applicativo di un'app è registrato con una fingerprint SHA-256 del certificato pubblico specifica, passa il parametro di query certificateFingerprint:

Richiesta:

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

Risultati

Risposta (registrata con fingerprint del certificato corrispondente):

Se il nome del pacchetto è registrato con la fingerprint SHA-256 del certificato pubblico fornita, riceverai il seguente corpo della risposta HTTP con il codice di risposta HTTP 200:

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

Risposta (registrata con una fingerprint del certificato diversa):

Se il nome del pacchetto è registrato con una fingerprint SHA-256 del certificato diversa da quella fornita, riceverai il seguente corpo della risposta HTTP con il codice di risposta HTTP 200:

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

Risposta (non registrata):

Se il nome del pacchetto non è registrato con la fingerprint SHA-256 del certificato pubblico fornita, riceverai il seguente corpo della risposta HTTP con il codice di risposta HTTP 200:

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

Esempio di implementazione Java

La seguente classe Java mostra come chiamare l'API utilizzando HttpClient standard di Java 11.

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 DeveloperIdStatusClient {

  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 = checkPackageRegistrationStatus(apiKey, packageName, certificateFingerprint);
      System.out.println("Response: " + response);
    } catch (IOException | InterruptedException e) {
      e.printStackTrace();
    }
  }

  /**
   *   Checks the registration status of an Android package.
   *
   *   @param apiKey The Google API key for authentication.
   *   @param packageName The fully-qualified Android package name (for example, "com.example.app").
   *   @param certificateFingerprint Optional SHA-256 certificate fingerprint. Pass null or empty to omit.
   *   @return The JSON response string from the API.
   */
  public static String checkPackageRegistrationStatus(
      String apiKey, String packageName, String certificateFingerprint)
      throws IOException, InterruptedException {

    // 1. Build the URL path (accepts dots directly)
    // Format: /v1/packages/{package}/packageRegistrationStatus:check
    String path = String.format("/v1/packages/%s/packageRegistrationStatus:check", packageName);

    // 2. Build query parameters (only certificateFingerprint if provided)
    StringBuilder queryBuilder = new StringBuilder();
    if (certificateFingerprint != null && !certificateFingerprint.isEmpty()) {
      queryBuilder.append("certificateFingerprint=")
          .append(URLEncoder.encode(certificateFingerprint, StandardCharsets.UTF_8));
    }

    String fullUrl = API_ENDPOINT + path;
    if (queryBuilder.length() > 0) {
      fullUrl += "?" + queryBuilder.toString();
    }

    // 3. Create and send the HTTP GET request with API Key header
    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();
  }
}

Comprendere gli stati di registrazione e la gestione degli errori

Quando una richiesta API non va a buon fine, l'API Android Developer ID Status restituisce un oggetto di errore JSON standard di Google Cloud nel corpo della risposta. Questo oggetto fornisce una struttura coerente per comprendere e gestire l'errore.

Esempio di risposta di errore:

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

L'oggetto di errore contiene i seguenti campi chiave:

• code: il codice di stato HTTP (ad esempio, 400, 403, 500).
• message: una descrizione dell'errore in inglese rivolta agli sviluppatori. Questo messaggio non è stabile e può cambiare, quindi non creare una logica di analisi basata su di esso.
• status: un codice di errore canonico che identifica a livello di programmazione il tipo di errore (ad esempio, INVALID_ARGUMENT, PERMISSION_DENIED). La logica di gestione degli errori deve essere basata su questo identificatore stabile.

La seguente tabella elenca gli errori più comuni restituiti dall'API e la procedura consigliata.

Limiti di quota

Le quote di utilizzo vengono applicate per progetto per garantire l'affidabilità del servizio.

Monitorare l'utilizzo

Puoi monitorare l'utilizzo attuale dell'API del tuo progetto e vedere quanto sei vicino ai limiti di quota direttamente nella console Google Cloud.

1. Vai alla pagina API e servizi > Dashboard.
2. Seleziona l'API Android Developer ID Status.
3. Fai clic sulla scheda Quote.

Questa dashboard fornisce una suddivisione dettagliata del volume delle richieste nel tempo.