How to Add SVGA Gifts to Android, iOS, Flutter and Web Apps with SVGAPlayer

To add SVGA gifts to an Android app, install SVGAPlayer Android from JitPack, put an SVGAImageView in your layout, decode the .svga file with SVGAParser and call startAnimation(). SVGAPlayer iOS (CocoaPods), the SVGA player Flutter package (svgaplayer_flutter) and SVGAPlayer Web (Web-Lite) follow the same load-then-play pattern, shown step by step below.

What do you need before you start?

• An SVGA file. Download a free sample gift from our SVGA Player page (the online player plays SVGA 2.x files only). The samples are SVGA 2.x files, which every player below can read. To follow along with the code, save Glossy Pink Lips as glossy-pink-lips.svga.
• A quick preview. Drop the file into the SVGA Player to check timing and size before you write code.
• The right library version. This guide uses SVGAPlayer-Android 2.6.1, SVGAPlayer-iOS 2.5.7, svgaplayer_flutter 2.2.0 and SVGAPlayer-Web-Lite 2.1.1 (npm svga), the latest published versions. The Android, iOS and Flutter repositories are archived, so those versions are final; the code still installs and runs. For current links to every player, start from the official SVGA docs.

How do you set up SVGAPlayer Android?

SVGAPlayer Android (SVGAPlayer-Android) draws the animation natively on an Android Canvas. It reads both SVGA 1.x and 2.x files and can play the sound inside 2.x files.

Step 1: Add the JitPack repository

The library is hosted on JitPack. In settings.gradle.kts:

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://jitpack.io") }
    }
}

Step 2: Add the SVGAPlayer-Android dependency

In app/build.gradle.kts:

dependencies {
    implementation("com.github.yyued:SVGAPlayer-Android:2.6.1")
}

(The README shows compile '…:latest'. Pin the version instead, and use implementation, because current Gradle versions removed compile.)

Step 3: Keep the Protobuf classes in release builds

If you use R8/ProGuard, add the rules from the library README to proguard-rules.pro:

-keep class com.squareup.wire.** { *; }
-keep class com.opensource.svgaplayer.proto.** { *; }

Step 4: Add an SVGAImageView to your layout

Copy glossy-pink-lips.svga into app/src/main/assets/. Then add the view, set to play once, wait for your code, and clear its last frame when done:

<com.opensource.svgaplayer.SVGAImageView
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:id="@+id/giftView"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:autoPlay="false"
    app:loopCount="1"
    app:fillMode="Clear" />

loopCount 0 means loop forever (useful for avatar frames); 1 plays once (right for gifts). fillMode can be Forward (stop on the last frame), Backward (stop on the first frame) or Clear.

Step 5: Load and play the gift

import com.opensource.svgaplayer.SVGAImageView
import com.opensource.svgaplayer.SVGAParser
import com.opensource.svgaplayer.SVGAVideoEntity

val giftView = findViewById<SVGAImageView>(R.id.giftView)
val parser = SVGAParser(this)

parser.decodeFromAssets("glossy-pink-lips.svga", object : SVGAParser.ParseCompletion {
    override fun onComplete(videoItem: SVGAVideoEntity) {
        giftView.setVideoItem(videoItem)
        giftView.startAnimation()
    }

    override fun onError() {
        // Log it and skip this gift
    }
})

Decoding runs on a background thread, and the library posts onComplete and onError back to the main thread, so you can touch the view directly. To load from your server instead, call parser.decodeFromURL(URL("https://your-cdn.example/gifts/glossy-pink-lips.svga"), callback) with java.net.URL. SVGAParser does not manage an HTTP cache itself; the README recommends installing HttpResponseCache in Application.onCreate():

import android.net.http.HttpResponseCache
import java.io.File

val cacheDir = File(applicationContext.cacheDir, "http")
HttpResponseCache.install(cacheDir, 1024 * 1024 * 128)

Step 6: React when the gift finishes

import com.opensource.svgaplayer.SVGACallback

giftView.callback = object : SVGACallback {
    override fun onPause() {}
    override fun onFinished() {
        // Gift done: hide the view or play the next gift in the queue
    }
    override fun onRepeat() {}
    override fun onStep(frame: Int, percentage: Double) {}
}

Sound in 2.x files plays automatically. To control volume, call SVGASoundManager.init() once, then SVGASoundManager.setVolume(0.5f); pass a SVGAVideoEntity as the second argument to change only that animation.

How do you set up SVGAPlayer iOS?

SVGAPlayer iOS (SVGAPlayer-iOS) renders with Core Animation. Like the Android player, it reads 1.x and 2.x files and plays audio from 2.x files.

Step 1: Install SVGAPlayer with CocoaPods

