--- title: "Attribuer un solde initial" description: "Donnez aux nouveaux utilisateurs un solde de départ en devise virtuelle via l'API côté serveur, et rétroalimentez les utilisateurs existants lors du lancement d'une nouvelle devise." --- :::link Article principal : [Devises virtuelles](virtual-currencies) ::: Chaque profil démarre avec un solde de 0 dans chaque devise, et les [produits liés](create-virtual-currency#link-products) 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](getting-started-with-server-side-api), après avoir identifié l'utilisateur. ## Accorder le solde à un nouvel utilisateur \{#grant-the-balance-for-a-new-user\} 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](ios-quickstart-identify)) 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](virtual-currency-balance#balances-profiles-and-devices) pour un aperçu complet. 2. **Accordez les crédits** : Appelez [Créer une transaction de monnaie virtuelle](api-adapty/operations/createVirtualCurrencyTransaction) avec un `amount` positif. Cet exemple accorde 500 tokens : ```bash title="Grant an initial balance" 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 : ```json title="Response" { "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](api-adapty/operations/listVirtualCurrencyTransactions) 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 \{#grant-it-exactly-once\} 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](api-adapty/operations/listVirtualCurrencyBalances) 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 \{#backfill-existing-users\} 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](create-virtual-currency#link-products). 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](api-adapty/operations/createVirtualCurrencyTransaction) 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. :::tip Ne remplissez rétroactivement que les utilisateurs que vous souhaitez cibler, par exemple ceux actifs ou payants. Les crédits accordés via l'API n'expirent jamais, donc le solde que vous attribuez maintenant reste sur le profil jusqu'à ce que l'utilisateur le dépense. ::: ## Prochaines étapes \{#next-steps\} - Dépensez le solde et lisez-le à l'exécution : [Démarrage rapide avec la monnaie virtuelle](virtual-currency-quickstart). - Vérifiez ce que possède un utilisateur et auditez chaque modification : [Solde de monnaie virtuelle](virtual-currency-balance).