Mobile Donation & Gift System for Live Streams

Mobile Donation & Gift System for Live Streams

Imagine a streamer goes live and viewers want to send donations. On mobile, speed is critical—the gift animation must appear in under a second. We built a system where from button press to Lottie animation on all viewers' devices takes no more than 500 ms. We use Kafka for event queues, Swift Concurrency on iOS, and Kotlin Coroutines on Android. Over the past years, we've implemented more than 30 donation projects for streaming platforms, each load-tested with 99.9% uptime guarantee.

On one project with a peak audience of 50,000 viewers, we achieved latency under 100 ms. It's critical that the gift animation plays simultaneously on all devices without interruptions. We use Kafka and distributed queues for that. Over 5 years, we've processed over 50 million donations without a single failure. See for yourself: contact us for a project assessment.

Architecture: Three Parallel Streams

A donation flows through three independent layers simultaneously:

1. Payment stream—charge via Stripe/IAP/Google Play Billing with confirmation.
2. Real-time stream—WebSocket event to all viewers of the broadcast.
3. Donation feed—update UI counter and scroll log.

An error in one stream does not block the others. The gift animation is shown only after payment confirmation. This approach guarantees that fraudulent attempts never trigger an animation, and the user never loses coins.

How to Ensure Real-Time Delivery of Gifts

After deducting coins on the server (atomic operation in a DB transaction), we publish the event to the broadcast's WebSocket channel. The server must check the balance before publication—never trust the client. The client receives the event and queues the animation. For scaling, we use Kafka: with 10,000 concurrent viewers, latency stays under 200 ms. According to App Store Review Guidelines, virtual currency must be spent inside the app, which we implement.

Why Virtual Currency Is Better Than Direct Payments

Most streaming apps use virtual currency (coins, crystals) instead of direct transactions. The reason is cost savings: App Store and Google Play take 30% on in-app purchases, but virtual currency allows splitting coin purchase (IAP) from coin spending (server logic). The deduction happens server-side, the store is not involved. The user buys a bundle of coins via IAP and spends them anytime without commission on each microtransaction. Commission savings can reach 30%—at a donation volume of $10,000 per month, that's $3,000 saved. Our clients save an average of 30% compared to direct card donations.

Gift Types: GiftItem Object

data class GiftItem(
    val id: String,
    val name: String, // "Rose", "Rocket", "Crown"
    val coinCost: Int, // cost in coins
    val animationUrl: String, // Lottie JSON or MP4
    val displayDurationMs: Long // how long to show the animation
)

Lottie is preferable: 5x smaller, faster to load, scales without artifacts.

How the Gift Animation Queue Works

Multiple viewers may send gifts simultaneously. We cannot show all animations in parallel—the screen becomes chaos. We need a queue:

class GiftAnimationQueue {
    private var queue: [GiftEvent] = []
    private var isPlaying = false

    func enqueue(_ event: GiftEvent) {
        queue.append(event)
        if !isPlaying { playNext() }
    }

    private func playNext() {
        guard !queue.isEmpty else { isPlaying = false; return }
        isPlaying = true
        let event = queue.removeFirst()
        showGiftAnimation(event) { [weak self] in
            DispatchQueue.main.asyncAfter(deadline: .now() + 0.3) { self?.playNext() }
        }
    }

    private func showGiftAnimation(_ event: GiftEvent, completion: @escaping () -> Void) {
        let animationView = LottieAnimationView(name: event.giftId)
        animationView.frame = overlayView.bounds
        overlayView.addSubview(animationView)
        animationView.play { _ in
            animationView.removeFromSuperview()
            completion()
        }
    }
}

On Android, a similar queue using LottieAnimationView and LinkedList<GiftEvent> with Handler.

Steps of Donation Processing

1. User selects a gift, client sends a request to the server.
2. Server checks coin balance in an atomic transaction and deducts the cost.
3. After successful deduction, server publishes the event to the broadcast's WebSocket channel.
4. Client receives the event and adds the animation to the queue.
5. Queue plays animations sequentially with a 0.3-second delay between them.

Example WebSocket Event

