App-Links überprüfen

Wenn android:autoVerify="true" in mindestens einem Intent-Filter Ihrer App vorhanden ist, wird beim Installieren Ihrer App auf einem Gerät mit Android 6.0 (API-Level 23) oder höher automatisch überprüft, ob die Hosts mit den URLs in den Intent-Filtern Ihrer App verknüpft sind. Unter Android 12 und höher können Sie das Bestätigungsverfahren auch manuell aufrufen, um die Bestätigungslogik zu testen.

Automatische Bestätigung

Die automatische Überprüfung des Systems umfasst Folgendes:

  1. Das System prüft alle Intent-Filter, die Folgendes enthalten:
    • Aktion: android.intent.action.VIEW
    • Kategorien: android.intent.category.BROWSABLE und android.intent.category.DEFAULT
    • Datenschema: http oder https
  2. Für jeden eindeutigen Hostnamen, der in den oben genannten Intent-Filtern gefunden wird, fragt Android die entsprechenden Websites nach der Digital Asset Links-Datei unter https:///.well-known/assetlinks.json ab.

Nachdem Sie die Liste der Websites bestätigt haben, die mit Ihrer App verknüpft werden sollen, und die gehostete JSON-Datei gültig ist, installieren Sie die App auf Ihrem Gerät. Warten Sie mindestens 20 Sekunden, bis die asynchrone Bestätigung abgeschlossen ist. Mit dem folgenden Befehl können Sie prüfen, ob das System Ihre App überprüft und die richtigen Richtlinien für die Linkverarbeitung festgelegt hat:

adb shell am start -a android.intent.action.VIEW \
    -c android.intent.category.BROWSABLE \
    -d "http://domain.name:optional_port"

Manuelle Bestätigung

Ab Android 12 können Sie die Domainbestätigung für eine App, die auf einem Gerät installiert ist, manuell aufrufen. Sie können diesen Vorgang unabhängig davon ausführen, ob Ihre App auf Android 12 ausgerichtet ist.

Internetverbindung herstellen

Für die Domainbestätigung muss Ihr Testgerät mit dem Internet verbunden sein.

Unterstützung des aktualisierten Domainbestätigungsprozesses

Wenn Ihre App auf Android 12 oder höher ausgerichtet ist, verwendet das System automatisch das aktualisierte Verfahren zur Domainbestätigung.

Andernfalls können Sie das aktualisierte Bestätigungsverfahren manuell aktivieren. Führen Sie dazu den folgenden Befehl in einem Terminalfenster aus:

adb shell am compat enable 175408749 PACKAGE_NAME

Status von Android-App-Links auf einem Gerät zurücksetzen

Bevor Sie die Domainbestätigung auf einem Gerät manuell aufrufen, müssen Sie den Status von Android-App-Links auf dem Testgerät zurücksetzen. Führen Sie dazu den folgenden Befehl in einem Terminalfenster aus:

adb shell pm set-app-links --package PACKAGE_NAME 0 all

Mit diesem Befehl wird das Gerät in den Zustand zurückversetzt, in dem es sich befindet, bevor der Nutzer Standard-Apps für Domains auswählt.

Domainbestätigungsprozess aufrufen

Nachdem Sie den Status von Android-App-Links auf einem Gerät zurückgesetzt haben, können Sie die Bestätigung selbst durchführen. Führen Sie dazu den folgenden Befehl in einem Terminalfenster aus:

adb shell pm verify-app-links --re-verify PACKAGE_NAME

Bestätigungsergebnisse prüfen

Nachdem der Bestätigungs-Agent einige Zeit hatte, seine Anfragen abzuschließen, können Sie die Bestätigungsergebnisse überprüfen. Führen Sie dazu den folgenden Befehl aus:

adb shell pm get-app-links PACKAGE_NAME

Die Ausgabe dieses Befehls sieht so aus:

com.example.pkg:
    ID: 01234567-89ab-cdef-0123-456789abcdef
    Signatures: [***]
    Domain verification state:
      example.com: verified
      sub.example.com: legacy_failure
      example.net: verified
      example.org: 1026

Domains, die die Bestätigung bestehen, haben den Status verified. Jeder andere Status weist darauf hin, dass die Domainbestätigung nicht durchgeführt werden konnte. Insbesondere der Status none gibt an, dass der Bestätigungsbeauftragte den Bestätigungsprozess möglicherweise noch nicht abgeschlossen hat.

In der folgenden Liste sind die möglichen Rückgabewerte aufgeführt, die bei der Domainbestätigung für eine bestimmte Domain zurückgegeben werden können:

