# Add stickers and AR overlays in Android

> Attach 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: Android
SDK version: 3.0.7
Group: guide
Source: https://nosmai.com/docs/effects/guides/stickers-and-ar-overlays/overview/android/

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 [Android quickstart](/docs/effects/quickstart/android/)
- A compatible camera preview; runtime stickers require the supported SDK preview path
- 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 | `Bitmap` or encoded image bytes |
| Authored AR overlay | Face masks, particles, animated props, and 3D content | A compatible Cloud Filter package |

## Add a runtime face sticker

Use a named anchor so the sticker follows the intended face landmark.

```java
Bitmap sticker = BitmapFactory.decodeResource(
    getResources(), R.drawable.heart_sticker);

boolean applied = NosmaiSDK.setFaceSticker(
    sticker,
    NosmaiEffects.FaceStickerAnchor.FOREHEAD);

if (!applied) {
    Log.e("Camera", "Face sticker could not be applied");
}
```

A `Bitmap` contains only a still image. For an animated GIF, pass the original
encoded file bytes so the SDK can preserve its frames and timing.

```java
byte[] gifBytes = readAssetBytes("stickers/sparkles.gif");
boolean applied = NosmaiSDK.setFaceSticker(
    gifBytes,
    NosmaiEffects.FaceStickerAnchor.ABOVE_HEAD);
```

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

## Adjust placement

```java
NosmaiSDK.setFaceStickerPlacement(
    NosmaiEffects.FaceStickerAnchor.NOSE,
    0.0f,  // horizontal offset in face-width units
    0.05f, // vertical offset in face-height units
    0.4f,  // sticker width relative to face width
    0.0f,  // clockwise rotation in degrees
    1.0f   // opacity
);
```

Keep opacity between `0.0f` and `1.0f`. Pass a non-positive scale while
applying the sticker to use the selected anchor's default size.

## Remove the sticker

```java
if (NosmaiSDK.isFaceStickerActive()) {
    NosmaiSDK.clearFaceSticker();
}
```

## Apply an authored or 3D overlay

Select an approved `effect` package from Cloud Filters, download it, and apply
the returned local package path.

```java
NosmaiEffects.applyEffect(packagePath, new NosmaiEffects.EffectCallback() {
    @Override public void onSuccess() {
        // The authored overlay is active.
    }

    @Override public void onError(String message) {
        Log.e("Camera", message);
    }
});
```

The package contains its own tracking configuration, visual assets, animation,
triggers, particles, and 3D content. Runtime face stickers and authored AR
effects share the AR overlay slot, so the last applied item replaces the
previous item.

> **Warning**
>
> Runtime face stickers are not available through Android's external frame
> pipeline. Use the supported SDK preview path, or use a compatible authored
> effect package for a custom frame integration.

## Verify

Test face loss and return, fast head movement, different face distances, both
cameras, rotation, and repeated preview start and stop.

## Common errors

| Symptom | Fix |
| --- | --- |
| Animated GIF is static | Pass the original GIF bytes instead of decoding the file into a `Bitmap` |
| Sticker does not appear in an external-frame session | Runtime stickers require the supported preview path; use an authored package where applicable |
| 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 Android](/docs/effects/guides/effects/add-an-ar-mask/android/)
- [Download a Cloud Filter in Android](/docs/effects/guides/filters/download-a-cloud-filter/android/)
- [Read the Android API reference](/docs/effects/reference/api/android/)

## References

- [Android installation guide](/docs/effects/installation/android/)
- [Cloud Filters](/docs/effects/concepts/cloud-filters/)
