# Add stickers and AR overlays in iOS

> Pin images and animated GIFs to tracked face landmarks, or apply authored masks and 3D overlays through Cloud Filters.

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

Product: Nosmai Effects
Platform: iOS
SDK version: 3.0.7
Group: guide
Source: https://nosmai.com/docs/effects/guides/stickers-and-ar-overlays/overview/ios/

Available platform versions:
- iOS: https://nosmai.com/docs/effects/guides/stickers-and-ar-overlays/overview/ios.md
- Android: https://nosmai.com/docs/effects/guides/stickers-and-ar-overlays/overview/android.md
- Web: https://nosmai.com/docs/effects/guides/stickers-and-ar-overlays/overview/web.md
- React Native: https://nosmai.com/docs/effects/guides/stickers-and-ar-overlays/overview/react-native.md
- Flutter: https://nosmai.com/docs/effects/guides/stickers-and-ar-overlays/overview/flutter.md



> **Note**
>
> **Feature access**
>
> Runtime face stickers use the mobile AR overlay slot. Authored masks and 3D
> content also require AR Effects and Cloud Filters to be enabled for the project
> in [Nosmai Console](https://console.nosmai.com/).

## Prerequisites

- A working [iOS quickstart](/docs/effects/quickstart/ios/)
- A compatible camera preview
- AR Effects and Cloud Filters enabled for authored overlays

## What a face sticker is

A face sticker is a PNG, JPEG, or animated GIF that your app pins to one of
nine points on the face. Nosmai Effects tracks the face every frame, so the
sticker moves, scales, and tilts with the head.

![Diagram of a face with nine sticker anchor points: above head, forehead, right eye, left eye, eyes, center, nose, mouth, and chin](/images/docs/face-sticker-anchors.webp)

## Choose the content type

| Type | Use it for | Source |
| --- | --- | --- |
| Runtime face sticker | A PNG, JPEG, or animated GIF supplied by the application | `UIImage` or encoded image data |
| Authored AR overlay | Face masks, particles, animated props, and 3D content | A compatible Cloud Filter package |

## Add a runtime face sticker

Use a named face anchor so the sticker follows the intended landmark. A
`UIImage` displays a still image; use encoded data when an animated GIF must
retain its animation.

```objc
UIImage *sticker = [UIImage imageNamed:@"heart.png"];
BOOL applied = [[NosmaiSDK sharedInstance]
    setFaceSticker:sticker
             anchor:NosmaiFaceStickerAnchorForehead];

if (!applied) {
  NSLog(@"Face sticker could not be applied");
}
```

For an animated GIF:

```objc
NSURL *url = [[NSBundle mainBundle] URLForResource:@"sparkles"
                                     withExtension:@"gif"];
NSData *data = [NSData dataWithContentsOfURL:url];
BOOL applied = [[NosmaiSDK sharedInstance]
    setFaceStickerData:data
                anchor:NosmaiFaceStickerAnchorAboveHead];
```

Available anchors include the face centre, forehead, above the head, either
eye, both eyes, nose, mouth, and chin.

## Adjust placement

Offsets and scale are relative to the tracked face, so the placement remains
stable as the face moves closer to or farther from the camera.

```objc
[[NosmaiSDK sharedInstance]
    setFaceStickerAnchor:NosmaiFaceStickerAnchorNose
                 offsetX:0.0f
                 offsetY:0.05f
                   scale:0.4f
             rotationDeg:0.0f
                 opacity:1.0f];
```

Keep `opacity` between `0.0` and `1.0`. Pass `scale <= 0` when applying a
sticker to use the selected anchor's default size.

## Remove the sticker

```objc
if ([NosmaiSDK sharedInstance].isFaceStickerActive) {
  [[NosmaiSDK sharedInstance] clearFaceSticker];
}
```

## Apply an authored or 3D overlay

Select an approved `effect` package from Cloud Filters, download it, and apply
the resulting local package path. The package owns its face tracking, assets,
animation, triggers, particles, and 3D content.

```objc
[[NosmaiCore shared].effects
    applyEffect:packagePath
     completion:^(BOOL success, NSError *error) {
  if (!success) NSLog(@"AR overlay failed: %@", error.localizedDescription);
}];
```

Runtime face stickers and authored AR effects share the AR overlay slot. The
most recently applied item replaces the previous item in that slot.

## Verify

Test the sticker or overlay with face loss and return, head rotation, fast
movement, different face distances, both cameras, and device rotation.

## Common errors

| Symptom | Fix |
| --- | --- |
| Animated GIF displays only its first frame | Pass the original encoded GIF through `setFaceStickerData`, not a `UIImage` |
| Sticker jumps after a placement update | Use the same anchor for placement that was used when applying the sticker |
| Sticker disappears after applying a mask | Both use the AR overlay slot; apply the item that should remain visible last |

## Next steps

- [Add an AR face mask in iOS](/docs/effects/guides/effects/add-an-ar-mask/ios/)
- [Download a Cloud Filter in iOS](/docs/effects/guides/filters/download-a-cloud-filter/ios/)
- [Read the iOS API reference](/docs/effects/reference/api/ios/)

## References

- [iOS installation guide](/docs/effects/installation/ios/)
- [Cloud Filters](/docs/effects/concepts/cloud-filters/)