none
Für diese Domain wurden keine Daten aufgezeichnet. Warten Sie einige Minuten, bis der Bestätigungs-Agent die Anfragen zur Domainbestätigung abgeschlossen hat, und rufen Sie den Domainbestätigungsprozess noch einmal auf.
verified
Die Domain wurde für die deklarierende App bestätigt.
approved
Die Domain wurde zwangsweise genehmigt, in der Regel durch Ausführen eines Shell-Befehls.
denied
Die Domain wurde zwangsweise abgelehnt, in der Regel durch Ausführen eines Shell-Befehls.
migrated
Das System hat das Ergebnis eines früheren Prozesses beibehalten, bei dem die alte Domainüberprüfung verwendet wurde.
restored
Die Domain wurde genehmigt, nachdem der Nutzer eine Datenwiederherstellung durchgeführt hat. Es wird davon ausgegangen, dass die Domain bereits bestätigt wurde.
legacy_failure
Die Domain wurde von einem Legacy-Bestätiger abgelehnt. Der genaue Grund für den Fehler ist unbekannt.
system_configured
Die Domain wurde automatisch durch die Gerätekonfiguration genehmigt.
Fehlercode von 1024 oder höher

Benutzerdefinierter Fehlercode, der für den Prüfer des Geräts spezifisch ist.

Prüfen Sie, ob Sie eine Netzwerkverbindung hergestellt haben, und rufen Sie den Domainbestätigungsprozess noch einmal auf.

Nutzer auffordern, Ihre App mit einer Domain zu verknüpfen

Eine weitere Möglichkeit, die Genehmigung für eine Domain zu erhalten, besteht darin, den Nutzer zu bitten, Ihre App mit dieser Domain zu verknüpfen.

Prüfen, ob Ihre App bereits für die Domain genehmigt wurde

Bevor Sie den Nutzer auffordern, prüfen Sie, ob Ihre App der Standard-Handler für die Domains ist, die Sie in Ihren <intent-filter>-Elementen definieren. Sie können den Genehmigungsstatus mit einer der folgenden Methoden abfragen:

DomainVerificationManager

Das folgende Code-Snippet zeigt, wie die DomainVerificationManager API verwendet wird:

Kotlin

val context: Context = TODO("Your activity or fragment's Context")
val manager = context.getSystemService(DomainVerificationManager::class.java)
val userState = manager.getDomainVerificationUserState(context.packageName)

// Domains that have passed Android App Links verification.
val verifiedDomains = userState?.hostToStateMap
    ?.filterValues { it == DomainVerificationUserState.DOMAIN_STATE_VERIFIED }

// Domains that haven't passed Android App Links verification but that the user
// has associated with an app.
val selectedDomains = userState?.hostToStateMap
    ?.filterValues { it == DomainVerificationUserState.DOMAIN_STATE_SELECTED }

// All other domains.
val unapprovedDomains = userState?.hostToStateMap
    ?.filterValues { it == DomainVerificationUserState.DOMAIN_STATE_NONE }

Java

Context context = TODO("Your activity or fragment's Context");
DomainVerificationManager manager =
        context.getSystemService(DomainVerificationManager.class);
DomainVerificationUserState userState =
        manager.getDomainVerificationUserState(context.getPackageName());

Map<String, Integer> hostToStateMap = userState.getHostToStateMap();
List<String> verifiedDomains = new ArrayList<>();
List<String> selectedDomains = new ArrayList<>();
List<String> unapprovedDomains = new ArrayList<>();
for (String key : hostToStateMap.keySet()) {
    Integer stateValue = hostToStateMap.get(key);
    if (stateValue == DomainVerificationUserState.DOMAIN_STATE_VERIFIED) {
        // Domain has passed Android App Links verification.
        verifiedDomains.add(key);
    } else if (stateValue == DomainVerificationUserState.DOMAIN_STATE_SELECTED) {
        // Domain hasn't passed Android App Links verification, but the user has
        // associated it with an app.
        selectedDomains.add(key);
    } else {
        // All other domains.
        unapprovedDomains.add(key);
    }
}

Befehlszeilenprogramm

Wenn Sie Ihre App während der Entwicklung testen, können Sie mit dem folgenden Befehl den Bestätigungsstatus der Domains abfragen, die Ihrer Organisation gehören:

adb shell pm get-app-links --user cur PACKAGE_NAME

Im folgenden Beispiel wurde die App zwar nicht für die Domain „example.org“ bestätigt, Nutzer 0 hat die App aber manuell in den Systemeinstellungen genehmigt und kein anderes Paket ist für diese Domain bestätigt.

