Autoriser les autres applications à démarrer votre activité

Si votre application peut effectuer une action qui pourrait être utile à une autre, préparez-la à répondre aux requêtes d'action en spécifiant le filtre d'intent approprié dans votre activité.

Par exemple, si vous créez une application de réseau social qui peut partager des messages ou des photos avec les amis de l'utilisateur, prenez en charge l'intent ACTION_SEND. Ensuite, lorsque les utilisateurs lancent une action de partage à partir d'une autre application, celle-ci apparaît comme une option dans la boîte de dialogue du sélecteur (également appelée boîte de dialogue de sélection d'application), comme l'illustre la figure 1.

Figure 1 : Boîte de dialogue du sélecteur

Pour permettre à d'autres applications de démarrer votre activité de cette manière, vous devez ajouter un élément <intent-filter> à votre fichier manifeste pour l'élément <activity> correspondant.

Lorsque votre application est installée sur un appareil, le système identifie vos filtres d'intent et ajoute les informations à un catalogue interne d'intents compatibles avec toutes les applications installées. Lorsqu'une application appelle startActivity() ou startActivityForResult() avec un intent implicite, le système recherche les activités susceptibles de répondre à cet intent.

Ajouter un filtre d'intent

Pour définir correctement les intents que votre activité peut gérer, faites en sorte que chaque filtre d'intent que vous ajoutez soit aussi spécifique que possible en termes de type d'action et de données acceptées par l'activité.

Le système peut envoyer un élément Intent spécifique à une activité si celle-ci comporte un filtre d'intent répondant aux critères suivants de l'objet Intent :

Action

Chaîne indiquant l'action à effectuer. En général, l'une des valeurs définies par la plate-forme, comme ACTION_SEND ou ACTION_VIEW.

Indiquez-le dans votre filtre d'intent avec l'élément <action>. La valeur que vous spécifiez dans cet élément doit correspondre au nom complet de la chaîne de l'action, et non à la constante de l'API, comme indiqué dans les exemples de cette page.

Données

Description des données associées à l'intent.

Indiquez-le dans votre filtre d'intent avec l'élément <data>. À l'aide d'un ou plusieurs attributs dans cet élément, vous pouvez spécifier le type MIME, un préfixe d'URI, un schéma d'URI ou une combinaison de ces éléments et d'autres qui indiquent le type de données accepté.

Remarque : Si vous ne devez pas déclarer de détails spécifiques sur les données Uri (par exemple, lorsque votre activité traite un autre type de données "supplémentaires" au lieu d'un URI), spécifiez uniquement l'attribut android:mimeType pour déclarer le type de données traité par votre activité, comme text/plain ou image/jpeg.

Catégorie

Fournit un moyen supplémentaire de définir l'activité qui gère l'intent, généralement liée au geste utilisateur ou au lieu d'où elle a commencé. Le système accepte plusieurs catégories, mais la plupart sont rarement utilisées. Toutefois, tous les intents implicites sont définis avec CATEGORY_DEFAULT par défaut.

Indiquez-le dans votre filtre d'intent avec l'élément <category>.

Dans votre filtre d'intent, vous pouvez déclarer les critères acceptés par votre activité en déclarant chacun d'eux avec les éléments XML correspondants imbriqués dans l'élément <intent-filter>.

Par exemple, voici une activité avec un filtre d'intent qui gère l'intent ACTION_SEND lorsque le type de données est soit du texte, soit une image :

<activity android:name="ShareActivity">
    <intent-filter>
        <action android:name="android.intent.action.SEND"/>
        <category android:name="android.intent.category.DEFAULT"/>
        <data android:mimeType="text/plain"/>
        <data android:mimeType="image/*"/>
    </intent-filter>
</activity>

Conseil : Si vous souhaitez que l'icône de la boîte de dialogue du sélecteur soit différente de l'icône par défaut de votre activité, ajoutez android:icon à <intent-filter>.

Chaque intent entrant ne définit qu'une action et un type de données, mais vous pouvez déclarer plusieurs instances d'éléments <action>, <category> et <data> dans chaque <intent-filter>.

Si deux paires d'action et de données s'excluent mutuellement dans leurs comportements, créez des filtres d'intent distincts pour définir les actions acceptables lorsqu'elles sont associées aux types de données.

Supposons par exemple que votre activité gère à la fois le texte et les images pour les intents ACTION_SEND et ACTION_SENDTO. Dans ce cas, vous devez définir deux filtres d'intent distincts pour les deux actions, car un intent ACTION_SENDTO doit utiliser les données Uri pour préciser l'adresse du destinataire à l'aide du schéma d'URI send ou sendto. Ce processus est illustré dans l'exemple suivant :

<activity android:name="ShareActivity">
    <!-- Filter for sending text; accepts SENDTO action with sms URI schemes -->
    <intent-filter>
        <action android:name="android.intent.action.SENDTO"/>
        <category android:name="android.intent.category.DEFAULT"/>
        <data android:scheme="sms" />
        <data android:scheme="smsto" />
    </intent-filter>
    <!-- Filter for sending text or images; accepts SEND action and text or image data -->
    <intent-filter>
        <action android:name="android.intent.action.SEND"/>
        <category android:name="android.intent.category.DEFAULT"/>
        <data android:mimeType="image/*"/>
        <data android:mimeType="text/plain"/>
    </intent-filter>
</activity>

Remarque : Pour recevoir des intents implicites, vous devez inclure la catégorie CATEGORY_DEFAULT dans le filtre d'intent. Les méthodes startActivity() et startActivityForResult() traitent tous les intents comme s'ils avaient déclaré la catégorie CATEGORY_DEFAULT. Si vous ne la déclarez pas dans votre filtre d'intent, aucun intent implicite n'atteindra votre activité.

Pour en savoir plus sur l'envoi et la réception d'intents ACTION_SEND qui sont responsables des comportements de partage sur les réseaux sociaux, consultez la section Recevoir des données simples depuis d'autres applications. Vous trouverez également des informations utiles sur le partage de données dans Partager des données simples et Partager des fichiers.

Gérer l'intent de votre activité

Pour choisir l'action à effectuer, consultez l'Intent utilisé pour la démarrer.

Au début de votre activité, appelez getIntent() pour récupérer l'élément Intent qui a lancé l'activité. Vous pouvez le faire à tout moment au cours du cycle de vie de l'activité, mais il vaut généralement mieux le faire lors des premiers rappels, comme onCreate() ou onStart().

Ce processus est illustré dans l'exemple suivant :

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    setContentView(R.layout.main)

    val data: Uri? = intent?.data

    // Figure out what to do based on the intent type
    if (intent?.type?.startsWith("image/") == true) {
        // Handle intents with image data
    } else if (intent?.type == "text/plain") {
        // Handle intents with text
    }
}

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    setContentView(R.layout.main);

    // Get the intent that started this activity
    Intent intent = getIntent();
    Uri data = intent.getData();

    // Figure out what to do based on the intent type
    if (intent.getType().indexOf("image/") != -1) {
        // Handle intents with image data
    } else if (intent.getType().equals("text/plain")) {
        // Handle intents with text
    }
}