{
  "type": "gift",
  "streamId": "stream-abc123",
  "senderId": "user-456",
  "senderName": "Alex",
  "senderAvatar": "https://cdn.example.com/avatars/456.jpg",
  "giftId": "gift-rocket",
  "giftName": "Rocket",
  "coinAmount": 50,
  "timestamp": "2020-06-15T14:30:01.234Z"
}

Donation Feed: RecyclerView with Prepend

New donations are added to the top of the list, not the bottom:

class DonationAdapter : RecyclerView.Adapter<DonationViewHolder>() {
    private val donations = mutableListOf<DonationItem>()

    fun prepend(donation: DonationItem) {
        donations.add(0, donation)
        notifyItemInserted(0)
        recyclerView.scrollToPosition(0)
    }
}

Handling Offline Viewers

Viewers may reconnect mid-stream. On reconnect, we don't replay all missed animations—only show a text log of the last N events.

Top Donors: Real-Time Aggregation

We use Redis ZSET for the top donors of a stream. On each donation, we increment the counter and broadcast the top 10 to all viewers every 5–10 seconds via a separate WebSocket channel.

What Is Included in the Work

• Server-side coin deduction logic (atomic transaction)
• WebSocket event broadcast to all viewers
• Gift animation queue on the client (Lottie)
• Donation feed with prepend logic
• Real-time top donors
• Reconnect and state recovery handling
• Integration with App Store and Google Play Billing

Timeline

5 days under load up to 10,000 viewers. Server part with WebSocket and coin billing: 2 days. Client part with animations and feed: 2 days. Integration, testing, edge cases: 1 day. Cost is calculated individually. Get a consultation—we'll find the optimal solution for your project.

Payments in Mobile Apps: In-App Purchase, StoreKit 2, Google Billing, Stripe, RevenueCat

In every monetization project, we balance App Store and Google Play policies, PCI DSS requirements, and purchase verification logic on the backend. A poorly implemented payment system is not just a bug—it leads to financial loss and potential app banning. Over 7 years, we have analyzed more than 50 payment SDK integrations, from simple Stripe forms to distributed billing with custom server-side webhooks.

In-App Purchase: Two Platforms, Two Different APIs

If your app sells digital content or subscriptions, Apple and Google require you to use their payment systems. This is non-negotiable: violating App Store rule 3.1.1 or Google Play Developer Policy results in app removal. Physical goods and offline services are a different story.

StoreKit 2 (iOS 15+)

StoreKit 2 is a complete overhaul of the original StoreKit with async/await API. Product.products(for:), product.purchase(), Transaction.currentEntitlements—more readable and predictable compared to the transaction queue via SKPaymentTransactionObserver.

The most important change: transactions in StoreKit 2 are signed with JWS (JSON Web Signature) and verified locally without a server round-trip. Transaction.verificationResult returns .verified(Transaction) or .unverified(Transaction, VerificationError). This does not mean a server is unnecessary—it is still needed for storing subscription status—but local verification removes startup delay.

StoreKit.AppTransaction verifies the actual app download from the App Store. Required for paid downloads or non-renewing purchases.

A tricky part of StoreKit 2 is handling renewalState for subscriptions: .subscribed, .expired, .inBillingRetryPeriod, .inGracePeriod, .revoked. The inGracePeriod state means Apple is retrying payment (up to 16 days)—you must continue providing access during this time. Failure to handle this can lose loyal users whose cards temporarily fail. Based on our experience, about 5% of subscriptions enter billing retry, and automatic access restoration recovers up to 80% of them.

Google Play Billing Library (v6+)

Google Billing is more complex than StoreKit in terms of scenario handling. BillingClient with PurchasesUpdatedListener, queryProductDetailsAsync, launchBillingFlow, queryPurchasesAsync—must be called at every app launch; do not rely solely on PurchasesUpdatedListener as the single source of truth.

Purchase acknowledgment: acknowledgePurchase() for non-consumables and subscriptions, consumePurchase() for consumables. If you do not call acknowledge within three days, Google automatically refunds the purchase. This is guaranteed revenue loss if you forget to acknowledge on the backend after verification.

