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 die Bestätigung der Hosts durchgeführt, die mit den URLs in den Intent-Filtern Ihrer App verknüpft sind. Unter Android 12 und höher können Sie den Bestätigungsprozess auch manuell aufrufen, um die Bestätigungslogik zu testen.

Automatische Bestätigung

Die automatische Bestätigung 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 Intent-Filtern gefunden wird, fragt Android die entsprechenden Websites nach der Digital Asset Links-Datei unter https://hostname/.well-known/assetlinks.json ab.

Nachdem Sie die Liste der Websites bestätigt haben, die mit Ihrer App verknüpft werden sollen, und bestätigt haben, dass die gehostete JSON-Datei gültig ist, installieren Sie die App auf Ihrem Gerät. Warten Sie mindestens 20 Sekunden, bis der asynchrone Bestätigungsprozess abgeschlossen ist. Mit dem folgenden Befehl können Sie prüfen, ob das System Ihre App bestätigt und die richtigen Richtlinien für die Linkbehandlung 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 Prozess 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.

Aktualisierten Domainbestätigungsprozess unterstützen

Wenn Ihre App auf Android 12 oder höher ausgerichtet ist, verwendet das System automatisch den aktualisierten Domainbestätigungsprozess.

Andernfalls können Sie den aktualisierten Bestätigungsprozess 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 gleichen Zustand versetzt, 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 Sie dem Bestätigungsagenten etwas Zeit gegeben haben, um die Anfragen zu bearbeiten, prüfen Sie die Bestätigungsergebnisse. 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

Für Domains, bei denen die Bestätigung erfolgreich war, ist der Domainbestätigungsstatus verified. Jeder andere Status gibt an, dass die Domainbestätigung nicht durchgeführt werden konnte. Insbesondere der Status none gibt an, dass der Bestätigungsagent 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 wurde nichts aufgezeichnet. Warten Sie einige Minuten, bis der Bestätigungsagent die Anfragen zur Domainbestätigung abgeschlossen hat, und rufen Sie dann 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 vorherigen Prozesses beibehalten, bei dem die Legacy-Domainbestätigung verwendet wurde.
restored
Die Domain wurde genehmigt, nachdem der Nutzer eine Datenwiederherstellung durchgeführt hat. Es wird davon ausgegangen, dass die Domain zuvor 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 1024 oder höher

Benutzerdefinierter Fehlercode, der spezifisch für den Bestätiger des Geräts ist.

Prüfen Sie noch einmal, ob Sie eine Netzwerk verbindung hergestellt haben, und rufen Sie den Domain bestätigungsprozess noch einmal auf.

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

Eine weitere Möglichkeit, Ihre App für eine Domain genehmigen zu lassen, 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 den <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 den folgenden Befehl ausführen, um den Bestätigungsstatus der Domains abzufragen, die Ihrer Organisation gehören:

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

In der folgenden Beispielausgabe hat der Nutzer 0 die App in den Systemeinstellungen manuell genehmigt, obwohl die Bestätigung für die Domain „example.org“ fehlgeschlagen ist. Außerdem ist kein anderes Paket 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 wird. Eine vollständige Erklärung dieser Befehle finden Sie in der Ausgabe von adb shell pm.

Kontext für die Anfrage angeben

Bevor Sie diese Anfrage zur Domainbestätigung stellen, geben Sie dem Nutzer etwas Kontext. Sie können ihm 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 einen Intent auf, der die ACTION_APP_OPEN_BY_DEFAULT_SETTINGS Intent-Aktion und einen Datenstring enthält, der package:com.example.pkgfür die Ziel-App entspricht, wie in dem 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 die Nutzer einen Einstellungsbildschirm mit dem Namen Standardmäßig öffnen. Dieser Bildschirm enthält ein Optionsfeld mit dem Namen Unterstützte Links öffnen, wie in Abbildung 1 dargestellt.

Wenn der Nutzer Unterstützte Links öffnen aktiviert, werden unter dem Abschnitt Links, die in dieser App geöffnet werden sollen eine Reihe von Kästchen angezeigt. Hier 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, wie in Abbildung 2 dargestellt. Wenn Nutzer später einen Link in den 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 Bildschirm mit den Systemeinstellungen, auf dem 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 Ihre App nicht bestätigen kann

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

Außerdem können Sie ein Dialogfeld oder eine Trampolin-Aktivität einführen, mit der der Nutzer den Link in der Erstanbieter-App öffnen kann, wenn er dies bevorzugt. Diese fungiert dann als Proxy. Bevor Sie ein solches Dialogfeld oder eine solche Trampolin-Aktivität einrichten, müssen Sie Ihre App so einrichten, dass sie Pakete in den Erstanbieter-Apps sehen kann, die dem Web-Intent-Filter Ihrer App entsprechen.

Latenz bei der Aktualisierung von Digital Asset Links

Wenn Sie die Datei assetlinks.json auf Ihrem Webserver aktualisieren, hängt die Zeit, die vergeht, bis diese Änderungen auf den Geräten der Endnutzer sichtbar werden, von der Betriebssystemversion ab:

  • Android 15 (API-Level 35) und höher:Das System führt regelmäßig im Hintergrund eine erneute Bestätigung der Domains durch. Es kann bis zu sieben Tage dauern, bis Änderungen auf allen Geräten der Endnutzer wirksam werden. Das liegt am Caching und der geplanten erneuten Bestätigung des Systems.
  • Android 14 (API-Level 34) und niedriger:Das System führt keine regelmäßige erneute Bestätigung im Hintergrund durch. Aktualisierungen der Datei werden in der Regel nur bei der Installation oder Aktualisierung der App übernommen.

Updates testen

Wenn Sie während des Tests eine erneute Bestätigung auf einem bestimmten Gerät erzwingen möchten, können Sie die App deinstallieren und neu installieren. Beachten Sie jedoch, dass serverseitige Caches die Bereitstellung der aktualisierten Datei assetlinks.json auf dem Gerät auch nach der Neuinstallation verzögern können. Da der Cache zeitbasiert ist, wird die Verzögerung in der Regel automatisch behoben, wenn Sie es nach einigen Stunden noch einmal versuchen.