On devices running Android 8.0 (API level 26) and higher, launchers that let users create[pinned shortcuts](https://developer.android.com/guide/topics/ui/shortcuts#shortcut-types)also let them pin widgets onto their home screen. Similar to pinned shortcuts, these*pinned widgets*give users access to specific tasks in your app and can be added to the home screen directly from the app, as shown in the following video.
![Example of responsive layout](https://developer.android.com/static/images/appwidgets/widget_pinning.gif)**Figure 2.**Example of pinning a widget.

## Let users pin a widget

In your app, you can create a request for the system to pin a widget onto a supported launcher by completing the following steps:

1. Make sure you[declare a widget in your app's manifest file](https://developer.android.com/guide/topics/appwidgets#Manifest).

2. Call the[`requestPinAppWidget()`](https://developer.android.com/reference/android/appwidget/AppWidgetManager#requestPinAppWidget(android.content.ComponentName,%20android.os.Bundle,%20android.app.PendingIntent))method, as shown in the following code snippet:

### Kotlin

```kotlin
val appWidgetManager = AppWidgetManager.getInstance(context)
val myProvider = ComponentName(context, ExampleAppWidgetProvider::class.java)

if (appWidgetManager.isRequestPinAppWidgetSupported()) {
    // Create the PendingIntent object only if your app needs to be notified
    // when the user chooses to pin the widget. Note that if the pinning
    // operation fails, your app isn't notified. This callback receives the ID
    // of the newly pinned widget (EXTRA_APPWIDGET_ID).
    val successCallback = PendingIntent.getBroadcast(
            /* context = */ context,
            /* requestCode = */ 0,
            /* intent = */ Intent(...),
            /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT)

    appWidgetManager.requestPinAppWidget(myProvider, null, successCallback)
}
```

### Java

```java
AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
ComponentName myProvider = new ComponentName(context, ExampleAppWidgetProvider.class);

if (appWidgetManager.isRequestPinAppWidgetSupported()) {
    // Create the PendingIntent object only if your app needs to be notified
    // when the user chooses to pin the widget. Note that if the pinning
    // operation fails, your app isn't notified. This callback receives the ID
    // of the newly pinned widget (EXTRA_APPWIDGET_ID).
    PendingIntent successCallback = PendingIntent.getBroadcast(
            /* context = */ context,
            /* requestCode = */ 0,
            /* intent = */ new Intent(...),
            /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT);

    appWidgetManager.requestPinAppWidget(myProvider, null, successCallback);
}
```
| **Note:** If your app doesn't need to be notified of whether the system successfully pins a widget onto a supported launcher, you can pass in`null`as the third argument to`requestPinAppWidget()`.

## Related design guidance

Users discover and add your widget through the widget picker or from within your app when the widget's functionality is most relevant. For more information, see[Discovery and promotion](https://developer.android.com/design/ui/mobile/guides/widgets/discovery-promotion).