Rappel : À compter du 2 août 2022, toutes les nouvelles applications devront utiliser la bibliothèque Billing version 4 ou ultérieure. D'ici le 1er novembre 2022, toutes les mises à jour apportées aux applications existantes devront utiliser la bibliothèque Billing version 4 ou ultérieure. En savoir plus

Intégrer la bibliothèque Google Play Billing à votre application

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Cet article explique comment intégrer la bibliothèque Google Play Billing à votre application pour commencer à vendre des produits.

Cet article inclut des exemples de code basés sur les exemples d'applications officiels disponibles sur GitHub. Consultez la section Autres ressources pour obtenir la liste complète des exemples d'applications et d'autres ressources que vous pouvez utiliser lors de l'intégration.

Cycle de vie d'un achat

Voici un parcours d'achat standard pour un achat ou un abonnement ponctuels.

  1. Montrez aux utilisateurs ce qu'ils peuvent acheter.
  2. Lancez le parcours d'achat pour que l'utilisateur accepte l'achat.
  3. Vérifiez l'achat sur votre serveur.
  4. Fournissez le contenu à l'utilisateur.
  5. Confirmez la livraison du contenu. Pour les produits consommables, utilisez l'achat afin que l'utilisateur ne puisse pas l'acheter à nouveau.

Les abonnements sont renouvelés automatiquement jusqu'à ce qu'ils soient résiliés. Un abonnement peut présenter les états suivants :

  • Actif : l'utilisateur est en règle et a accès à l'abonnement.
  • Annulé : l'utilisateur a annulé l'abonnement, mais a toujours accès jusqu'à sa date d'expiration.
  • En délai de grâce : l'utilisateur a rencontré un problème de paiement, mais a toujours accès à l'élément pendant que Google tente à nouveau le mode de paiement.
  • En attente : l'utilisateur a rencontré un problème de paiement et n'y a plus accès pendant que Google tente à nouveau le mode de paiement.
  • Suspendu : l'utilisateur a suspendu son accès et n'y a pas accès tant qu'il ne l'a pas réactivé.
  • Expiré : l'utilisateur a résilié son abonnement et n'y a plus accès. L'utilisateur est considéré comme perdu après l'expiration.

Initialiser une connexion à Google Play

La première étape pour intégrer le système de facturation de Google Play consiste à ajouter la bibliothèque Google Play Billing à votre application et à initialiser une connexion.

Ajouter la dépendance de la bibliothèque Google Play Billing

Ajoutez la dépendance Google Play Billing au fichier build.gradle de votre application, comme indiqué ci-dessous :

Groovy

dependencies {
    def billing_version = "5.1.0"

    implementation "com.android.billingclient:billing:$billing_version"
}

Kotlin

dependencies {
    val billing_version = "5.1.0"

    implementation("com.android.billingclient:billing:$billing_version")
}

Si vous utilisez Kotlin, le module KTX de la bibliothèque Google Play Billing contient des extensions et des coroutines Kotlin qui vous permettent d'écrire du code Kotlin idiomatique lors de l'utilisation de la bibliothèque Google Play Billing. Pour inclure ces extensions dans votre projet, ajoutez la dépendance suivante au fichier build.gradle de votre application, comme indiqué ci-dessous :

Groovy

dependencies {
    def billing_version = "5.1.0"

    implementation "com.android.billingclient:billing-ktx:$billing_version"
}

Kotlin

dependencies {
    val billing_version = "5.1.0"

    implementation("com.android.billingclient:billing-ktx:$billing_version")
}

Initialiser un BillingClient

Une fois que vous avez ajouté une dépendance à la bibliothèque Google Play Billing, vous devez initialiser une instance BillingClient. BillingClient est l'interface principale de communication entre la bibliothèque Google Play Billing et le reste de votre application. BillingClient fournit des méthodes pratiques, synchrones et asynchrones, utiles pour de nombreuses opérations de facturation courantes. Nous vous recommandons vivement d'avoir une connexion BillingClient active simultanément pour éviter plusieurs rappels PurchasesUpdatedListener liés à un seul événement.

