KappS Wissensdatenbank · Blog

Google Play Install Referrer API in 2026: Attributionsdaten und Verbindungszustände

Blog Leitfaden

Die Install-Attribution ist die eine Messung, auf der jeder bezahlte Install basiert, und auf Google Play stammt sie aus einer einzigen, kleinen Schnittstelle: der Install Referrer API. Sie ist keine Dashboard-Funktion und schickt Ihnen keine Zahlen per E-Mail – sie übergibt Ihrer App einmalig den Referrer-Inhalt, den Play zum Installationszeitpunkt erfasst hat, und danach liegt es an Ihnen, ihn zu speichern und abzugleichen. Dieses Tutorial zeigt den gesamten Weg: was die API zurückgibt, wie Sie sich verbinden, wie Sie die Antwort lesen, die 90-Tage-Regel, die die meisten Teams zu spät entdecken, und was bei jedem Verbindungsstatus zu tun ist.

Alles Folgende stützt sich auf die Referenzseiten von Google zur Install Referrer API und zur Play Install Referrer Client Library, beide geprüft am 27.10.2026.

Schritt 1 — Wissen Sie genau, was die API zurückgibt, bevor Sie darauf aufbauen

Die API ruft Empfehlungsinhalte ab, die von der Play-Store-App erfasst wurden, und die dokumentierte Payload ist eng und spezifisch:

  • die Referrer-URL des installierten Pakets;
  • der Zeitstempel in Sekunden des Referrer-Klicks – sowohl client- als auch serverseitig verfügbar;
  • der Zeitstempel, in Sekunden, zu dem die Installation begann — wiederum sowohl client- als auch serverseitig;
  • die App-Version zum Zeitpunkt der Erstinstallation;
  • ob der Nutzer in den letzten 7 Tagen mit der Instant Experience Ihrer App interagiert hat.

Zwei Voraussetzungen entscheiden über alles. Die API wird von der Play-Store-App auf dem Gerät bereitgestellt, und Geräte mit Play Store 8.3.73 oder höher haben automatisch Zugriff. Außerdem benötigen Sie ein Google Play Console-Konto. Darunter ist die API eine AIDL-Schnittstelle; Kotlin- und Java-Entwickler sollten den Wrapper der Client-Bibliothek statt des rohen AIDL verwenden.

Gestaltungskonsequenz: Dies ist First-Install-Attribution mit einem Klick-Zeitstempel und einem Install-Begin-Zeitstempel. Es gibt keine Multi-Touch-Kette, kein View-Through und keinen geräteübergreifenden Graphen in der Antwort. Wenn Ihr Reporting-Modell eines davon voraussetzt, müssen die Daten von woanders kommen.

Schritt 2 — Client-Bibliothek einbinden

Fügen Sie im build.gradle des App-Moduls die Abhängigkeit hinzu. Die auf der Seite der Client-Bibliothek dokumentierte Version ist 2.2:

dependencies { ... implementation "com.android.installreferrer:installreferrer:2.2" }

Wenn Ihr Modul für Kotlin DSL konfiguriert ist, wird dieselbe Koordinate mit implementation("com.android.installreferrer:installreferrer:2.2") hinzugefügt. Mehr ist nicht erforderlich — kein Manifest-Receiver, keine Berechtigung, kein Schalter in der Play Console. Der alte Broadcast-Receiver-Ansatz ist genau das, was diese Bibliothek ersetzt; führen Sie nicht beide Wege parallel.

Schritt 3 — Mit der Play Store-App verbinden

Die Verbindung ist asynchron, und genau hier beginnen die meisten fehlerhaften Implementierungen. Die dokumentierte Reihenfolge lautet: Erstellen Sie einen Client mit InstallReferrerClient.newBuilder(this).build(), rufen Sie startConnection() auf und übergeben Sie einen InstallReferrerStateListener, der das Ergebnis empfängt.

referrerClient = InstallReferrerClient.newBuilder(this).build() referrerClient.startConnection(object : InstallReferrerStateListener { override fun onInstallReferrerSetupFinished(responseCode: Int) { when (responseCode) { InstallReferrerResponse.OK -> { /* Verbindung hergestellt */ } InstallReferrerResponse.FEATURE_NOT_SUPPORTED -> { /* API in dieser Play-Store-App nicht verfügbar */ } InstallReferrerResponse.SERVICE_UNAVAILABLE -> { /* Verbindung konnte nicht hergestellt werden */ } } } override fun onInstallReferrerServiceDisconnected() { /* startConnection() vor der nächsten Anfrage erneut aufrufen */ } })

