# Download a Cloud Filter in iOS

> Request the iOS cloud catalog, show progress, apply the returned local package path, and reuse the cached filter.

> For AI agents: the complete documentation index is at https://nosmai.com/llms/effects.txt

Product: Nosmai Effects
Group: guide
Source: https://nosmai.com/docs/effects/guides/filters/download-a-cloud-filter/ios/

## Prerequisites

- A working [iOS quickstart](/docs/effects/quickstart/ios/)
- Cloud Filters enabled for the project

## Request the catalog

```objc
NosmaiCloudFilterRequestOptions *options =
    [NosmaiCloudFilterRequestOptions defaultOptions];
options.page = 1;
options.limit = 20;
options.version = NosmaiCloudFilterVersion2;
options.filterType = @"effects";

[[NosmaiCore shared].effects
    getCloudFiltersWithOptions:options
                    completion:^(NSArray<NSDictionary *> *filters,
                                 NosmaiCloudFilterPaginationInfo *pagination,
                                 NSError *error) {
  if (error != nil) NSLog(@"Catalog failed: %@", error.localizedDescription);
}];
```

## Download and apply

```objc
[[NosmaiCore shared].effects
    downloadCloudFilter:filterId
               progress:^(float progress) {
  NSLog(@"Download %.0f%%", progress * 100.0f);
} completion:^(BOOL success, NSString *localPath, NSError *error) {
  if (success && localPath.length > 0) {
    [[NosmaiCore shared].effects applyEffect:localPath completion:nil];
  }
}];
```

Deduplicate taps by cloud identifier and apply only the completion path.

## Handle cache eviction

Use `isCloudFilterDownloaded:` or `getCloudFilterLocalPath:` at the time of
selection. The cache has no documented permanent TTL and iOS can reclaim cache
storage. If the package is missing, download it again and replace the old path;
persist the cloud identifier rather than the filesystem location.

## Verify it worked

Apply the item again from cache after turning off network access. Do not issue a
new download for an already cached item.

## Common errors

| Symptom | Fix |
| --- | --- |
| Empty catalog | Check cloud capability, category, pagination, and request error |
| Download stops | Preserve the current effect, show Retry, and do not use a partial path |
| Apply fails | Pass the returned local path unchanged |

## Next steps

- [Understand Cloud Filters](/docs/effects/concepts/cloud-filters/)
- [Bundle a filter in iOS](/docs/effects/guides/filters/bundle-an-asset-store-filter/ios/)

## References

- [iOS platform guide](/docs/effects/platforms/ios/)