Pour créer un BillingClient, utilisez newBuilder(). Vous pouvez transmettre n'importe quel contexte à newBuilder(), et BillingClient l'utilise pour obtenir un contexte d'application. Vous n'avez donc plus à vous soucier des fuites de mémoire. Pour recevoir des mises à jour pour les achats, vous devez également appeler setListener(), en transmettant une référence à PurchasesUpdatedListener. Cet écouteur reçoit des mises à jour pour tous les achats dans votre application.

Kotlin

private val purchasesUpdatedListener =
   PurchasesUpdatedListener { billingResult, purchases ->
       // To be implemented in a later section.
   }

private var billingClient = BillingClient.newBuilder(context)
   .setListener(purchasesUpdatedListener)
   .enablePendingPurchases()
   .build()

Java

private PurchasesUpdatedListener purchasesUpdatedListener = new PurchasesUpdatedListener() {
    @Override
    public void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
        // To be implemented in a later section.
    }
};

private BillingClient billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases()
    .build();

Se connecter à Google Play

Après avoir créé un BillingClient, vous devez établir une connexion à Google Play.

Pour vous connecter à Google Play, appelez startConnection(). Le processus de connexion est asynchrone. Vous devez implémenter BillingClientStateListener pour recevoir un rappel une fois que la configuration du client est terminée et est prête à envoyer d'autres requêtes.

Vous devez également mettre en œuvre une logique de nouvelle tentative pour gérer les connexions perdues à Google Play. Pour implémenter une logique de nouvelle tentative, contournez la méthode de rappel onBillingServiceDisconnected() et assurez-vous que BillingClient appelle la méthode startConnection() pour vous reconnecter à Google Play avant d'envoyer d'autres requêtes.

L'exemple suivant montre comment démarrer une connexion et tester si elle est fonctionnelle :

Kotlin

billingClient.startConnection(object : BillingClientStateListener {
    override fun onBillingSetupFinished(billingResult: BillingResult) {
        if (billingResult.responseCode ==  BillingResponseCode.OK) {
            // The BillingClient is ready. You can query purchases here.
        }
    }
    override fun onBillingServiceDisconnected() {
        // Try to restart the connection on the next request to
        // Google Play by calling the startConnection() method.
    }
})

Java

billingClient.startConnection(new BillingClientStateListener() {
    @Override
    public void onBillingSetupFinished(BillingResult billingResult) {
        if (billingResult.getResponseCode() ==  BillingResponseCode.OK) {
            // The BillingClient is ready. You can query purchases here.
        }
    }
    @Override
    public void onBillingServiceDisconnected() {
        // Try to restart the connection on the next request to
        // Google Play by calling the startConnection() method.
    }
});

Afficher les produits disponibles à l'achat

Une fois la connexion à Google Play établie, vous pouvez interroger les produits disponibles et les présenter à vos utilisateurs.

L'interrogation des informations détaillées sur un produit est une étape importante avant de présenter vos produits aux utilisateurs, car elle renvoie des informations localisées sur le produit. Pour les abonnements, assurez-vous que l'affichage du produit respecte toutes les règles de Google Play.

Pour interroger les informations sur un produit intégré, appelez queryProductDetailsAsync().

Pour gérer le résultat de l'opération asynchrone, vous devez également spécifier un écouteur qui implémente l'interface ProductDetailsResponseListener. Vous pouvez ensuite contourner onProductDetailsResponse(), qui avertit l'écouteur lorsque la requête est terminée, comme illustré dans l'exemple suivant :

Kotlin

val queryProductDetailsParams =
    QueryProductDetailsParams.newBuilder()
        .setProductList(
            ImmutableList.of(
                Product.newBuilder()
                    .setProductId("product_id_example")
                    .setProductType(ProductType.SUBS)
                    .build()))
        .build()

billingClient.queryProductDetailsAsync(queryProductDetailsParams) {
    billingResult,
    productDetailsList ->
      // check billingResult
      // process returned productDetailsList
}
)

