Documentation de référence sur la gestion des licences

Classes et interfaces de bibliothèque LVL

Le tableau 1 liste tous les fichiers sources de la bibliothèque LVL (License Verification Library), disponibles via le SDK Android. Tous les fichiers font partie du package com.android.vending.licensing.

Tableau 1. Résumé des classes et des interfaces de bibliothèque LVL.

Réponse du serveur

Le tableau 2 liste tous les champs de réponse de licence renvoyés par le serveur de gestion des licences.

Tableau 2. Récapitulatif des champs de réponse de licence renvoyés par le serveur Google Play.

Codes de réponse du serveur

Le tableau 3 liste tous les codes de réponse de licence compatibles avec le serveur de gestion des licences. En général, une application doit gérer tous ces codes de réponse. Par défaut, la classe LicenseValidator du LVL assure la gestion nécessaire de ces codes de réponse.

Tableau 3. Récapitulatif des codes de réponse renvoyés par le serveur Google Play dans une réponse de licence.

Remarque : Comme indiqué dans Configurer l'environnement de test, le code de réponse peut être remplacé manuellement pour le développeur de l'application et tout utilisateur test enregistré via la Google Play Console.

Remarque : Auparavant, vous pouviez tester une application en important une version brouillon non publiée de celle-ci. Cette fonctionnalité n'est plus disponible. Vous devez à présent la publier sur le canal de distribution alpha ou bêta. Pour en savoir plus, consultez la page Les versions provisoires d'applications ne sont plus acceptées.

Réponses du serveur : extras

Pour aider votre application à gérer l'accès à l'application tout au long de la période de remboursement et à fournir d'autres informations, le serveur de gestion des licences inclut plusieurs informations dans les réponses de licence. Plus précisément, le service fournit des valeurs recommandées pour la période de validité de la licence de l'application, le délai de grâce pour les relances, le nombre maximal de relances autorisées et d'autres paramètres. Si votre application utilise des fichiers d'extension pour APK, la réponse inclut également les noms, les tailles et les URL des fichiers. Le serveur ajoute les paramètres en tant que paires clé/valeur dans le champ "Extras" de la réponse de licence.

Toute implémentation de Policy peut extraire les paramètres supplémentaires de la réponse de licence et les utiliser au besoin. L'implémentation de Policy par défaut de la bibliothèque LVL, ServerManagedPolicy, sert d'implémentation opérationnelle et montre comment obtenir, stocker et utiliser les paramètres.

Tableau 4. Résumé des paramètres de gestion des licences fournis par le serveur Google Play dans une réponse de licence.

Période de validité de la licence

Le serveur de gestion des licences Google Play définit une période de validité de la licence pour toutes les applications téléchargées. La période exprime l'intervalle de temps pendant lequel l'état de la licence d'une application doit être considéré comme immuable et pouvant être mis en cache par une Policy de licence dans l'application. Le serveur de gestion des licences inclut la période de validité dans sa réponse à toutes les vérifications de licence, en ajoutant un horodatage de fin de validité à la réponse en tant qu'extra sous la clé VT. Une Policy peut extraire la valeur de clé VT et l'utiliser pour autoriser l'accès à l'application de manière conditionnelle sans revérifier la licence, jusqu'à expiration de la période de validité.

La validité de la licence signale à une Policy de licence lorsque l'état de la licence doit être revérifié auprès du serveur de gestion des licences. Elle n'est pas destinée à insinuer qu'une application est effectivement sous licence. Autrement dit, lorsque la période de validité de la licence de l'application expire, cela ne signifie pas que l'application n'est plus sous licence, mais simplement que Policy doit revérifier l'état de la licence avec le serveur. Ensuite, tant que la période de validité de la licence n'a pas expiré, la Policy peut mettre en cache l'état initial de la licence localement et renvoyer l'état de la licence mis en cache au lieu d'envoyer une nouvelle vérification des licences au serveur.

Le serveur de gestion des licences gère la période de validité pour aider l'application à attribuer correctement les licences pendant la période de remboursement proposée par Google Play pour les applications payantes. Il définit la période de validité en fonction de l'achat ou non de l'application et, le cas échéant, de sa date. Plus précisément, le serveur définit une période de validité comme suit :

