App-Links überprüfen

Wenn android:autoVerify="true" in mindestens einem Intent-Filter Ihrer App vorhanden ist, werden bei der Installation Ihrer App auf einem Gerät mit Android 6.0 (API-Level 23) oder höher die Hosts, die mit den URLs in den Intent-Filtern Ihrer App verknüpft sind, automatisch vom System überprüft. Unter Android 12 und höher können Sie den Überprüfungsprozess auch manuell aufrufen, um die Überprüfungslogik 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 Intent-Filtern gefunden wird, fragt Android die entsprechenden Websites nach der Digital Asset Links-Datei unter https://hostname/.well-known/assetlinks.json ab.

Nachdem du die Liste der Websites, die mit deiner App verknüpft werden sollen, und die Gültigkeit der gehosteten JSON-Datei bestätigt hast, installiere die App auf deinem Gerät. Warten Sie mindestens 20 Sekunden, bis der asynchrone Überprüfungsprozess abgeschlossen ist. Prüfen Sie mit dem folgenden Befehl, ob das System Ihre App verifiziert 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 auf einem Gerät installierte App 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 den aktualisierten Prozess zur Domainbestätigung.

Andernfalls können Sie das aktualisierte Überprüfungsverfahren 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 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 Überprüfung selbst durchführen. Führen Sie dazu den folgenden Befehl in einem Terminalfenster aus:

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

Ergebnisse der Überprüfung ansehen

Nachdem Sie dem Prüf-Agenten etwas Zeit gegeben haben, seine Anfragen abzuschließen, prüfen Sie die Ergebnisse. Dazu führen Sie 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 erfolgreich bestehen, haben den Domainbestätigungsstatus verified. Jeder andere Status gibt an, dass die Domainbestätigung nicht durchgeführt werden konnte. Insbesondere der Status none weist darauf hin, dass der Prüfungs-Agent das Überprüfungsverfahren möglicherweise noch nicht abgeschlossen hat.

In der folgenden Liste sind die möglichen Rückgabewerte aufgeführt, die die Domainbestätigung für eine bestimmte Domain zurückgeben kann:

none

Für diese Domain wurde nichts aufgezeichnet. Warten Sie noch einige Minuten, bis der Bestätigungs-Agent die Anfragen im Zusammenhang mit der Domainbestätigung abgeschlossen hat, und rufen Sie dann das Domain-Überprüfungsverfahren noch einmal auf.

verified

Die Domain wurde für die deklarierende App erfolgreich bestätigt.

approved

Die Domain wurde zwangsweise genehmigt, normalerweise durch Ausführen eines Shell-Befehls.

denied

Die Domain wurde zwangsweise abgelehnt, normalerweise durch Ausführen eines Shell-Befehls.

migrated

Das System hat das Ergebnis eines vorherigen Prozesses beibehalten, bei dem die alte 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-Prüfer abgelehnt. Der genaue Grund für den Fehler ist unbekannt.

system_configured

Die Domain wurde automatisch über die Gerätekonfiguration genehmigt.

Fehlercode 1024 oder höher

Benutzerdefinierter Fehlercode, der für den Verifizierer 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, die App mit dieser Domain zu verknüpfen.

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

Bevor du den Nutzer aufforderst, solltest du prüfen, ob deine App der Standard-Handler für die Domains ist, die du in deinen <intent-filter>-Elementen definierst. Sie können den Genehmigungsstatus mit einer der folgenden Methoden abfragen:

• Die DomainVerificationManager API (zur Laufzeit).
• Ein Befehlszeilenprogramm (während des Tests).

DomainVerificationManager

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

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 }

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 die App die Überprüfung für die Domain „example.org“ zwar nicht bestanden, Nutzer 0 hat die App jedoch manuell in den Systemeinstellungen genehmigt und es wurde kein anderes Paket für diese Domain überprüft.

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 Vorgang zu simulieren, bei dem der Nutzer auswählt, welche App mit einer bestimmten Domain verknüpft ist. 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 Domaingenehmigung stellen, sollten Sie dem Nutzer einige Informationen zur Verfügung stellen. Du kannst ihnen beispielsweise einen Splash Screen, ein Dialogfeld oder ein ähnliches UI-Element anzeigen, in dem erklärt wird, warum deine 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 Intent-Aktion ACTION_APP_OPEN_BY_DEFAULT_SETTINGS und einen Datenstring enthält, der mit package:com.example.pkg für die Ziel-App übereinstimmt, wie im folgenden Code-Snippet gezeigt:

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)

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 den Einstellungsbildschirm Standardmäßig öffnen. Dieser Bildschirm enthält ein Optionsfeld namens Unterstützte Links öffnen, wie in Abbildung 1 dargestellt.

Wenn der Nutzer Unterstützte Links öffnen aktiviert, wird 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 innerhalb der von ihnen hinzugefügten Domains auswählen, wird der Link automatisch in Ihrer App geöffnet.

Domains in Ihrer App öffnen, die von Ihrer App nicht verifiziert werden können

Die Hauptfunktion Ihrer App besteht möglicherweise darin, Links als Drittanbieter zu öffnen, ohne die Möglichkeit, die verarbeiteten Domains zu bestätigen. In diesem Fall solltest du Nutzern erklären, dass sie beim Auswählen eines Weblinks nicht zwischen einer Erstanbieter-App und deiner Drittanbieter-App wählen können. Nutzer müssen die Domains manuell mit deiner Drittanbieter-App verknüpfen.

Außerdem kannst du einen Dialog oder eine Trampolin-Aktivität einführen, mit der der Nutzer den Link in der Erstanbieter-App öffnen kann, wenn er dies bevorzugt. Bevor du eine solche Dialog- oder Trampolin-Aktivität einrichtest, musst du deine App so konfigurieren, dass sie Paketsichtbarkeit für die Erstanbieter-Apps hat, die dem Web-Intent-Filter deiner 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 es dauert, bis diese Änderungen auf den Geräten der Endnutzer angezeigt werden, von der Betriebssystemversion ab:

• Android 15 (API-Level 35) und höher:Das System überprüft Domains regelmäßig im Hintergrund. Es kann bis zu sieben Tage dauern, bis Änderungen aufgrund des Cachings und der geplanten erneuten Überprüfung des Systems auf allen Endnutzergeräten wirksam werden.
• 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 übernommen, wenn die App installiert oder aktualisiert wird.

Updates testen

Wenn Sie während des Tests eine erneute Überprüfung 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 assetlinks.json-Datei 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.