KappS Base de connaissances · Blog

Google Play Install Referrer API en 2026 : données d’attribution et états de connexion

Blog Guide

L’attribution des installations est la mesure dont dépend chaque installation payante, et sur Google Play elle provient d’une interface unique et légère : l’Install Referrer API. Ce n’est pas une fonctionnalité de tableau de bord et elle ne vous envoie pas de chiffres par e-mail — elle transmet à votre application le contenu de référence enregistré par Play au moment de l’installation, une seule fois, et c’est ensuite à vous de le stocker et de le rapprocher. Ce tutoriel parcourt tout le chemin : ce que renvoie l’API, comment se connecter, comment lire la réponse, la règle des 90 jours que la plupart des équipes découvrent trop tard, et que faire pour chaque état de connexion.

Tout ce qui suit s'appuie sur les pages de référence de Google consacrées à l'Install Referrer API et à la Play Install Referrer Client Library, toutes deux consultées le 2026-10-27.

Étape 1 — Savoir exactement ce que renvoie l’API avant de concevoir autour

L’API récupère le contenu de parrainage enregistré par l’application Play Store, et la charge utile documentée est étroite et précise :

  • l’URL de provenance du package installé ;
  • l’horodatage, en secondes, du clic du référent — disponible côté client et côté serveur ;
  • le timestamp, en secondes, du début de l'installation — là encore côté client et côté serveur ;
  • la version de l’application au moment de la première installation ;
  • si l’utilisateur a interagi avec l’expérience instantanée de votre application au cours des 7 derniers jours.

Deux prérequis conditionnent l’ensemble. L’API est exposée par l’application Play Store sur l’appareil, et les appareils exécutant Play Store 8.3.73 ou une version ultérieure y ont accès automatiquement. Vous avez également besoin d’un compte Google Play Console. En interne, l’API est une interface AIDL ; les développeurs Kotlin et Java sont censés utiliser le wrapper de la bibliothèque cliente plutôt que l’AIDL brut.

Conséquence de conception : il s’agit d’une attribution de première installation avec un horodatage de clic et un horodatage de début d’installation. Il n’y a ni chaîne multi-touch, ni vue traversante, ni graphe inter-appareils dans la réponse. Si votre modèle de reporting présuppose l’un de ces éléments, les données doivent provenir d’ailleurs.

Étape 2 — Ajouter la bibliothèque cliente

Dans le build.gradle du module de l’application, ajoutez la dépendance. La version documentée sur la page de la bibliothèque cliente est 2.2 :

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

Si votre module est configuré pour le Kotlin DSL, la même coordonnée s’ajoute avec implementation("com.android.installreferrer:installreferrer:2.2"). Rien d’autre n’est nécessaire — pas de receiver dans le manifeste, pas d’autorisation, pas d’option dans Play Console. L’ancienne approche par broadcast receiver est ce que cette bibliothèque remplace ; ne conservez pas les deux chemins.

Étape 3 — se connecter à l’application Play Store

La connexion est asynchrone, et c’est précisément là que commencent la plupart des implémentations défaillantes. La séquence documentée est la suivante : créez un client avec InstallReferrerClient.newBuilder(this).build(), appelez startConnection(), puis passez un InstallReferrerStateListener qui reçoit le résultat.

referrerClient = InstallReferrerClient.newBuilder(this).build() referrerClient.startConnection(object : InstallReferrerStateListener { override fun onInstallReferrerSetupFinished(responseCode: Int) { when (responseCode) { InstallReferrerResponse.OK -> { /* connexion établie */ } InstallReferrerResponse.FEATURE_NOT_SUPPORTED -> { /* API indisponible sur cette application Play Store */ } InstallReferrerResponse.SERVICE_UNAVAILABLE -> { /* connexion impossible à établir */ } } } override fun onInstallReferrerServiceDisconnected() { /* rappeler startConnection() avant la prochaine requête */ } })

Lisez le contrat de rappel au pied de la lettre. OK signifie que la connexion a réussi et que vous pouvez continuer. FEATURE_NOT_SUPPORTED signifie que l’API n’est pas disponible sur l’application Play Store de cet appareil — un build du store ancien ou non standard, pas un bug dans votre code. SERVICE_UNAVAILABLE signifie que la connexion n’a pas pu être établie du tout, ce qui est un problème de timing, pas un verdict.

La déconnexion est attendue plutôt qu’exceptionnelle : la note de Google précise elle-même que le client peut perdre la connexion si le service Play Store se met à jour en arrière-plan, et que le client doit rappeler startConnection() pour la relancer avant toute nouvelle requête. Le listener n’est donc pas à usage unique ; traitez-le comme une machine à états que vous pilotez.

Étape 4 — lire les détails du référent

Une fois connecté, getInstallReferrer() est un appel synchronisé qui renvoie un objet ReferrerDetails. Les champs correspondent un à un à la charge utile listée à l’étape 1 :

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

Deux d’entre eux sont plus utiles qu’ils n’en ont l’air. referrerClickTimestampSeconds et installBeginTimestampSeconds permettent de calculer le delta clic-installation par campagne — un delta lent signifie généralement que c’est la page du store, et non l’annonce, qui a fait perdre l’utilisateur. googlePlayInstantParam indique si l’installation provient d’une expérience instantanée au cours des 7 derniers jours, seul signal d’attribution instantanée présent dans la réponse.

Étape 5 — Respectez la fenêtre de 90 jours et ne la sollicitez qu’une fois

Voici la phrase qui coûte leurs données historiques aux équipes : les informations de l’install referrer seront disponibles pendant 90 jours et ne changeront pas, sauf si l’application est réinstallée. La recommandation de Google qui suit est tout aussi directe — pour éviter des appels API inutiles, n’appelez l’API qu’une seule fois lors de la première exécution après l’installation.