In your Podfile:

target 'MyApp' do
  use_frameworks!
  pod 'SVGAPlayer', '~> 2.5'
end

Run pod install and open the .xcworkspace. The pod depends on SSZipArchive and Protobuf (~> 3.4); if another pod in your project needs a newer Protobuf major version, resolve that conflict first.

Step 2: Add the .svga file to your app

Drag glossy-pink-lips.svga into Xcode and tick your app target, so it's copied into the main bundle.

Step 3: Load and play the gift in Swift

import UIKit
import SVGAPlayer

final class GiftViewController: UIViewController {
    private let player = SVGAPlayer(frame: .zero)
    private let parser = SVGAParser()

    override func viewDidLoad() {
        super.viewDidLoad()
        player.frame = view.bounds
        player.loops = 1               // 0 = loop forever
        player.clearsAfterStop = true  // remove the last frame when done
        view.addSubview(player)

        parser.parse(withNamed: "glossy-pink-lips", in: nil, completionBlock: { [weak self] videoItem in
            self?.player.videoItem = videoItem
            self?.player.startAnimation()
        }, failureBlock: { error in
            print("SVGA parse failed: \(error)")
        })
    }
}

Pass the file name without the .svga extension; in: nil means the main bundle. For a remote file, use parser.parse(with: url, completionBlock:failureBlock:); in that call videoItem is optional, so unwrap it before assigning. Completion blocks are delivered on the main queue. To know when a gift ends, set player.delegate and implement the optional SVGAPlayerDelegate method svgaPlayerDidFinishedAnimation:.

For Objective-C, the library README shows the same flow with parseWithNamed:inBundle:completionBlock:failureBlock:.

How do you set up the SVGA player Flutter package?

The SVGA player for Flutter is the svgaplayer_flutter package (SVGAPlayer-Flutter). It renders with a Flutter CustomPainter. It supports the SVGA 2.0 format only and has no audio playback, so 1.x files won't decode and sound in 2.x files is silent.

Step 1: Add svgaplayer_flutter

dependencies:
  svgaplayer_flutter: ^2.2.0

Version 2.2.0 requires http: ^0.13.3. If your app already depends on http 1.x, flutter pub get will report a version conflict that you need to resolve, for example with a fork or a dependency_overrides entry you've tested.

Step 2: Declare the asset

flutter:
  assets:
    - assets/gifts/glossy-pink-lips.svga

Step 3: Show a looping animation

SVGASimpleImage loads a file and repeats it forever, which suits avatar frames:

SVGASimpleImage(assetsName: 'assets/gifts/glossy-pink-lips.svga')

Use resUrl: 'https://…' instead of assetsName to load from a URL.

Step 4: Play a gift once with a controller

import 'package:flutter/material.dart';
import 'package:svgaplayer_flutter/svgaplayer_flutter.dart';

class GiftOverlay extends StatefulWidget {
  const GiftOverlay({super.key});

  @override
  State<GiftOverlay> createState() => _GiftOverlayState();
}

class _GiftOverlayState extends State<GiftOverlay>
    with SingleTickerProviderStateMixin {
  late final SVGAAnimationController _controller;

  @override
  void initState() {
    super.initState();
    _controller = SVGAAnimationController(vsync: this);
    _playGift();
  }

  Future<void> _playGift() async {
    final videoItem = await SVGAParser.shared
        .decodeFromAssets('assets/gifts/glossy-pink-lips.svga');
    if (!mounted) {
      videoItem.dispose();
      return;
    }
    _controller.videoItem = videoItem;
    await _controller.forward(); // plays once
    if (mounted) _controller.videoItem = null; // clears and releases it
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) => SVGAImage(_controller);
}

forward() plays once and repeat() loops. A decoded MovieEntity is released when the controller is disposed or its videoItem is replaced; set videoItem.autorelease = false if you want to reuse it, and call dispose() on it yourself later. To decode bytes you cached yourself, use SVGAParser.shared.decodeFromBuffer(bytes).

How do you set up SVGAPlayer Web?

For web pages and in-app webviews, use SVGAPlayer-Web-Lite, published on npm as svga. Unlike the archived players, it is still updated. Its README lists the limits: SVGA 2.x only, no sound, and browser support from Android 4.4 and iOS 9.

Step 1: Install SVGAPlayer-Web-Lite

npm i svga

Step 2: Play the gift once on a canvas

<canvas id="gift"></canvas>

import { Parser, Player } from 'svga'

const parser = new Parser()
const svga = await parser.load('/gifts/glossy-pink-lips.svga')

const player = new Player({
  container: document.getElementById('gift'),
  loop: 1 // 0 = loop forever (the default)
})
player.onEnd = () => player.clear()
await player.mount(svga)
player.start()

