smart_cached_network_lottie

A Flutter package for caching Lottie animations with smart update detection and automatic format handling.

Features

• ✅ Smart Caching - Cache Lottie animations with ETag/Last-Modified based invalidation
• ✅ Format Detection - Automatically handles both .json and .lottie (dotLottie) formats
• ✅ Show-Cached-First - Display cached content immediately, check for updates asynchronously
• ✅ Image Asset Caching - Automatically caches referenced image assets
• ✅ Update Callbacks - Get notified when new versions are available

Getting Started

Add the dependency:

dependencies:
  smart_cached_network_lottie: ^1.0.0

Usage

Basic Usage

import 'package:smart_cached_network_lottie/smart_cached_network_lottie.dart';

SmartCachedNetworkLottie(
  url: 'https://example.com/animation.json',
  width: 200,
  height: 200,
  repeat: true,
)

With Update Detection

SmartCachedNetworkLottie(
  url: 'https://example.com/animation.lottie',
  width: 200,
  height: 200,
  repeat: true,
  
  // Enable automatic update checking (default: true)
  autoCheckForUpdates: true,
  
  // Called when an update is available
  onUpdateAvailable: () async {
    print('New version available!');
    return true; // Return true to apply, false to skip
  },
  
  // Called after update is applied
  onUpdate: () {
    print('Animation updated!');
  },
)

With Error Handling

SmartCachedNetworkLottie(
  url: 'https://example.com/animation.json',
  width: 200,
  height: 200,
  
  loadingBuilder: (context) => const CircularProgressIndicator(),
  
  errorBuilder: (context, error, stackTrace) {
    return Text('Failed to load: $error');
  },
)

Custom Cache Manager

SmartCachedNetworkLottie(
  url: 'https://example.com/animation.json',
  width: 200,
  height: 200,
  headers: {'Authorization': 'Bearer token'},
  cacheManager: SmartLottieCacheManager.custom(
    cacheKey: 'myCustomCache',
    stalePeriod: Duration(days: 14),
  ),
)

Manual Update Checking

final cacheManager = SmartLottieCacheManager.instance;

// Check if update is available
final result = await cacheManager.checkForUpdate(url);

if (result.hasUpdate) {
  // Force download the new version
  await cacheManager.downloadAndCache(url, forceDownload: true);
}

How Update Detection Works

The package uses HTTP conditional requests for efficient update checking:

1. First Download: Stores ETag and Last-Modified headers from the server
2. Update Check: Sends If-None-Match / If-Modified-Since headers
3. Server Response:
   • 304 Not Modified → Content unchanged, use cache
   • 200 OK → Content updated, re-download

Note: Your server must return ETag or Last-Modified headers. Most web servers and CDNs do this automatically.

Supported Formats

Format	Extension	Description
JSON	.json	Standard Lottie JSON format
dotLottie	.lottie	Compressed ZIP archive with animations and assets

Format is detected automatically using:

1. Magic bytes (most reliable)
2. Content-Type header
3. File extension (fallback)

API Reference

SmartCachedNetworkLottie

Main widget for displaying cached Lottie animations.

Property	Type	Description
url	String	URL of the Lottie animation
autoCheckForUpdates	bool	Whether to check for updates automatically (default: true)
onUpdate	VoidCallback?	Called when animation is updated
onUpdateAvailable	Future<bool> Function()?	Called when update available, return true to apply
headers	Map<String, String>?	HTTP headers for requests
cacheManager	BaseCacheManager?	Custom cache manager

Plus all standard Lottie widget properties (width, height, repeat, animate, etc.)

SmartLottieCacheManager

Cache manager with ETag/Last-Modified support.

Method	Description
checkForUpdate(url)	Check if remote file has been updated
getOrDownload(url)	Get from cache or download
downloadAndCache(url)	Download and cache file

License

MIT License - see LICENSE file for details.