com.example.pkg:
ID: ***
Signatures: [***]
Domain verification state:
  example.com: verified
  example.net: verified
  example.org: 1026
User 0:
  Verification link handling allowed: true
  Selection state:
    Enabled:
      example.org
    Disabled:
      example.com
      example.net

Sie können auch Shell-Befehle verwenden, um den Prozess zu simulieren, bei dem der Nutzer auswählt, welche App mit einer bestimmten Domain verknüpft ist. Eine vollständige Beschreibung dieser Befehle finden Sie in der Ausgabe von adb shell pm.

Kontext für die Anfrage angeben

Bevor Sie diese Anfrage zur Domaingenehmigung stellen, sollten Sie dem Nutzer etwas Kontext geben. Sie können Nutzern beispielsweise einen Splash-Screen, ein Dialogfeld oder ein ähnliches UI-Element anzeigen, in dem erklärt wird, warum Ihre App der Standard-Handler für eine bestimmte Domain sein sollte.

Anfrage stellen

Nachdem der Nutzer verstanden hat, was Ihre App von ihm verlangt, stellen Sie die Anfrage. Rufen Sie dazu ein Intent auf, das die Intent-Aktion ACTION_APP_OPEN_BY_DEFAULT_SETTINGS und einen Datenstring enthält, der package:com.example.pkg für die Ziel-App entspricht, wie im folgenden Code-Snippet gezeigt:

Kotlin

val context: Context = TODO("Your activity or fragment's Context")
val intent = Intent(Settings.ACTION_APP_OPEN_BY_DEFAULT_SETTINGS,
    Uri.parse("package:${context.packageName}"))
context.startActivity(intent)

Java

Context context = TODO("Your activity or fragment's Context");
Intent intent = new Intent(Settings.ACTION_APP_OPEN_BY_DEFAULT_SETTINGS,
    Uri.parse("package:" + context.getPackageName()));
context.startActivity(intent);

Wenn der Intent aufgerufen wird, sehen Nutzer einen Einstellungsbildschirm mit dem Namen Standardmäßig öffnen. Dieser Bildschirm enthält ein Optionsfeld mit dem Namen Unterstützte Links öffnen (siehe Abbildung 1).

Wenn der Nutzer Unterstützte Links öffnen aktiviert, wird unter dem Abschnitt In dieser App zu öffnende Links eine Reihe von Kästchen angezeigt. Dort können Nutzer die Domains auswählen, die sie mit Ihrer App verknüpfen möchten. Sie können auch Link hinzufügen auswählen, um Domains hinzuzufügen (siehe Abbildung 2). Wenn Nutzer später einen Link in den von ihnen hinzugefügten Domains auswählen, wird der Link automatisch in Ihrer App geöffnet.

Wenn das Optionsfeld aktiviert ist, enthält ein Bereich unten auf der Seite Kästchen sowie die Schaltfläche „Link hinzufügen“.
Abbildung 1. Systemeinstellungen, in denen Nutzer auswählen können, welche Links standardmäßig in Ihrer App geöffnet werden.
Jedes Kästchen steht für eine Domain, die Sie hinzufügen können. Die Schaltflächen im Dialogfeld sind „Abbrechen“ und „Hinzufügen“.
Abbildung 2. Dialogfeld, in dem Nutzer zusätzliche Domains auswählen können, die mit Ihrer App verknüpft werden sollen.

Domains in Ihrer App öffnen, die nicht bestätigt werden können

Die Hauptfunktion Ihrer App besteht möglicherweise darin, Links als Drittanbieter zu öffnen, ohne dass die Möglichkeit besteht, die verarbeiteten Domains zu bestätigen. Wenn dies der Fall ist, erklären Sie den Nutzern, dass sie zu diesem Zeitpunkt, wenn sie einen Weblink auswählen, nicht zwischen einer selbst entwickelten App und Ihrer (Drittanbieter-)App wählen können. Nutzer müssen die Domains manuell mit Ihrer Drittanbieter-App verknüpfen.

Außerdem sollten Sie ein Dialogfeld oder eine Trampolinaktivität einführen, über die der Nutzer den Link in der Erstanbieter-App öffnen kann, wenn er dies bevorzugt. Bevor Sie einen solchen Dialog oder eine Trampolin-Aktivität einrichten, müssen Sie Ihre App so konfigurieren, dass sie Paketsichtbarkeit für die Erstanbieter-Apps hat, die dem Web-Intent-Filter Ihrer App entsprechen.