Contact search
Contact search provider plugins need to extend the ContactProvider
class:
class MyContactSearchPlugin() : ContactProvider(
QueryPluginConfig()
)
In the super constructor call, pass a QueryPluginConfig
object.
Plugin config
Search plugins have the following configuration properties:
storageStrategy
: Describes how the launcher should store a search result in its internal database. This is relevant when a user pins a search result to favorites, or when they assign a tag or custom label. In these situations, the launcher needs to be able to restore the search result from its database. There are two different strategies:StorageStrategy.StoreCopy
(default): The launcher stores all relevant information about this search result in its own internal database. The result can be restored without querying the plugin again. The launcher will try refresh the search result at its own discretion (e.g. when a user long-presses a restored search result to view its details). This strategy is the default and should be used whenever the plugin can't restore a search result immediately. It is best suited for online search plugins.StorageStrategy.StoreReference
: The launcher only stores the ID of the search result, and the plugin that created it. To restore a result, the plugin is queried again. This allows the plugin to update key fields (i.e. the label) immediately. However, plugins that use this strategy must guarantee, that they can restore a search result at any time, in a timely manner. In particular, the plugin must be able to restore a search result without any network requests. This strategy is best suited for on-device search plugins.
Search contacts
To implement contact search, override
suspend fun search(query: String, params: SearchParams): List<Contact>
query
is the search termparams
provides additional parameters for the search:allowNetwork
is a flag that indicates whether the user has enabled online search for this query. Plugins are generally advised to respect this request. This flag exists mainly for privacy reasons: the majority of searches target offline results (like apps, or contacts). Sending every single search request to external servers is overkill and can be a privacy issue. (Besides, it's not very nice to overload servers with unnecessary requests.) To reduce the amount of data that is sent to external servers, users can control, whether a search should include online results or not.lang
is the current language of the launcher. This can differ from the system language, as the user can set a different language per app. This value should be used for any localization in the search results.
search
returns a list of Contact
s. The list can be empty if no results were found.
The Contact
object
A Contact
has the following properties:
id
: A unique and stable identifier for this contact. This is used to track usage stats so if two contacts are identical, they must have the same ID, and if they are different, they need to have different IDs.uri
: A URI that is used to open the contact.name
: The display name of this concact. First name + last name, if applicable.photoUri
: Uri to a contact photo. Ifnull
, a default icon is used.phoneNumbers
: A list of phone numbers for this contact. Can be an empty list.emailAddresses
: A list of email addresses for this contact. Can be an empty list.postalAddresses
: A list of postal addresses for this contact. Can be an empty list.customActions
: Custom actions to contact this person.
Custom actions
Custom actions are channels handled by third party apps to contact a person. This could be a message on Slack, a voice call on WhatsApp, or a video call on Microsoft Teams. A CustomContactAction
has the following properties:
label
: Label that describes the actionuri
: Uri that is passed the intent to start the actionmimeType
: Type that is passed to the intent to start the actionpackageName
: Package name of the receiver app. If the app is not installed, the action is ignored.
Refresh a contact
If you have set config.storageStrategy
to StorageStrategy.StoreCopy
, the launcher will periodically try to refresh the stored copy. This happens for example when a user long-presses a contact to view its details. To update the contact, you can override
suspend fun refresh(item: Contact, params: RefreshParams): Contact?
The stored contact will be replaced with the return value of this method. If the contact is no longer available, it should return null
. In this case, the launcher will remove it from its database. If the contact is temporarily unavailable, an exception should be thrown.
item
is the version that the launcher has currently storedparams
provides additional parameters:lang
is the current language of the launcher. This can differ from the system language, as the user can set a different language per app. This value should be used to localize the result.lastUpdated
the timestamp (in milliseconds) whenitem
was last updated. This should be used to determine if the item needs to be refreshed again. If you decide not to refresh the item, you should return the originalitem
parameter.
The default implementation returns item
without any changes.
Get a contact
If you have set config.storageStrategy
to StorageStrategy.StoreReference
, you must override
suspend fun get(id: String, params: GetParams): Contact?
This method is used to lookup a contact by its id
. If the contact is no longer available, it should return null
. In this case, the launcher will remove it from its database.
id
is the ID of the contact that is being requestedparams
provides additional parameters:lang
is the current language of the launcher. This can differ from the system language, as the user can set a different language per app. This value should be used to localize the result.
Plugin state
Some plugins need to be configured before they can be used. For example, users might need to connect an account, or provide an API key.
If your plugin has such requirements, you can override
suspend fun getPluginState(): PluginState
This method can either return PluginState.Ready
, or PluginState.SetupRequired
.
PluginState.Ready
can have a statustext
to describe what the plugin does in its current configuration. For example "Search {username}'s files on {service}". This overrides the plugin's description.PluginState.SetupRequired
needs to have asetupActivity
Intent that starts the setup. You can also provide amessage
to describe what kind of setup needs to be performed. For example "Sign in with {service} to search files on {service}"
IMPORTANT
This method is only meant to provide hints to the launcher's user interface. You should not rely on it as a safeguard for your other plugin methods. There is still a chance that your other plugin methods are called regardless of the return value of this method. Make sure to check your requirements in the other plugin methods as well.