Run this inside an ES module or an async function. The older SVGAPlayer-Web (svgaplayerweb) is archived; use it only if you must play 1.x files or sound in a browser.

How do you play SVGA gifts in React Native?

React Native has no official SVGA player. The SVGA docs list one community library, react-native-svga-player by BANG88. It's a native view that wraps the same SVGAPlayer-Android and SVGAPlayer-iOS libraries used above. Check its age before you adopt it.

Which React Native SVGA libraries exist?

react-native-svga-player (npm react-native-svga-player, MIT licence):

• The latest npm release is 1.1.0, published in May 2021. Its peer dependencies are react ^16.8.1 and react-native >=0.60.0-rc.0 <1.0.x, so a current app will warn about the React version, and you need to test it.
• On Android it depends on com.github.yyued:SVGAPlayer-Android:2.6.1; on iOS it depends on the SVGAPlayer pod.
• It registers its view with requireNativeComponent, and its README doesn't mention the New Architecture. Test it in your app before you commit.
• The source prop takes a URL, or a file name in your Android assets or iOS bundle. The animation starts as soon as the file loads. Other props: loops, clearsAfterStop, onFinished, onFrame and onPercentage.

npm install react-native-svga-player --save

import SVGAPlayer from 'react-native-svga-player'

export function GiftOverlay({ onDone }) {
  return (
    <SVGAPlayer
      style={{ position: 'absolute', width: '100%', height: '100%' }}
      pointerEvents="none"
      source="https://your-cdn.example/gifts/glossy-pink-lips.svga"
      loops={1}
      onFinished={onDone}
    />
  )
}

Other community packages exist on npm, such as react-native-svga (last release 1.0.10, May 2021). Check each one's activity and native dependencies the same way.

The native-module fallback

If no library fits your React Native version, write a small native view yourself. On Android, wrap SVGAImageView and SVGAParser as shown in the Android steps above; on iOS, wrap SVGAPlayer and SVGAParser. Expose a source prop, a loop count and a finished event, and call the same release habits listed below when the view unmounts. Because the native players are archived, pin their versions as you would in a native app.

How should a live-streaming app play SVGA gifts?

The code above plays one file. In a live room, a few habits keep gifts smooth:

1. Queue gifts. Several viewers may send gifts at once. Keep a queue and start the next gift from the finished callback (onFinished on Android, svgaPlayerDidFinishedAnimation: on iOS, the forward() future in Flutter).
2. Play gifts once, loop frames. Use one loop for gifts and entry effects (entrance effects), and infinite loops for avatar frames. For how apps trigger and layer each type, see Entry effects and avatar frames explained.
3. Overlay, don't block. Place the player view above the video with a transparent background and touches passing through, so the host stays visible and controls keep working. If you're weighing a transparent-MP4 format instead, see SVGA vs VAP.
4. Download ahead. Fetch gift files when the gift panel loads, not when a gift is sent, and cache them (HttpResponseCache on Android; your own cache with decodeFromBuffer in Flutter).
5. Release memory. fillMode="Clear" and clearsAfterStop only clear the screen. To free the images, call clear() on Android's SVGAImageView, or set the player's videoItem to nil (iOS) or null (Flutter).
6. Test on low-end devices. Check the largest gifts in your panel on the slowest phone you support.

Need test files at scale? SVGA Gifts has gifts such as Golden Rose Gift, and the Entry Car Package bundles entry effects like Golden Rescue Helicopter.

How do you test SVGA playback before release?

Test with the files your users will receive, not only the sample:

1. Preview each new file in the SVGA Player, which plays SVGA 2.x files only, to catch damaged or 1.x files early.
2. Play every gift in your panel once on Android, iOS and (if you use them) Flutter and web, and confirm the finished callback fires so your queue moves on.
3. Send several gifts quickly in a test room to check queueing and memory.
4. Test with sound on and off, in the background and foreground, and on your oldest supported device.

Why isn't my SVGA file playing?

• Nothing happens on Android: check that SVGAParser has a context. Create it with SVGAParser(context), or call SVGAParser.shareParser().init(context) before using the shared parser; otherwise the library logs an error and returns without decoding.
• Release build crashes or shows nothing on Android: add the ProGuard rules from Step 3.
• The file fails in Flutter or on the web but works on Android or iOS: it's probably SVGA 1.x. The Flutter package and SVGAPlayer-Web-Lite support 2.x only.
• No sound: the Flutter package and SVGAPlayer-Web-Lite have no audio playback; on Android and iOS, check that the file actually contains audio and the device isn't muted.
• Still stuck: drop the file into our SVGA Player. It plays SVGA 2.x files only, so a file that fails there is likely 1.x or damaged.