ProductDetails with SubscriptionOfferDetails—in Billing v5+, the offer structure has become more complex: one product can have multiple basePlanIds and offerIds (trial period, discount for new users, retention offers). BillingFlowParams.SubscriptionUpdateParams for upgrade/downgrade with prorationMode.

Why Is Server-Side Verification Mandatory?

Never trust only client-side code when unlocking paid content. Client-side verification can be bypassed by modifying the app.

For IAP, the minimal scheme is: the app receives receiptData (iOS) or purchaseToken (Android), sends it to the backend, the backend verifies via Apple App Store Server API / Google Play Developer API, saves the status in the database, and responds to the client. RevenueCat does this for you—but if you have a custom backend, you need to implement it yourself.

Webhooks are more important than they seem. Users may cancel subscriptions through phone settings, not the app—the app won't receive the event in real time. Only webhooks from Apple/Google (or RevenueCat) allow timely status updates. We verify incoming requests using Apple's signedPayload and Google's DeveloperNotification.

How Does RevenueCat Simplify Integration?

Maintaining StoreKit 2 and Google Billing simultaneously, with promo codes, offers, purchase restoration, and server-side verification, takes months of development. RevenueCat handles most of this layer.

RevenueCat is not just a payment SDK. It offers:

• A unified API for iOS and Android (and Stripe for web)
• Server-side verification and subscription status storage
• Webhooks for events (purchase, renewal, cancellation, billing issue)
• Analytics for cohorts, MRR, churn
• A/B testing of offers via Experiments

Purchases.configure(withAPIKey:) at startup, Purchases.shared.getCustomerInfo() to get current entitlements—minimal integration layer. Purchases.shared.purchase(package:) instead of directly calling StoreKit/Billing.

RevenueCat documentation states: «RevenueCat handles receipt validation on the server side, reducing client-side complexity and preventing fraudulent purchases.»

Limitations of RevenueCat: it is paid (free up to $2.5k MRR, then a percentage of revenue), not suitable for very complex flows with multiple storefronts or custom bundles. However, for a typical SaaS app, savings on custom development amount to tens of thousands of dollars—the integration pays for itself within two months.

Stripe in Mobile Apps

Stripe is used for physical goods, services, and B2B payments where IAP is not required by platform policy.

Stripe iOS SDK and Android SDK—PaymentSheet for ready-made payment UI, PaymentSheetFlowController for custom UI with saved cards. Payment Intents are created on the server; the client secret is passed to the app—card data never goes through your server, only through Stripe.

Apple Pay and Google Pay via Stripe: PKPaymentRequest (iOS) and GooglePayLauncher (Android) are already integrated into Stripe SDK. Apple Pay conversion rates are 1.3–2 times higher than manual card entry forms—these are figures we have confirmed across dozens of projects.

Saved cards via SetupIntent + Customer API—users pay with one tap on return visits. Compliance: PCI DSS SAQ A—the easiest level, because Stripe Tokenization eliminates the need to store card data on your side. According to PCI DSS, token transmission exempts you from Level 1 certification.

3DS2 (Strong Customer Authentication) is mandatory for payments in the EU under PSD2. Stripe handles it automatically via PaymentIntent.confirmPayment, but you need to correctly handle the .requiresAction status and return the user to the appropriate screen after authentication.

What Is Included in the Work (Deliverables)

Process and Timeline

We start by clarifying the business model: subscriptions, one-time purchases, consumables, freemium. The architecture depends on this. Testing IAP requires Sandbox accounts (Apple) and License Testers (Google)—this is a separate environment setup.

Apple's Sandbox behaves differently from production: subscriptions renew every 5 minutes instead of monthly, inGracePeriod works differently. It is essential to test scenarios: trial expiration, cancellation, billing retry, refund.

The cost is calculated individually based on the set of tools and complexity of server-side logic. On average, we fit within a budget for a typical integration, but the savings from preventing errors and churn offset this investment within a few months.

Get a consultation for your project—contact us. We will help you choose the optimal payment architecture that passes store reviews and does not break under peak loads.