Java

QueryProductDetailsParams queryProductDetailsParams =
    QueryProductDetailsParams.newBuilder()
        .setProductList(
            ImmutableList.of(
                Product.newBuilder()
                    .setProductId("product_id_example")
                    .setProductType(ProductType.SUBS)
                    .build()))
        .build();

billingClient.queryProductDetailsAsync(
    queryProductDetailsParams,
    new ProductDetailsResponseListener() {
        public void onProductDetailsResponse(BillingResult billingResult,
                List<ProductDetails> productDetailsList) {
            // check billingResult
            // process returned productDetailsList
        }
    }
)

Lorsque vous interrogez les informations détaillées sur un produit, transmettez une instance de QueryProductDetailsParams qui spécifie une liste de chaînes d'ID produit créées dans la Google Play Console avec un élément ProductType. ProductType peut être de type ProductType.INAPP pour des produits ponctuels ou de type ProductType.SUBS pour les abonnements.

Interroger avec des extensions Kotlin

Si vous utilisez des extensions Kotlin, vous pouvez interroger les informations sur les produits intégrés à l'application en appelant la fonction d'extension queryProductDetails().

queryProductDetails() exploite les coroutines Kotlin. Vous n'avez donc pas besoin de définir un écouteur distinct. Au lieu de cela, la fonction est suspendue jusqu'à la fin de l'interrogation, après quoi vous pouvez traiter le résultat :

suspend fun processPurchases() {
    val productList = ArrayList<String>()
    productList.add("product_id_example")

    val params = QueryProductDetailsParams.newBuilder()
    params.setProductList(productList)
        .setType(ProductType.SUBS)

    // leverage queryProductDetails Kotlin extension function
    val productDetailsResult = withContext(Dispatchers.IO) {
        billingClient.queryProductDetails(params.build())
    }

    // Process the result.
}

Traiter le résultat

La bibliothèque Google Play Billing stocke les résultats de la requête dans un List d'objets ProductDetails. Vous pouvez ensuite appeler diverses méthodes sur chaque objet ProductDetails de la liste pour afficher des informations pertinentes sur un produit intégré, telles que son prix ou sa description. Pour afficher des informations détaillées disponibles sur le produit, consultez la liste des méthodes de la classe ProductDetails.

Avant de proposer un article à la vente, vérifiez que l'utilisateur n'en est pas déjà le propriétaire. Si l'utilisateur dispose d'un consommable qui se trouve toujours dans sa bibliothèque d'articles, il doit le consommer avant de pouvoir l'acheter à nouveau.

Avant de proposer un abonnement, vérifiez que l'utilisateur n'est pas déjà abonné. Notez également ce qui suit :

  • queryProductDetailsAsync() renvoie les détails des produits sur abonnement et un maximum de 50 offres par abonnement.
  • queryProductDetailsAsync() renvoie uniquement les offres pour lesquelles l'utilisateur est éligible. Si l'utilisateur tente d'acheter une offre pour laquelle il n'est pas éligible (par exemple, si l'application affiche une liste obsolète d'offres éligibles), Google Play informe l'utilisateur qu'il n'est pas éligible. L'utilisateur peut alors choisir d'acheter le forfait de base à la place.

Lancer le parcours d'achat

Pour démarrer une demande d'achat depuis votre application, appelez la méthode launchBillingFlow() à partir du thread principal de votre application. Cette méthode transmet une référence à un objet BillingFlowParams contenant l'objet ProductDetails approprié obtenu lors de l'appel de queryProductDetailsAsync(). Pour créer un objet BillingFlowParams, utilisez la classe BillingFlowParams.Builder.

Kotlin

// An activity reference from which the billing flow will be launched.
val activity : Activity = ...;

val productDetailsParamsList = listOf(
    BillingFlowParams.ProductDetailsParams.newBuilder()
        // retrieve a value for "productDetails" by calling queryProductDetailsAsync()
        .setProductDetails(productDetails)
        // to get an offer token, call ProductDetails.subscriptionOfferDetails()
        // for a list of offers that are available to the user
        .setOfferToken(selectedOfferToken)
        .build()
)

val billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(productDetailsParamsList)
    .build()

// Launch the billing flow
val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

Java

// An activity reference from which the billing flow will be launched.
Activity activity = ...;

ImmutableList productDetailsParamsList =
    ImmutableList.of(
        ProductDetailsParams.newBuilder()
             // retrieve a value for "productDetails" by calling queryProductDetailsAsync()
            .setProductDetails(productDetails)
            // to get an offer token, call ProductDetails.getSubscriptionOfferDetails()
            // for a list of offers that are available to the user
            .setOfferToken(selectedOfferToken)
            .build()
    );

BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(productDetailsParamsList)
    .build();

// Launch the billing flow
BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

La méthode launchBillingFlow() renvoie l'un des codes de réponse recensés dans BillingClient.BillingResponseCode. Assurez-vous que ce résultat ne comporte aucune erreur lors du lancement du parcours d'achat. Un BillingResponseCode de type OK indique un lancement réussi.

Lors d'un appel réussi à launchBillingFlow(), le système affiche l'écran d'achat Google Play. La figure 1 illustre l'écran d'achat d'un abonnement :

L'écran d'achat Google Play affiche un abonnement disponible à l'achat
Figure 1. L'écran d'achat de Google Play affiche un abonnement disponible à l'achat.

Google Play appelle onPurchasesUpdated() pour transmettre le résultat de l'opération d'achat à un écouteur qui implémente l'interface PurchasesUpdatedListener. L'écouteur est spécifié à l'aide de la méthode setListener() lors de l'initialisation du BillingClient.

Vous devez implémenter onPurchasesUpdated() pour gérer les éventuels codes de réponse. L'exemple suivant montre comment contourner onPurchasesUpdated() :

Kotlin

override fun onPurchasesUpdated(billingResult: BillingResult, purchases: List<Purchase>?) {
   if (billingResult.responseCode == BillingResponseCode.OK && purchases != null) {
       for (purchase in purchases) {
           handlePurchase(purchase)
       }
   } else if (billingResult.responseCode == BillingResponseCode.USER_CANCELED) {
       // Handle an error caused by a user cancelling the purchase flow.
   } else {
       // Handle any other error codes.
   }
}

Java

@Override
void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
    if (billingResult.getResponseCode() == BillingResponseCode.OK
        && purchases != null) {
        for (Purchase purchase : purchases) {
            handlePurchase(purchase);
        }
    } else if (billingResult.getResponseCode() == BillingResponseCode.USER_CANCELED) {
        // Handle an error caused by a user cancelling the purchase flow.
    } else {
        // Handle any other error codes.
    }
}

Un achat réussi génère un écran de confirmation d'achat Google Play semblable à la figure 2.

Écran de confirmation d'achat de Google Play
Figure 2. Écran de confirmation d'achat de Google Play.

Un achat réussi génère également un jeton d'achat, c'est-à-dire un identifiant unique qui représente l'utilisateur et l'ID du produit intégré qu'il a acheté. Vos applications peuvent stocker le jeton d'achat localement, mais nous vous recommandons de le transmettre à votre serveur backend sécurisé, où vous pourrez ensuite vérifier l'achat et vous protéger contre la fraude. Ce processus est décrit plus en détail dans la section suivante.

L'utilisateur reçoit également un reçu par e-mail contenant un ID de commande ou un ID unique de la transaction. Les utilisateurs reçoivent un e-mail contenant un ID de commande unique pour chaque achat de produit ponctuel, ainsi que pour l'achat initial de l'abonnement et les renouvellements automatiques récurrents ultérieurs. Vous pouvez utiliser cet ID de commande pour gérer les remboursements dans la Google Play Console.

Indiquer un prix personnalisé

Si votre application peut être distribuée aux utilisateurs de l'Union européenne, utilisez la méthode setIsOfferPersonalized() pour indiquer aux utilisateurs que le prix d'un article a été personnalisé à l'aide de la prise de décision automatisée.