Renvoyer un résultat

Si vous souhaitez renvoyer un résultat à l'activité qui a appelé la vôtre, appelez setResult() pour préciser l'élément Intent de code du résultat et de résultat. Lorsque l'opération est terminée et que l'utilisateur retourne dans l'activité d'origine, appelez finish() pour fermer et détruire votre activité. Ce processus est illustré dans l'exemple suivant :

// Create intent to deliver some kind of result data
Intent("com.example.RESULT_ACTION", Uri.parse("content://result_uri")).also { result ->
    setResult(Activity.RESULT_OK, result)
}
finish()

// Create intent to deliver some kind of result data
Intent result = new Intent("com.example.RESULT_ACTION", Uri.parse("content://result_uri"));
setResult(Activity.RESULT_OK, result);
finish();

Vous devez toujours indiquer un code de résultat avec le résultat. Il s'agit en général de RESULT_OK ou de RESULT_CANCELED. Fournissez ensuite si nécessaire des données supplémentaires avec un élément Intent.

Remarque : Le résultat est défini par défaut sur RESULT_CANCELED. Ainsi, si l'utilisateur appuie sur le bouton Retour avant d'effectuer l'action et avant que vous ne définissiez le résultat, l'activité d'origine reçoit le résultat "Annulé".

Si vous devez simplement renvoyer un nombre entier indiquant l'une des possibilités de résultat, vous pouvez définir le code de résultat sur une valeur supérieure à 0. Si vous utilisez le code de résultat pour fournir un nombre entier et que vous n'avez pas besoin d'inclure l'élément Intent, vous pouvez appeler setResult() et ne transmettre qu'un code de résultat :

setResult(RESULT_COLOR_RED)
finish()

setResult(RESULT_COLOR_RED);
finish();

Dans ce cas, il peut n'y avoir que quelques résultats possibles. Le code de résultat est donc un nombre entier défini localement (supérieur à 0). Cela fonctionne bien lorsque vous renvoyez un résultat à une activité dans votre propre application, car l'activité qui reçoit le résultat peut mentionner la constante publique pour déterminer la valeur du code de résultat.

Remarque : Inutile de vérifier si votre activité a commencé par startActivity() ou startActivityForResult(). Il suffit d'appeler setResult() si l'intent qui a démarré votre activité peut s'attendre à un résultat. Si l'activité d'origine avait appelé startActivityForResult(), le système envoie le résultat que vous avez fourni à setResult() ; sinon le résultat est ignoré.