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.
Prerequisites
- A working iOS quickstart
- 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.

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.
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:
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.
[[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
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.
[[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 |