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.