How to Deploy & Use airbnb/lottie-android

# Lottie for Android - Deployment & Usage Guide

## 1. Prerequisites

### For Library Integration
- **Android Studio**: Arctic Fox (2020.3.1) or later
- **JDK**: 8 or higher
- **Android SDK**: API level 21+ (Android 5.0)
- **Project Requirements**: 
  - Migrated to [AndroidX](https://developer.android.com/jetpack/androidx/) (required for Lottie 2.8.0+)
  - Gradle 7.0+ (compatible with Android Gradle Plugin 7.0+)

### For Library Development/Contributing
- **Android Studio Canary**: Required for building the library from source due to dependencies on latest Android Gradle Plugin canaries
- **Git**: For cloning the repository

## 2. Installation

### Option A: Adding Lottie to Your Android Project

Add the dependency to your app-level `build.gradle` (Groovy) or `build.gradle.kts` (Kotlin):

**Groovy:**
```groovy
dependencies {
  implementation 'com.airbnb.android:lottie:6.3.0'
  // For Jetpack Compose support:
  implementation 'com.airbnb.android:lottie-compose:6.3.0'
}

Kotlin DSL:

dependencies {
  implementation("com.airbnb.android:lottie:6.3.0")
  implementation("com.airbnb.android:lottie-compose:6.3.0")
}

Check Maven Central for the latest version.

Option B: Building from Source (Contributors)

git clone https://github.com/airbnb/lottie-android.git
cd lottie-android

Open in Android Studio Canary (stable versions may not work due to AGP version requirements).

3. Configuration

AndroidX Migration

Ensure your gradle.properties includes:

android.useAndroidX=true
android.enableJetifier=true

ProGuard/R8 Rules

Add to proguard-rules.pro if using minification:

-keep class com.airbnb.lottie.** { *; }
-dontwarn com.airbnb.lottie.**

Network Permissions (Optional)

If loading animations from URLs, add to AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />

Asset Structure

Place JSON animation files in:

• src/main/assets/ for direct asset loading
• src/main/res/raw/ for resource loading

4. Build & Run

Basic Implementation (XML)

Layout (res/layout/activity_main.xml):

<com.airbnb.lottie.LottieAnimationView
    android:id="@+id/animation_view"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    app:lottie_fileName="animation.json"
    app:lottie_autoPlay="true"
    app:lottie_loop="true" />

Activity/Fragment:

LottieAnimationView animationView = findViewById(R.id.animation_view);
// Programmatic control
animationView.setAnimation("animation.json");
animationView.playAnimation();

Jetpack Compose Implementation

import com.airbnb.lottie.compose.*

@Composable
fun Loader() {
    val composition by rememberLottieComposition(
        LottieCompositionSpec.RawRes(R.raw.animation)
    )
    val progress by animateLottieCompositionAsState(
        composition,
        iterations = LottieConstants.IterateForever
    )
    
    LottieAnimation(
        composition = composition,
        progress = { progress },
        modifier = Modifier.size(100.dp)
    )
}

Loading Methods

From LottieCompositionFactory, supported sources include:

// From assets
LottieCompositionFactory.fromAsset(context, "animation.json")
    .addListener(composition -> { /* use composition */ });

// From raw resource
LottieCompositionFactory.fromRawRes(context, R.raw.animation);

// From network (URL)
LottieCompositionFactory.fromUrl(context, "https://example.com/animation.json");

// From JSON string
LottieCompositionFactory.fromJsonString(jsonString, "cache_key");

// From file
LottieCompositionFactory.fromFile(context, "path/to/file.json");

Running Sample App

./gradlew :sample:installDebug

Or run the sample configuration from Android Studio.

5. Deployment

For Applications Using Lottie

Build release APK/AAB:

./gradlew assembleRelease
# or
./gradlew bundleRelease

Upload to Google Play Console via standard Android deployment流程.

For Library Maintainers (Publishing)

The library is published to Maven Central. To publish locally for testing:

./gradlew publishToMavenLocal

For official releases (requires credentials):

./gradlew publishReleasePublicationToMavenCentralRepository

6. Troubleshooting

AndroidX Migration Errors

Issue: Lottie 2.8.0 and above only supports projects that have been migrated to androidx Solution: Follow Google's migration guide or downgrade to Lottie 2.7.0.

Animation Not Rendering

Issue: Blank view or crash when loading animation Solutions:

• Verify JSON file is valid Bodymovin export from After Effects
• Check logcat for parsing errors in JsonUtf8Reader
• Ensure animation file is in assets/ or res/raw/ with correct path
• For network loading, verify internet permission and URL accessibility

Memory Issues

Issue: OutOfMemoryError with large animations Solutions:

• Enable hardware acceleration in AndroidManifest.xml: android:hardwareAccelerated="true"
• Reduce animation resolution in After Effects before export
• Use LottieCompositionFactory cache keys effectively to avoid reloading

Text Rendering Issues

Issue: Custom fonts not displaying (from TextLayer.java analysis) Solutions:

• Ensure fonts are bundled in assets and properly referenced in the JSON
• Use TextDelegate for dynamic text updates
• Verify font family names match exactly between After Effects and Android assets

Gradle Sync Failures (Contributors)

Issue: Plugin version incompatible Solution: Install Android Studio Canary build as specified in README. Stable Android Studio versions may not support the required Android Gradle Plugin canary versions used in development.

ProGuard Issues

Issue: Animation works in debug but not release Solution: Ensure ProGuard rules keep Lottie classes (see Configuration section).