Lesen Sie den Callback-Vertrag wörtlich. OK bedeutet, dass die Verbindung erfolgreich war und Sie fortfahren können. FEATURE_NOT_SUPPORTED bedeutet, dass die API in der Play-Store-App dieses Geräts nicht verfügbar ist – ein alter oder nicht standardmäßiger Store-Build, kein Fehler in Ihrem Code. SERVICE_UNAVAILABLE bedeutet, dass die Verbindung überhaupt nicht hergestellt werden konnte, was ein Timing-Problem und kein Urteil ist.

Eine Trennung ist zu erwarten und nicht die Ausnahme: Die eigene Anmerkung von Google lautet, dass der Client die Verbindung verlieren kann, wenn der Play-Store-Dienst im Hintergrund aktualisiert wird, und dass der Client vor weiteren Anfragen erneut startConnection() aufrufen muss, um sie neu zu starten. Der Listener ist also kein Einmal-Ereignis; behandeln Sie ihn als Zustandsmaschine, die Sie steuern.

Schritt 4 – Lesen Sie die Referrer-Details

Sobald die Verbindung hergestellt ist, ist getInstallReferrer() ein synchronisierter Aufruf, der ein ReferrerDetails-Objekt zurückgibt. Die Felder entsprechen eins zu eins der in Schritt 1 aufgeführten Nutzlast:

val response: ReferrerDetails = referrerClient.installReferrer val referrerUrl: String = response.installReferrer val referrerClickTime: Long = response.referrerClickTimestampSeconds val appInstallTime: Long = response.installBeginTimestampSeconds val instantExperienceLaunched: Boolean = response.googlePlayInstantParam

Zwei davon sind nützlicher, als sie aussehen. referrerClickTimestampSeconds und installBeginTimestampSeconds lassen Sie das Klick-zu-Install-Delta pro Kampagne berechnen – ein langsames Delta bedeutet meist, dass die Store-Seite und nicht die Anzeige den Nutzer verloren hat. googlePlayInstantParam sagt Ihnen, ob die Installation in den letzten 7 Tagen aus einer Instant-Erfahrung stammte – das einzige Instant-Attributionssignal in der Antwort.

Schritt 5 — Halten Sie das 90-Tage-Fenster ein und entscheiden Sie einmal

Dies ist der Satz, der Teams ihre historischen Daten kostet: Die Install-Referrer-Informationen sind 90 Tage lang verfügbar und ändern sich nicht, es sei denn, die Anwendung wird neu installiert. Die darauffolgende Empfehlung von Google ist ebenso direkt — um unnötige API-Aufrufe zu vermeiden, rufen Sie die API nur einmal während der ersten Ausführung nach der Installation auf.

Die 90 Tage sind keine Aufbewahrungslizenz. Es ist das Zeitfenster, in dem der Wert noch aus Play abrufbar ist – eine App, die ihn nur träge in irgendeiner späteren Sitzung liest, hat also eine harte Frist. Lesen Sie ihn beim ersten Start nach der Installation und speichern Sie ihn dauerhaft. Da er sich nur bei einer Neuinstallation der App ändert, bringt Ihnen eine Aktualisierungsschleife nichts und erzeugt nur zusätzliche Aufrufe.

Schließen Sie die Verbindung, wenn Sie fertig sind: Rufen Sie endConnection() auf dem Client auf. Die Begründung von Google ist eindeutig – das Schließen der Verbindung vermeidet Lecks und Performance-Probleme auf dem Gerät.

Schritt 6 — Verzweigen Sie nach dem Antwortcode, wiederholen Sie nicht blind

Ein Attributions-Read beim ersten Start liegt auf dem kritischen Pfad des ersten Nutzererlebnisses, daher zählt die Fehlerstrategie genauso wie der Code. Eine praktikable Zuordnung:

  • OK — lesen, persistieren, endConnection(). Bei späteren Starts nicht erneut lesen.
  • SERVICE_UNAVAILABLE — als „jetzt nicht" behandeln. Nichts speichern, den ersten Bildschirm nicht blockieren und beim nächsten Start innerhalb des 90-Tage-Fensters erneut versuchen.
  • FEATURE_NOT_SUPPORTED – die API ist auf diesem Gerät nicht vorhanden. Greifen Sie auf die Kampagnenkennung zurück, die Ihr eigener Link mitführt, und erfassen Sie, dass der Lesevorgang nicht unterstützt wurde, damit Ihre Auswertung ihn nicht stillschweigend als organisch zählt.
  • Getrennt – starten Sie mit startConnection() vor der nächsten Anfrage neu; gehen Sie nicht davon aus, dass der Client noch aktiv ist.