Écran d'achat Google Play indiquant que le prix a été personnalisé pour l'utilisateur
Figure 3. Écran d'achat Google Play indiquant que le prix a été personnalisé pour l'utilisateur.

Vous devez consulter l'art. 6 (1) (ea) de la directive sur les droits des consommateurs (2011/83/UE) pour déterminer si le prix que vous proposez aux utilisateurs est personnalisé.

setIsOfferPersonalized() accepte une entrée booléenne. Si true, l'interface utilisateur Google Play indique que le prix a été personnalisé. Si false, l'interface utilisateur omet ce message. La valeur par défaut est false.

Pour obtenir plus d'informations, consultez le Centre d'aide.

Traiter les achats

Une fois qu'un utilisateur a effectué un achat, votre application doit le traiter. Dans la plupart des cas, votre application est informée des achats via votre PurchasesUpdatedListener, mais dans certains cas, votre application est informée via l'appel de BillingClient.queryPurchasesAsync(), comme décrit dans Récupérer les achats.

Pour traiter un achat, votre application doit :

  1. Vérifier l'achat.
  2. Fournir le contenu à l'utilisateur et confirmer la livraison. Dans certains cas, marquer l'article comme consommé pour que l'utilisateur puisse l'acheter à nouveau.

Pour vérifier un achat, vérifiez d'abord que l'état de l'achat est PURCHASED. Si l'achat est PENDING, vous devez le traiter comme décrit dans Gérer les transactions en attente. Pour les achats reçus de onPurchasesUpdated() ou queryPurchasesAsync(), vous devez vérifier l'achat plus précisément afin de vous assurer de sa légitimité avant que votre application accorde les droits d'accès. Pour savoir comment vérifier correctement un achat, consultez Vérifier les achats avant d'accorder des droits.

Une fois l'achat vérifié, votre application est prête à accorder un droit d'accès à l'utilisateur. Une fois les droits d'accès accordés, votre application doit confirmer l'achat. Cette confirmation indique à Google Play que vous avez accordé les droits d'accès à l'achat.

Le processus permettant d'accorder des droits d'accès et de confirmer l'achat dépend de la nature de l'achat : consommable, non consommable ou abonnement.

Pour les consommables, la méthode consumeAsync() répond aux exigences de confirmation et indique que votre application a accordé des droits à l'utilisateur. Cette méthode permet également à votre application de proposer à nouveau le produit ponctuel à l'achat.

Pour indiquer qu'un produit ponctuel a été consommé, appelez consumeAsync() et incluez le jeton d'achat que Google Play doit proposer à nouveau à la vente. Vous devez également transmettre un objet qui implémente l'interface ConsumeResponseListener. Cet objet gère le résultat de l'opération de consommation. Vous pouvez contourner la méthode onConsumeResponse(), que la bibliothèque Google Play Billing appelle une fois l'opération terminée.

L'exemple suivant illustre la consommation d'un produit à l'aide du jeton d'achat associé :

Kotlin

suspend fun handlePurchase(purchase: Purchase) {
    // Purchase retrieved from BillingClient#queryPurchasesAsync or your PurchasesUpdatedListener.
    val purchase : Purchase = ...;

    // Verify the purchase.
    // Ensure entitlement was not already granted for this purchaseToken.
    // Grant entitlement to the user.

    val consumeParams =
        ConsumeParams.newBuilder()
            .setPurchaseToken(purchase.getPurchaseToken())
            .build()
    val consumeResult = withContext(Dispatchers.IO) {
        client.consumePurchase(consumeParams)
    }
}

Java

