# Wallpaper APIs

### Overview

The Smart Launcher Wallpaper API is an Android library that lets third‑party apps notify Smart Launcher about the wallpaper a user has selected. It handles temporary file storage, permission management, and metadata sharing so you can integrate without additional manifest setup or custom providers.

### Benefits for Developers

* **Advanced visual effect** – Smart Launcher will be able to apply dynamic blur effects and other enhancements to the wallpapers you supply, ensuring the launcher showcases your content at its best.

| Before                                                              | After                                                               |
| ------------------------------------------------------------------- | ------------------------------------------------------------------- |
| <img src="/files/ZRoQixDbQKlhEw7ebe90" alt="" data-size="original"> | <img src="/files/g5YIvBc8tQ8N7e8s5OFS" alt="" data-size="original"> |

* **Built‑in attribution** – When users share their setups, Smart Launcher preserves your metadata (author, source, link) so you receive proper credit. This attribution flows through to social posts, helping your work reach new audiences.

| Before                                                              | After                                                               |
| ------------------------------------------------------------------- | ------------------------------------------------------------------- |
| <img src="/files/ssspQ3l8M6bXmDRN5reF" alt="" data-size="original"> | <img src="/files/j8UL0rhsZS03PF8ch17e" alt="" data-size="original"> |

### Quick Implementation Guide

{% stepper %}
{% step %}
**Add the dependency**

```kotlin
dependencies {
    implementation("net.smartlauncher:wallpaper-api:0.0.5")
}
```

{% endstep %}

{% step %}
**Go to the code that you use to apply your wallpapers**

First apply the wallpaper with `WallpaperManager`, then notify Smart Launcher with `SmartLauncherWallpaperApi.updateWallpaper`. This requires Smart Launcher **6.5.54 or later**.

```kotlin
// Both calls are usually made from a background thread, for example from a coroutine.
yourCoroutineScope.launch(Dispatchers.IO) {
    WallpaperManager.getInstance(this@MainActivity).setBitmap(bitmap)

    // You can already tell the user that the new wallpaper has been applied.
    val result = SmartLauncherWallpaperApi.updateWallpaper(
        context = this@MainActivity,
        bitmap = bitmap, // also Uri is supported
        which = WallpaperManager.FLAG_SYSTEM,
        metadata = SmartLauncherWallpaperApi.Metadata(
            author = "Jane Doe",
            link = "https://example.com/wallpaper/42",
            source = "Example App"
        )
    )
    // Useful for debugging
    Log.d(TAG, "SmartLauncherWallpaperAPI returned $result")
}
```

{% endstep %}

{% step %}
**You are done!**
{% endstep %}
{% endstepper %}

### Recommendations and common errors

✅ Run `WallpaperManager.setBitmap(...)` and `SmartLauncherWallpaperApi.updateWallpaper(...)` from a background thread, for example from a coroutine. They do not need to run on the same thread or the same coroutine scope, but `updateWallpaper(...)` must happen after the wallpaper has already been applied.

✅ After `WallpaperManager.setBitmap(...)` returns, you can already tell the user that the new wallpaper has been applied.

✅ You do not need to wait for `SmartLauncherWallpaperApi.updateWallpaper(...)` to return. You can launch it separately on another background thread if that fits your app better.

❌ **Do not call** `SmartLauncherWallpaperApi.updateWallpaper` before `WallpaperManager.getInstance(this).setBitmap(bitmap)`. Calling it first will not have any effect on the current wallpaper.

❌ If you are applying your wallpaper only to the lock screen, **do not call** `updateWallpaper`. Otherwise, your information will again be associated with the wrong wallpaper.

### **How to test it**

1. Verify you are running Smart Launcher 6.5.54 or higher
2. Launch your code, ensure **`SmartLauncherWallpaperApi.updateWallpaper` returns `Success`**
3. From Smart Launcher, open preferences, then select **Show your home screen**.

✅ If you see your current setup, the integration is working! Now, if you populated the metadata field, you should see them as part of the body text when you press the **Share** button.

🚨 If you get an error after selecting **Show your home screen**, something is wrong. Contact us for assistance.

***

### Library release notes

**0.0.5**

Breaking change: `SmartLauncherWallpaperApi.updateWallpaper` replaces the previous `saveWallpaper` method.

The new flow is to apply the wallpaper first with `WallpaperManager.setBitmap(...)`, then call `updateWallpaper(...)` afterwards. This unlocks the caller earlier because you do not need to postpone the wallpaper application until you receive the return value.

**0.0.4**

The library now uses WebP under the hood for improved performance

**0.0.3**

Initial public release


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.smartlauncher.net/work-with-smart-launcher/wallpaper-apis.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.