Les 90 jours ne sont pas une licence de stockage. C’est la fenêtre pendant laquelle la valeur reste récupérable depuis Play, si bien qu’une application qui ne la lit que paresseusement, lors d’une session ultérieure, a une échéance ferme. Lisez-la au premier lancement après installation et persistez-la. Comme elle ne change pas tant que l’application n’est pas réinstallée, une boucle de rafraîchissement ne vous apporte rien et ne fait qu’ajouter des appels.

Fermez la connexion quand vous avez terminé : appelez endConnection() côté client. La raison donnée par Google est explicite — fermer la connexion évite les fuites et les problèmes de performance sur l'appareil.

Étape 6 — Branchez-vous sur le code de réponse, ne réessayez pas à l’aveugle

La lecture d’attribution au premier lancement se trouve sur le chemin critique de la première expérience de l’utilisateur, la politique d’échec compte donc autant que le code. Une correspondance exploitable :

  • OK — lisez, persistez, endConnection(). Ne relisez pas lors des lancements suivants.
  • SERVICE_UNAVAILABLE — à traiter comme « pas maintenant ». Ne stockez rien, ne bloquez pas le premier écran et réessayez lors d’un lancement ultérieur dans la fenêtre de 90 jours.
  • FEATURE_NOT_SUPPORTED — l’API n’est pas disponible sur cet appareil. Revenez à l’identifiant de campagne que porte votre propre lien, et enregistrez que la lecture n’était pas prise en charge afin que votre reporting ne la compte pas silencieusement comme organique.
  • Déconnecté — redémarrez avec startConnection() avant la requête suivante ; ne partez pas du principe que le client est toujours actif.

Une règle d’ingénierie prime sur les quatre autres : ne jamais laisser l’attribution bloquer l’UX du premier lancement, et ne jamais laisser une lecture échouée écrire une fausse ligne d’attribution « organic ». La différence entre « aucune donnée » et « organic » est précisément là où les rapports d’installation cessent de se réconcilier.

Étape 7 — Traiter la chaîne de référent comme une entrée non fiable

La bibliothèque cliente renvoie la valeur du referrer sous forme de chaîne. Elle est fournie par la plateforme, mais reste une valeur issue de l’extérieur de votre application : les règles d’hygiène habituelles pour les entrées externes s’appliquent donc — analysez-la défensivement en paires clé-valeur, limitez sa longueur et ne l’interpolez jamais sans validation dans une URL, une route de deep link ou une requête de base de données.

Concrètement, cela signifie : décoder la valeur, découper selon les séparateurs documentés, mettre en liste blanche les clés de campagne que vous reconnaissez réellement, et écarter tout le reste. Puis rapprochez le résultat de votre propre événement côté serveur avant qu’il ne devienne une donnée de facturation ou de revenus. Les données d’attribution décident quel canal reçoit du budget — une chaîne non validée ne devrait pas pouvoir déplacer de l’argent.

Si la chaîne de référent est transmise à des régies publicitaires ou à un MMP, vérifiez que votre déclaration de sécurité des données Play et votre politique de confidentialité couvrent déjà ce partage avant la mise en production du pipeline, et non après un audit. La plomberie d’attribution est une collecte de données ; la déclaration doit la décrire.

Étape 8 — Notez ce que l’API ne vous dit pas

La plupart des litiges d’attribution viennent d’attentes erronées face à une réponse pourtant correcte. D’après les deux pages de référence, les limites honnêtes sont les suivantes :

  • Les appareils antérieurs à la version 8.3.73 du Play Store n'ont tout simplement pas l'API — prévoyez le repli, car FEATURE_NOT_SUPPORTED est un résultat réel, pas une erreur à journaliser et à oublier.
  • La valeur est fixée à la première installation et ne change pas sauf réinstallation de l'application — elle ne peut donc pas exprimer un réengagement, une mise à niveau ou un contact de campagne ultérieur.
  • La récupération prend fin après 90 jours — tout ce que vous n’avez pas conservé dans cette fenêtre est perdu.
  • L’indicateur d’expérience instantanée ne couvre qu’une fenêtre de 7 jours.
  • Il s'agit d'un signal au niveau de l'appareil et du compte pour les installations depuis Play ; ce n'est pas une identité utilisateur et cela ne dédupliquera pas les installations entre appareils.

Consignez ces cinq limites dans le même document que votre schéma d’attribution. Quand un rapport de campagne et un rapport de revenus divergent, la divergence vient généralement de l’une de ces cinq affirmations, pas d’un bug côté client.

Sources : Android Developers — Google Play Install Referrer API (developer.android.com/google/play/installreferrer) : champs de payload, exigence Play Store 8.3.73+, interface AIDL, exigence de compte Play Console. Android Developers — Play Install Referrer Library (developer.android.com/google/play/installreferrer/library, page mise à jour le 2026-10-23) : version de dépendance 2.2, flux de connexion et codes de réponse, champs getInstallReferrer() et ReferrerDetails, la note de disponibilité de 90 jours, la recommandation d’un appel par installation et endConnection(). Les deux vérifiés le 2026-10-27. Google ne publie pas de taux d’attribution par campagne ni de chiffres de latence côté store ; aucune valeur n’est déduite ici.

Vous gérez des comptes développeur à grande échelle ? Nous prenons en charge le volet opérationnel.

Cliquez pour choisir un fichier · clic droit → Coller, ou appuyez sur Ctrl/⌘+V pour coller une capture d’écran

Vous pouvez aussi glisser un fichier sur cette zone.

Nous répondons à l’e-mail que vous indiquez. Vos données restent chez KappS.

✔ Soumis

Nous avons bien reçu votre message et vous répondrons sous 24 heures.


← Retour à la modification