void handlePurchase(Purchase purchase) {
    // Purchase retrieved from BillingClient#queryPurchasesAsync or your PurchasesUpdatedListener.
    Purchase purchase = ...;

    // Verify the purchase.
    // Ensure entitlement was not already granted for this purchaseToken.
    // Grant entitlement to the user.

    ConsumeParams consumeParams =
        ConsumeParams.newBuilder()
            .setPurchaseToken(purchase.getPurchaseToken())
            .build();

    ConsumeResponseListener listener = new ConsumeResponseListener() {
        @Override
        public void onConsumeResponse(BillingResult billingResult, String purchaseToken) {
            if (billingResult.getResponseCode() == BillingResponseCode.OK) {
                // Handle the success of the consume operation.
            }
        }
    };

    billingClient.consumeAsync(consumeParams, listener);
}

Pour confirmer les achats de produits non consommables, utilisez l'une des options suivantes : BillingClient.acknowledgePurchase() depuis la bibliothèque Google Play Billing, ou Product.Purchases.Acknowledge de l'API Google Play Developer. Avant de confirmer un achat, votre application doit vérifier s'il a déjà été confirmé à l'aide de la méthode isAcknowledged() dans la bibliothèque Google Play Billing ou de la méthode acknowledgementState dans l'API Google Developer.

L'exemple suivant montre comment confirmer un achat à l'aide de la bibliothèque Google Play Billing :

Kotlin

val client: BillingClient = ...
val acknowledgePurchaseResponseListener: AcknowledgePurchaseResponseListener = ...

suspend fun handlePurchase() {
    if (purchase.purchaseState === PurchaseState.PURCHASED) {
        if (!purchase.isAcknowledged) {
            val acknowledgePurchaseParams = AcknowledgePurchaseParams.newBuilder()
                    .setPurchaseToken(purchase.purchaseToken)
            val ackPurchaseResult = withContext(Dispatchers.IO) {
               client.acknowledgePurchase(acknowledgePurchaseParams.build())
            }
        }
     }
}

Java

BillingClient client = ...
AcknowledgePurchaseResponseListener acknowledgePurchaseResponseListener = ...

void handlePurchase(Purchase purchase) {
    if (purchase.getPurchaseState() == PurchaseState.PURCHASED) {
        if (!purchase.isAcknowledged()) {
            AcknowledgePurchaseParams acknowledgePurchaseParams =
                AcknowledgePurchaseParams.newBuilder()
                    .setPurchaseToken(purchase.getPurchaseToken())
                    .build();
            client.acknowledgePurchase(acknowledgePurchaseParams, acknowledgePurchaseResponseListener);
        }
    }
}

Les abonnements sont traités de la même manière que les produits non consommables. Vous pouvez confirmer un abonnement à l'aide de l'une des méthodes suivantes : BillingClient.acknowledgePurchase() depuis la bibliothèque Google Play Billing, ou Purchases.Subscriptions.Acknowledge de l'API Google Play Developer. Tous les achats initiaux d'abonnements doivent être confirmés. Il n'est pas nécessaire de confirmer les renouvellements d'abonnement. Pour en savoir plus sur la confirmation des abonnements, consultez la page Vendre des abonnements.

Récupérer les achats

Pour vous assurer que votre application traite tous les achats, il n'est pas suffisant d'utiliser un PurchasesUpdatedListener en ce qui concerne les mises à jour d'achats. Il est possible que votre application ne soit pas à jour quant à la totalité des achats effectués par un utilisateur. Voici quelques situations lors desquelles votre application peut perdre de vue un achat ou en ignorer l'existence :

  • Problèmes de réseau lors de l'achat : un utilisateur effectue un achat et reçoit la confirmation de Google, mais son appareil perd la connectivité réseau avant que son appareil ne reçoive une notification de l'achat via PurchasesUpdatedListener.
  • Plusieurs appareils : un utilisateur achète un article sur un appareil, puis s'attend à pouvoir le voir lorsqu'il change d'appareil.
  • Gérer les achats effectués en dehors de votre application : certains achats, par exemple l'utilisation d'offres promotionnelles, peuvent être effectués en dehors de votre application.

Pour gérer ces situations, assurez-vous que votre application appelle BillingClient.queryPurchasesAsync() dans votre méthode onResume() pour vous assurer que tous les achats sont bien traités comme décrit dans Traiter les achats.

