Attribuer un solde initial

Chaque profil démarre avec un solde de 0 dans chaque devise, et les produits liés n’accordent des crédits qu’à l’occasion d’un achat ou d’un renouvellement. Ainsi, un utilisateur qui n’a encore rien acheté ne reçoit jamais de crédits automatiquement.

Vous pouvez toujours attribuer un solde de départ aux nouveaux utilisateurs : un bonus de bienvenue, une allocation d’essai gratuit ou un ensemble de vies. Accordez-le depuis votre backend via l’API côté serveur, après avoir identifié l’utilisateur.

Accorder le solde à un nouvel utilisateur

1. Identifiez d’abord l’utilisateur : un solde appartient à un profil et ne peut jamais être transféré à un autre, donc n’accordez les crédits qu’une fois que le profil dispose d’un identifiant utilisateur client. Identifiez l’utilisateur dans votre application via le SDK (voir Identifier les utilisateurs) ou depuis votre backend via l’API côté serveur.

Accorder des crédits à un profil anonyme est l’erreur la plus fréquente ici. Les profils anonymes sont liés à une seule installation de l’application, donc l’utilisateur perd ses crédits s’il réinstalle l’application ou l’ouvre sur un autre appareil. Consultez Soldes, profils et appareils pour un aperçu complet.

2. Accordez les crédits : Appelez Créer une transaction de monnaie virtuelle avec un amount positif. Cet exemple accorde 500 tokens :

    curl -X POST https://api.adapty.io/api/v2/server-side-api/vc/transactions/ \
      -H "Authorization: Api-Key {your secret key}" \
      -H "adapty-customer-user-id: user-42" \
      -H "Idempotency-Key: 6f2c0b34-9c3a-4f5e-8a1d-2b7e5c9d0a11" \
      -H "Content-Type: application/json" \
      -d '{
            "items": [{"currency_code": "TOKENS", "amount": 500}],
            "metadata": {"reason": "initial_balance"}
          }'

La réponse renvoie le nouveau solde :

    {
      "transaction_id": "3a9f8e21-5d4c-4b7a-9e01-8c6d2f4b1a37",
      "balances": [
        { "code": "TOKENS", "name": "Tokens", "balance": 500, "held": 0, "available": 500 }
      ]
    }

Les crédits accordés de cette façon n’expirent jamais, contrairement aux crédits par cycle d’un abonnement lié.

Le champ metadata est facultatif. Un tag comme reason: initial_balance permet de retrouver facilement le crédit dans l’historique des transactions et de le distinguer des crédits d’achat dans vos propres rapports.

3. Enregistrez l’attribution dans votre base de données : Stockez le fait que cet utilisateur a reçu son solde initial, afin qu’une reconnexion ou une tâche réessayée ne l’accorde pas deux fois. La section suivante explique pourquoi cet enregistrement est nécessaire.

Accordez-le exactement une fois

Votre propre base de données est la source de vérité pour déterminer si un utilisateur a reçu son solde initial. Deux approches qui semblent suffisantes ne le sont pas :

• Idempotency-Key protège un seul appel, pas un utilisateur : Réessayer une requête avec la même clé renvoie le résultat d’origine au lieu d’accorder à nouveau, ce qui permet de relancer un appel en toute sécurité après un délai d’attente. Adapty mémorise chaque clé pendant une heure au maximum, par profil. Passé ce délai, la même clé accorde à nouveau, donc l’en-tête ne peut pas vous indiquer des mois plus tard si un utilisateur a déjà reçu son solde initial. Générez une nouvelle clé pour chaque nouvel octroi.
• Lire le solde en premier ne prouve rien : Un solde de 0 signifie soit que l’utilisateur n’a jamais reçu de crédits, soit qu’il en a reçu et les a tous dépensés. Lister les soldes de monnaie virtuelle ne permet pas de distinguer les deux cas.

Vérifiez donc votre propre enregistrement avant d’appeler l’API, et écrivez l’enregistrement après une réponse réussie.

Remplir les soldes des utilisateurs existants

Lorsque vous créez une devise, tous les profils existants démarrent à 0, et les liens produits ne s’appliquent qu’à partir de ce moment. Pour attribuer un solde de départ à vos utilisateurs actuels, effectuez un remplissage unique depuis votre backend.

1. Dans votre base de données, collectez les identifiants utilisateur clients auxquels accorder des devises.
2. Pour chacun d’eux, appelez Créer une transaction de devise virtuelle comme indiqué ci-dessus. Il n’existe pas d’endpoint en masse : une requête accorde des devises à un seul profil, et une seule requête peut couvrir jusqu’à 20 devises pour ce profil.
3. Conservez l’enregistrement par utilisateur de la section précédente au fur et à mesure, afin de pouvoir interrompre le traitement et le reprendre sans effectuer de double attribution.
4. Respectez la limite de débit de 600 requêtes par minute par application. Une requête dépassant cette limite échoue avec rate_limited, donc réglez le débit du traitement et relancez les utilisateurs en échec.

Prochaines étapes

• Dépensez le solde et lisez-le à l’exécution : Démarrage rapide avec la monnaie virtuelle.
• Vérifiez ce que possède un utilisateur et auditez chaque modification : Solde de monnaie virtuelle.