• Pour une application payante, le serveur définit la période de validité initiale de la licence afin que la réponse de la licence reste valide tant que l'application est remboursable. Une Policy de licence dans l'application peut mettre en cache le résultat de la vérification initiale de la licence et n'a pas besoin de la vérifier à nouveau avant la fin de la période de validité.
• Lorsqu'une application n'est plus remboursable, le serveur définit une période de validité plus longue, généralement un nombre de jours.
• Pour une application sans frais, le serveur définit la période de validité sur une valeur très élevée (long.MAX_VALUE). Cela garantit que, si Policy a mis en cache l'horodatage de validité en local, il n'aura pas besoin de revérifier l'état de la licence de l'application à l'avenir.

L'implémentation de ServerManagedPolicy utilise l'horodatage extrait (mValidityTimestamp) comme condition principale pour déterminer si l'état de la licence doit être revérifié avant d'autoriser l'utilisateur à accéder à l'application.

Période de relance et nombre maximal de relances

Dans certains cas, les conditions du système ou du réseau peuvent empêcher la vérification des licences d'une application d'atteindre le serveur de gestion des licences, ou empêcher la réponse du serveur d'atteindre l'application cliente Google Play. Par exemple, l'utilisateur peut lancer une application lorsqu'aucune connexion au réseau mobile ni aucune connexion de données n'est disponible (en avion, par exemple), lorsque la connexion réseau est instable ou que le signal du réseau mobile est faible.

Lorsque des problèmes de réseau empêchent ou interrompent la vérification des licences, le client Google Play envoie une notification à l'application en renvoyant un code de réponse RETRY à la méthode processServerResponse() de Policy. En cas de problème système, par exemple lorsque l'application ne parvient pas à s'associer à l'implémentation de ILicensingService de Google Play, la bibliothèque LicenseChecker appelle la méthode processServerResponse() avec un code de réponse RETRY.

En général, le code de réponse RETRY indique à l'application qu'une erreur s'est produite et a empêché la vérification d'une licence.

Le serveur Google Play aide une application à gérer l'attribution de licences en cas d'erreur en définissant un nouveau "délai de grâce" et un nombre maximal de relances recommandé. Le serveur inclut ces valeurs dans toutes les réponses de vérification de licence, en les ajoutant en tant qu'extras dans les clés GT et GR.

La Policy de l'application peut extraire les extras GT et GR, et les utiliser pour autoriser l'accès à l'application de manière conditionnelle, comme suit :

• Pour une vérification de licence qui génère une réponse RETRY, la Policy doit mettre en cache le code de réponse RETRY et augmenter le nombre de réponses RETRY.
• Le champ Policy doit permettre à l'utilisateur d'accéder à l'application, à condition que le délai de grâce des relances soit toujours actif ou que le nombre maximal de relances n'ait pas été atteint.

La ServerManagedPolicy utilise les valeurs GT et GR fournies par le serveur, comme décrit ci-dessus. L'exemple ci-dessous montre le traitement conditionnel des réponses aux relances dans la méthode allow(). Le nombre de réponses RETRY est conservé dans la méthode processServerResponse(), et non affiché.

fun allowAccess(): Boolean {
    val ts = System.currentTimeMillis()
    return when(lastResponse) {
        LICENSED -> {
            // Check if the LICENSED response occurred within the validity timeout.
            ts <= validityTimestamp  // Cached LICENSED response is still valid.
        }
        RETRY -> {
            ts < lastResponseTime + MILLIS_PER_MINUTE &&
                    // Only allow access if we are within the retry period
                    // or we haven't used up our max retries.
                    (ts <= retryUntil || retryCount <= maxRetries)
        }
        else -> false
    }
}

public boolean allowAccess() {
    long ts = System.currentTimeMillis();
    if (lastResponse == LicenseResponse.LICENSED) {
        // Check if the LICENSED response occurred within the validity timeout.
        if (ts <= validityTimestamp) {
            // Cached LICENSED response is still valid.
            return true;
        }
    } else if (lastResponse == LicenseResponse.RETRY &&
                ts < lastResponseTime + MILLIS_PER_MINUTE) {
        // Only allow access if we are within the retry period
        // or we haven't used up our max retries.
        return (ts <= retryUntil || retryCount <= maxRetries);
    }
    return false;
}