Android APIs
public abstract class

ChooserTargetService

extends Service
java.lang.Object
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ android.app.Service
         ↳ android.service.chooser.ChooserTargetService

Class Overview

A service that receives calls from the system when the user is asked to choose a target for an intent explicitly by another app. The calling app must have invoked ACTION_CHOOSER as handled by the system; applications do not have the ability to query a ChooserTargetService directly.

Which ChooserTargetServices are queried depends on a system-level policy decision made at the moment the chooser is invoked, including but not limited to user time spent with the app package or associated components in the foreground, recency of usage or frequency of usage. These will generally correlate with the order that app targets are shown in the list of intent handlers shown in the system chooser or resolver.

To extend this class, you must declare the service in your manifest file with the BIND_CHOOSER_TARGET_SERVICE permission and include an intent filter with the SERVICE_INTERFACE action. For example:

     <service android:name=".MyChooserTargetService"
             android:label="@string/service_name"
             android:permission="android.permission.BIND_CHOOSER_TARGET_SERVICE">
         <intent-filter>
             <action android:name="android.service.chooser.ChooserTargetService" />
         </intent-filter>
     </service>
 

For the system to query your service, you must add a <meta-data> element to the Activity in your manifest that can handle Intents that you would also like to provide optional deep links for. For example, a chat app might offer deep links to recent active conversations instead of invoking a generic picker after the app itself is chosen as a target.

The meta-data element should have the name android.service.chooser.chooser_target_service and a value corresponding to the component name of your service. Example:

     <activity android:name=".MyShareActivity"
             android:label="@string/share_activity_label">
         <intent-filter>
             <action android:name="android.intent.action.SEND" />
         </intent-filter>
         <meta-data android:name="android.service.chooser.chooser_target_service"
                 android:value=".MyChooserTargetService" />
     </activity>
 

Summary

Constants
String BIND_PERMISSION The permission that a ChooserTargetService must require in order to bind to it.
String META_DATA_NAME The name of the meta-data element that must be present on an activity element in a manifest to link it to a ChooserTargetService
String SERVICE_INTERFACE The Intent action that a ChooserTargetService must respond to
[Expand]
Inherited Constants
From class android.app.Service
From class android.content.Context
From interface android.content.ComponentCallbacks2
Public Constructors
ChooserTargetService()
Public Methods
IBinder onBind(Intent intent)
Return the communication channel to the service.
abstract List<ChooserTarget> onGetChooserTargets(ComponentName targetActivityName, IntentFilter matchedFilter)
Called by the system to retrieve a set of deep-link targets that can handle an intent.
[Expand]
Inherited Methods
From class android.app.Service
From class android.content.ContextWrapper
From class android.content.Context
From class java.lang.Object
From interface android.content.ComponentCallbacks2
From interface android.content.ComponentCallbacks

Constants

public static final String BIND_PERMISSION

Added in API level 23

The permission that a ChooserTargetService must require in order to bind to it. If this permission is not enforced the system will skip that ChooserTargetService.

Constant Value: "android.permission.BIND_CHOOSER_TARGET_SERVICE"

public static final String META_DATA_NAME

Added in API level 23

The name of the meta-data element that must be present on an activity element in a manifest to link it to a ChooserTargetService

Constant Value: "android.service.chooser.chooser_target_service"

public static final String SERVICE_INTERFACE

Added in API level 23

The Intent action that a ChooserTargetService must respond to

Constant Value: "android.service.chooser.ChooserTargetService"

Public Constructors

public ChooserTargetService ()

Added in API level 23

Public Methods

public IBinder onBind (Intent intent)

Added in API level 23

Return the communication channel to the service. May return null if clients can not bind to the service. The returned IBinder is usually for a complex interface that has been described using aidl.

Note that unlike other application components, calls on to the IBinder interface returned here may not happen on the main thread of the process. More information about the main thread can be found in Processes and Threads.

Parameters
intent The Intent that was used to bind to this service, as given to Context.bindService. Note that any extras that were included with the Intent at that point will not be seen here.
Returns
  • Return an IBinder through which clients can call on to the service.

public abstract List<ChooserTarget> onGetChooserTargets (ComponentName targetActivityName, IntentFilter matchedFilter)

Added in API level 23

Called by the system to retrieve a set of deep-link targets that can handle an intent.

The returned list should be sorted such that the most relevant targets appear first. The score for each ChooserTarget will be combined with the system's score for the original target Activity to sort and filter targets presented to the user.

Important: Calls to this method from other applications will occur on a binder thread, not on your app's main thread. Make sure that access to relevant data within your app is thread-safe.

Parameters
targetActivityName the ComponentName of the matched activity that referred the system to this ChooserTargetService
matchedFilter the specific IntentFilter on the component that was matched
Returns
  • a list of deep-link targets to fulfill the intent match, sorted by relevance