L'exemple suivant montre comment récupérer les achats d'abonnement d'un utilisateur. Notez que queryPurchasesAsync() ne renvoie que les abonnements actifs et les achats ponctuels non consommés.

Kotlin

val params = QueryPurchasesParams.newBuilder()
               .setProductType(ProductType.SUBS)

// uses queryPurchasesAsync Kotlin extension function
val purchasesResult = billingClient.queryPurchasesAsync(params.build())

// check purchasesResult.billingResult
// process returned purchasesResult.purchasesList, e.g. display the plans user owns

Java

billingClient.queryPurchasesAsync(
    QueryPurchasesParams.newBuilder()
      .setProductType(ProductType.SUBS)
      .build(),
    new PurchasesResponseListener() {
      public void onQueryPurchasesResponse(BillingResult billingResult, List purchases) {
        // check billingResult
        // process returned purchase list, e.g. display the plans user owns

      }
    }
);

Récupérer l'historique des achats

queryPurchaseHistoryAsync() renvoie l'achat le plus récent effectué par l'utilisateur pour chaque produit, même si cet achat a expiré, a été annulé ou a été consommé.

Si vous utilisez des extensions Kotlin, vous pouvez utiliser la fonction d'extension queryPurchaseHistory().

Kotlin

val params = QueryPurchaseHistoryParams.newBuilder()
               .setProductType(ProductType.SUBS)

// uses queryPurchaseHistory Kotlin extension function
val purchaseHistoryResult = billingClient.queryPurchaseHistory(params.build())

// check purchaseHistoryResult.billingResult
// process returned purchaseHistoryResult.purchaseHistoryRecordList, e.g. display purchase

Java

billingClient.queryPurchaseHistoryAsync(
    QueryPurchaseHistoryParams.newBuilder()
        .setProductType(ProductType.SUBS)
        .build(),
    new PurchaseHistoryResponseListener() {
      public void onPurchaseHistoryResponse(
        BillingResult billingResult, List purchasesHistoryList) {
          // check billingResult
          // process returned purchase history list, e.g. display purchase history
        }
    }
);

Gérer les achats effectués en dehors de votre application

