Feature access
Cloud Filters must be enabled for your Nosmai project before you can browse, download, cache, apply, or remove cloud-delivered effects. Review your project's enabled features in Nosmai Console.
Prerequisites
- A working Flutter quickstart
- Cloud Filters enabled for the project
- Successful SDK initialization before mounting the thumbnail widgets
Request the catalog
final filters = await NosmaiFlutter.instance.getCloudFilters( filterType: NosmaiCloudFilterType.effects, page: 1, limit: 20, );
Other typed values include filter, background, and beautyEffect.
Display catalog thumbnails
NosmaiFilterPreview displays a thumbnail for a filter or effect in a picker, list, or grid. It manages preview-image loading and available cached thumbnails. It can also obtain a preview from an already available local package when the preferred image source is unavailable.
Displaying a thumbnail may download its image. The widget does not download the effect package, apply a filter, or start the camera. A visible thumbnail therefore does not mean the effect itself is downloaded or active.
Display one thumbnail
Import the public package:
import 'package:flutter/material.dart'; import 'package:nosmai_effects_sdk/nosmai_effects_sdk.dart';
Pass a catalog item directly to the widget:
NosmaiFilterPreview( filter: filter, width: 80, height: 80, fit: BoxFit.cover, )
filter is a NosmaiFilter from a successful SDK catalog request. There is no need to extract or decode its preview field yourself.
Add a filter grid
Keep the filters list from the catalog request in application state. Fetch the catalog from the screen's initialization or refresh flow rather than from build.
Use the following widget inside a parent with a bounded height, such as an Expanded or a SizedBox:
class FilterThumbnailGrid extends StatelessWidget {
const FilterThumbnailGrid({
super.key,
required this.filters,
required this.onSelected,
});
final List<NosmaiFilter> filters;
final ValueChanged<NosmaiFilter> onSelected;
@override
Widget build(BuildContext context) {
if (filters.isEmpty) {
return const Center(child: Text('No filters available'));
}
return GridView.builder(
gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
crossAxisCount: 3,
crossAxisSpacing: 12,
mainAxisSpacing: 12,
childAspectRatio: 0.8,
),
itemCount: filters.length,
itemBuilder: (context, index) {
final filter = filters[index];
return InkWell(
onTap: () => onSelected(filter),
child: Column(
crossAxisAlignment: CrossAxisAlignment.stretch,
children: [
Expanded(
child: ClipRRect(
borderRadius: BorderRadius.circular(12),
child: NosmaiFilterPreview(
filter: filter,
fit: BoxFit.cover,
decodeSize: 256,
placeholder: (_) => const ColoredBox(
color: Color(0xFFEDEFF2),
child: Center(
child: SizedBox.square(
dimension: 20,
child: CircularProgressIndicator(strokeWidth: 2),
),
),
),
errorBuilder: (_) => const ColoredBox(
color: Color(0xFFEDEFF2),
child: Center(child: Icon(Icons.image_not_supported)),
),
),
),
),
const SizedBox(height: 8),
Text(
filter.displayName,
maxLines: 1,
overflow: TextOverflow.ellipsis,
textAlign: TextAlign.center,
),
],
),
);
},
);
}
}
The application owns onSelected. Connect it to the download and apply flow below when the user selects an item.
Customize the thumbnail
| Parameter | Purpose | Default |
|---|---|---|
filter | SDK catalog item whose preview should be displayed | Required |
width and height | Thumbnail layout dimensions in Flutter logical pixels | Parent constraints |
fit | How the decoded image fills the available space | BoxFit.cover |
alignment | Image alignment within its available space | Alignment.center |
decodeSize | Maximum decoded image dimension in pixels, clamped to 64 through 512 | 256 |
placeholder | WidgetBuilder used while the image loads | Built-in image placeholder |
errorBuilder | WidgetBuilder used when no usable preview is available | Built-in image placeholder |
placeholder and errorBuilder receive a BuildContext. They do not receive an exception or stack trace. Use decodeSize to match the intended thumbnail size; increasing the layout dimensions does not require a full-resolution image for every catalog item.
Caching and offline behavior
- Available cached previews can be reused when the picker is reopened.
- When an image source is unavailable, the widget can fall back to a preview inside an already available local package.
- A previously unseen cloud thumbnail may require network access. If no usable cached or local preview exists, the widget displays
errorBuilder. - Thumbnail storage is bounded and may be cleared or reclaimed. Treat it as a convenience cache rather than permanent storage.
- Thumbnail caching and effect-package downloading are separate operations. Check the SDK download result before applying an effect.
Keep SDK-provided identifiers and metadata with each NosmaiFilter. After a catalog refresh or package download, pass the updated item to the widget so it can use the current metadata and available preview sources.
Download and apply
final filter = filters.first;
final result = await NosmaiFlutter.instance.downloadCloudFilter(
filter.cloudIdentifier,
);
final path = result['path'] as String?;
if (path == null || path.isEmpty) {
throw StateError('Cloud Filter download returned no path');
}
await NosmaiFlutter.instance.applyEffect(path);
Remove a cached item only after an explicit user or product action:
await NosmaiFlutter.instance.removeCloudFilter( filter.cloudIdentifier, );
Handle cache eviction
Do not persist path as a permanent asset reference. The cache has no documented cross-platform TTL and the operating system can reclaim it. Query the SDK's downloaded state when the item is selected; if it is missing, call downloadCloudFilter again and use the new returned path.
Verify it worked
- Open the picker and confirm names and thumbnails load.
- Reopen it and confirm available cached thumbnails can be reused.
- Disable network access and check both previously loaded items and an item whose preview has never been loaded.
- Confirm that browsing thumbnails alone does not apply a filter.
- Select a filter and verify that the application's download/apply handler runs separately.
- Close and reopen the filter UI, then apply an already cached effect package with network disabled.
Common errors
| Symptom | Fix |
|---|---|
| Catalog is empty | Check cloud capability, type, and native key configuration |
| Returned path is null | Treat the download as failed and show Retry |
| Two downloads start | Store one Future per cloudIdentifier |
| Every item displays the error placeholder | Initialize the SDK first, check cloud feature access, and use current SDK catalog items |
| A thumbnail is missing offline | Its image cache may be unavailable and there may be no usable local package preview; keep the fallback visible |
| Grid reports an unbounded-height error | Give the grid a bounded parent, such as Expanded or a SizedBox |
| A thumbnail is visible but selecting the filter has no effect | Connect onSelected to the documented download and apply flow |