Eine technische Regel steht über allen vier: Lassen Sie niemals zu, dass Attribution das First-Run-Erlebnis blockiert, und lassen Sie niemals zu, dass ein fehlgeschlagener Lesevorgang eine falsche „Organic“-Attributionszeile schreibt. Die Differenz zwischen „keine Daten“ und „Organic“ ist genau der Punkt, an dem Install-Reportings aufhören, übereinzustimmen.

Schritt 7 — Behandeln Sie den Referrer-String als nicht vertrauenswürdige Eingabe

Die Client-Bibliothek gibt den Referrer-Wert als String zurück. Er wird von der Plattform geliefert, stammt aber dennoch von außerhalb Ihrer App, daher gilt die übliche Hygiene für externe Eingaben: Parsen Sie ihn defensiv in Schlüssel-Wert-Paare, begrenzen Sie seine Länge und setzen Sie ihn niemals ungeprüft in eine URL, eine Deep-Link-Route oder eine Datenbankabfrage ein.

In der Praxis heißt das: den Wert dekodieren, an den dokumentierten Trennzeichen aufteilen, die Kampagnen-Schlüssel, die Sie tatsächlich erkennen, auf eine Whitelist setzen und alles andere verwerfen. Dann gleichen Sie es mit Ihrem eigenen serverseitigen Event ab, bevor es zu einer Abrechnungs- oder Umsatzgröße wird. Attributionsdaten entscheiden, welcher Kanal Budget bekommt – ein ungeprüfter String darf kein Geld bewegen können.

Wenn der Referrer-String an Werbenetzwerke oder ein MMP weitergegeben wird, prüfen Sie, ob Ihre Play-Erklärung zur Datensicherheit und Ihre Datenschutzerklärung diese Weitergabe bereits abdecken, bevor die Pipeline live geht – nicht erst nach einem Audit. Attribution ist Datenerhebung; die Erklärung muss sie beschreiben.

Schritt 8 — Notieren Sie, was die API Ihnen nicht mitteilt

Die meisten Attribution-Streitfälle entstehen, weil man von einer korrekten Antwort das Falsche erwartet. Aus den beiden Referenzseiten ergeben sich die ehrlichen Grenzen:

  • Geräte unter Play Store 8.3.73 haben die API schlicht nicht – planen Sie den Fallback ein, denn FEATURE_NOT_SUPPORTED ist ein reales Ergebnis und kein Fehler, den man loggt und vergisst.
  • Der Wert wird bei der Erstinstallation festgelegt und ändert sich nur bei einer Neuinstallation — er kann daher kein Re-Engagement, ein Upgrade oder einen späteren Kampagnen-Kontakt abbilden.
  • Die Abrufbarkeit endet nach 90 Tagen — alles, was Sie in diesem Zeitraum nicht gespeichert haben, ist verloren.
  • Das Instant-Experience-Flag deckt nur einen 7-Tage-Rückblick ab.
  • Es ist ein Signal auf Geräte- und Kontoebene für Installationen aus Play; es ist keine Nutzeridentität und dedupliziert Installationen nicht geräteübergreifend.

Halten Sie diese fünf Grenzen im selben Dokument wie Ihr Attributionsschema fest. Wenn ein Kampagnenbericht und ein Umsatzbericht voneinander abweichen, liegt die Abweichung meist an einer dieser fünf Aussagen und nicht an einem Fehler im Client.

Quellen: Android Developers — Google Play Install Referrer API (developer.android.com/google/play/installreferrer): Payload-Felder, Anforderung Play Store 8.3.73+, AIDL-Schnittstelle, Anforderung eines Play-Console-Kontos. Android Developers — Play Install Referrer Library (developer.android.com/google/play/installreferrer/library, Seite zuletzt aktualisiert am 2026-10-23): Abhängigkeitsversion 2.2, Verbindungsablauf und Antwortcodes, Felder getInstallReferrer() und ReferrerDetails, der Hinweis zur 90-tägigen Verfügbarkeit, die Empfehlung zur einmaligen Abfrage pro Installation und endConnection(). Beides geprüft am 2026-10-27. Google veröffentlicht keine Attributionsraten pro Kampagne oder Latenzwerte auf Store-Seite; hier werden keine solchen Werte abgeleitet.

Sie verwalten Entwicklerkonten im großen Stil? Wir übernehmen die operative Seite.

Klicken Sie, um eine Datei auszuwählen · Rechtsklick → Einfügen oder Ctrl/⌘+V drücken, um einen Screenshot einzufügen

Sie können eine Datei auch auf dieses Feld ziehen.

Wir antworten an die von Ihnen angegebene E-Mail-Adresse. Ihre Daten bleiben bei KappS.

✔ Eingereicht

Wir haben Ihre Nachricht erhalten und antworten innerhalb von 24 Stunden.


← Zurück zum Bearbeiten