Certains achats (utilisation d'offres promotionnelles, par exemple) peuvent se produire en dehors de votre application. Lorsqu'un utilisateur effectue un achat en dehors de votre application, il s'attend à ce qu'un message s'affiche dans l'application ou qu'une notification lui indique que l'application a bien reçu et traité l'achat. Voici quelques-uns des mécanismes acceptés :

  • Afficher un pop-up dans l'application
  • Transmettre le message dans une zone de message dans l'application et indiquer clairement qu'un nouveau message s'y trouve.
  • Utiliser un message de notification de l'OS.

N'oubliez pas qu'il est possible qu'un achat soit reconnu par votre application, peu importe l'état dans lequel elle se trouve. Il est même possible que votre application ne soit même pas installée lors de l'achat. Les utilisateurs s'attendent à recevoir leur achat lorsqu'ils réactivent l'application, quel que soit l'état de l'application.

Vous devez détecter les achats, quel que soit l'état de leur application au moment où ils ont été effectués. Toutefois, dans certains cas, il peut être acceptable de ne pas informer immédiatement l'utilisateur que l'article a été reçu. Par exemple :

  • En plein milieu d'un jeu, l'affichage d'un message peut distraire l'utilisateur. Dans ce cas, vous devez prévenir l'utilisateur une fois la partie terminée.
  • Pendant les cinématiques, l'affichage d'un message peut distraire l'utilisateur. Dans ce cas, vous devez avertir l'utilisateur une fois la cinématique terminée.
  • Au cours du tutoriel de départ et de la configuration d'un jeu. Nous vous recommandons d'informer immédiatement les nouveaux utilisateurs de la récompense reçue dès qu'ils ouvrent le jeu ou lors de la configuration initiale de l'utilisateur. Cependant, il est possible d'attendre que la séquence de jeu principale soit disponible pour avertir l'utilisateur.

Tenez toujours compte de l'utilisateur lorsque vous choisissez quand et comment l'informer des achats effectués en dehors de votre application. Chaque fois qu'un utilisateur ne reçoit pas immédiatement une notification, il peut se sentir perdu et cesser d'utiliser votre application, contacter l'assistance utilisateur ou s'en plaindre sur les réseaux sociaux. Remarque : PurchasesUpdatedListener est enregistré dans le contexte de votre application afin de pouvoir gérer les mises à jour des achats, y compris ceux effectués en dehors de votre application. Ainsi, si votre processus d'application n'existe pas, votre PurchasesUpdatedListener ne sera pas notifié. C'est pourquoi votre application doit appeler BillingClient.queryPurchasesAsync() dans la méthode onResume(), comme indiqué dans la section Récupérer les achats.

Traiter les transactions en attente

Google Play accepte les transactions en attente ou celles nécessitant une ou plusieurs étapes supplémentaires entre le moment où l'utilisateur effectue un achat et le traitement du mode de paiement associé. Votre application ne doit pas accorder de droit à ces types d'achats tant que Google ne vous a pas informé que le mode de paiement de l'utilisateur a été débité.

Par exemple, un utilisateur peut créer un achat PENDING d'un article intégré à l'application en choisissant le paiement en espèces. L'utilisateur peut ensuite choisir un magasin physique dans lequel il terminera la transaction et recevra un code par notification et par e-mail. Lorsque l'utilisateur arrive au magasin physique, il peut passer par le caissier pour utiliser le code et payer en espèces. Google vous informe ensuite, vous et l'utilisateur, qu'un paiement en espèces a été effectué. Votre application peut alors accorder des droits à l'utilisateur.

Votre application doit prendre en charge les transactions en attente en appelant enablePendingPurchases() lors de l'initialisation de votre application.

Lorsque votre application reçoit un nouvel achat, via votre PurchasesUpdatedListener ou suite à un appel queryPurchasesAsync(), utilisez la méthode getPurchaseState() pour déterminer si l'état d'achat est PURCHASED ou PENDING.

Si votre application est en cours d'exécution lorsque l'utilisateur effectue l'achat, votre PurchasesUpdatedListener est appelé à nouveau et PurchaseState est désormais PURCHASED. À ce stade, votre application peut traiter l'achat à l'aide de la méthode standard de traitement des achats ponctuels. Votre application doit également appeler queryPurchasesAsync() dans la méthode onResume() de votre application pour gérer les achats qui sont passés à l'état PURCHASED lorsque votre application n'était pas en cours d'exécution.

Votre application peut également utiliser les notifications en temps réel pour les développeurs avec les achats en attente en écoutant OneTimeProductNotifications. Lorsque l'achat passe de PENDING à PURCHASED, votre application reçoit une notification ONE_TIME_PRODUCT_PURCHASED. Si l'achat est annulé, votre application reçoit une notification ONE_TIME_PRODUCT_CANCELED. Cela peut se produire si votre client n'effectue pas le paiement dans le délai requis. Lorsque vous recevez ces notifications, vous pouvez utiliser l'API Google Play Developer, qui inclut un état PENDING pour Purchases.products.

Pour connaître la procédure détaillée permettant de tester ce scénario, consultez la section Tester les achats en attente.

Gérer les achats de quantités multiples

Compatible avec les versions 4.0 et ultérieures de la bibliothèque Google Play Billing, Google Play permet aux clients d'acheter plus d'un produit intégré dans l'application en une seule transaction en spécifiant une quantité dans le panier d'achat. Votre application doit gérer les achats de quantités multiples et accorder des droits en fonction de la quantité d'achats spécifiée.

Pour respecter les achats de quantités multiples, la logique de provisionnement de votre application doit vérifier une quantité d'articles. Vous pouvez accéder à un champ quantity à partir de l'une des API suivantes :

Une fois que vous avez ajouté une logique pour gérer les achats de quantités multiples, vous devez activer la fonctionnalité de quantités multiples pour le produit correspondant sur la page de gestion des produits intégrés à l'application de la Google Play Console.