Consenti ad altre app di iniziare la tua attività

Se la tua app può eseguire un'azione che potrebbe essere utile a un'altra app, preparala a rispondere alle richieste di azioni specificando il filtro per intent appropriato nella tua attività.

Ad esempio, se crei un'app social in grado di condividere messaggi o foto con gli amici dell'utente, supporta l'intent ACTION_SEND. Poi, quando gli utenti avviano un'azione di "condivisione" da un'altra app, la tua app viene visualizzata come opzione nella finestra di dialogo del selettore (nota anche come finestra di dialogo di disambiguazione), come mostrato nella Figura 1.

Figura 1. La finestra di dialogo del selettore.

Per consentire ad altre app di avviare la tua attività in questo modo, devi aggiungere un <intent-filter> elemento nel file manifest per l'elemento <activity> corrispondente.

Quando la tua app viene installata su un dispositivo, il sistema identifica i filtri per intent e aggiunge le informazioni a un catalogo interno di intent supportati da tutte le app installate. Quando un'app chiama startActivity() o startActivityForResult() con un intent implicito, il sistema verifica la presenza di attività in grado di rispondere all'intent.

Aggiungere un filtro per intent

Per definire correttamente gli intent che la tua attività può gestire, rendi ogni filtro per intent che aggiungi il più specifico possibile in termini di tipo di azione e dati accettati dall'attività.

Il sistema potrebbe inviare un determinato Intent a un'attività se questa ha un filtro per intent che soddisfa i seguenti criteri dell'oggetto Intent:

Azione

Una stringa che indica l'azione da eseguire. In genere uno dei valori definiti dalla piattaforma, ad esempio ACTION_SEND o ACTION_VIEW.

Specifica questo valore nel filtro per intent con l'elemento <action>. Il valore specificato in questo elemento deve essere il nome della stringa completa per l'azione, anziché la costante API, come mostrato negli esempi in questa pagina.

Dati

Una descrizione dei dati associati all'intent.

Specifica questo valore nel filtro per intent con l'elemento <data>. Utilizzando uno o più attributi in questo elemento, puoi specificare il tipo MIME, un prefisso URI, uno schema URI o una combinazione di questi e altri che indicano il tipo di dati accettati.

Nota: se non devi dichiarare dettagli specifici sull'oggetto Uri dei dati, ad esempio quando la tua attività gestisce altri tipi di dati "extra" anziché un URI, specifica solo l'attributo android:mimeType per dichiarare il tipo di dati gestiti dalla tua attività, ad esempio text/plain o image/jpeg.

Categoria

Fornisce un modo aggiuntivo per caratterizzare l'attività che gestisce l'intent, in genere correlato all'attivazione dall'utente o alla posizione da cui viene avviata. Esistono diverse categorie supportate dal sistema, ma la maggior parte viene utilizzata raramente. Tuttavia, per impostazione predefinita, tutti gli intent impliciti sono definiti con CATEGORY_DEFAULT.

Specifica questo valore nel filtro per intent con l'<category> elemento.

Nel filtro per intent, puoi dichiarare i criteri accettati dalla tua attività dichiarandoli ciascuno con gli elementi XML corrispondenti nidificati nell'elemento <intent-filter>.

Ad esempio, ecco un'attività con un filtro per intent che gestisce l'intent ACTION_SEND quando il tipo di dati è testo o un'immagine:

<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>

Suggerimento: se vuoi che l'icona nella finestra di dialogo del selettore sia diversa dall'icona predefinita dell'attività, aggiungi android:icon nell'elemento <intent-filter>.

Ogni intent in entrata specifica una sola azione e un solo tipo di dati, ma è possibile dichiarare più istanze degli elementi <action>, <category> e <data> in ogni <intent-filter>.

Se due coppie di azione e dati si escludono a vicenda nei loro comportamenti, crea filtri per intent separati per specificare quali azioni sono accettabili quando sono abbinate a quali tipi di dati.

Supponiamo, ad esempio, che la tua attività gestisca sia testo sia immagini per gli intent ACTION_SEND e ACTION_SENDTO. In questo caso, devi definire due filtri per intent separati per le due azioni, perché un intent ACTION_SENDTO deve utilizzare l'oggetto Uri dei dati per specificare l'indirizzo del destinatario utilizzando lo schema URI send o sendto. Questo è mostrato nell'esempio seguente:

<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>

Nota: per ricevere intent impliciti, devi includere la categoria CATEGORY_DEFAULT nel filtro per intent. I metodi startActivity() e startActivityForResult() trattano tutti gli intent come se avessero dichiarato la categoria CATEGORY_DEFAULT. Se non la dichiari nel filtro per intent, nessun intent implicito viene risolto nella tua attività.

Per ulteriori informazioni sull'invio e la ricezione di ACTION_SEND intent che eseguono comportamenti di condivisione social, consulta Ricevere dati semplici da altre app. Puoi anche trovare informazioni utili sulla condivisione dei dati in Condividere dati semplici e Condividere file.

Gestire l'intent nell'attività

Per decidere quale azione intraprendere nella tua attività, leggi l'Intent utilizzato per avviarla.

Quando l'attività viene avviata, chiama getIntent() per recuperare Intent che l'ha avviata. Puoi farlo in qualsiasi momento durante il ciclo di vita dell'attività, ma in genere durante i primi callback, ad esempio onCreate() o onStart().

Questo è mostrato nell'esempio seguente:

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
    }
}

Restituire un risultato

Se vuoi restituire un risultato all'attività che ha richiamato la tua, chiama setResult() per specificare il codice del risultato e l'Intent del risultato. Al termine dell'operazione e quando l'utente torna all'attività originale, chiama finish() per chiudere ed eliminare la tua attività. Questo è mostrato nell'esempio seguente:

// 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();

Devi sempre specificare un codice del risultato con il risultato. In genere, è RESULT_OK o RESULT_CANCELED. Se necessario, puoi fornire dati aggiuntivi con un Intent.

Nota: per impostazione predefinita, il risultato è impostato su RESULT_CANCELED. Pertanto, se l'utente tocca il pulsante Indietro prima di completare l'azione e prima di impostare il risultato, l'attività originale riceve il risultato "annullato".

Se devi semplicemente restituire un numero intero che indica una delle diverse opzioni di risultato, puoi impostare il codice del risultato su qualsiasi valore maggiore di 0. Se utilizzi il codice del risultato per fornire un numero intero e non devi includere l'Intent, puoi chiamare setResult() e passare solo un codice del risultato:

setResult(RESULT_COLOR_RED)
finish()

setResult(RESULT_COLOR_RED);
finish();

In questo caso, potrebbero esserci solo pochi risultati possibili, quindi il codice del risultato è un numero intero definito localmente (maggiore di 0). Questo funziona bene quando restituisci un risultato a un'attività nella tua app, perché l'attività che riceve il risultato può fare riferimento alla costante pubblica per determinare il valore del codice del risultato.

Nota: non è necessario verificare se l'attività è stata avviata con startActivity() o startActivityForResult(). Chiama semplicemente setResult() se l'intent che ha avviato l'attività potrebbe prevedere un risultato. Se l'attività di origine ha chiamato startActivityForResult(), il sistema fornisce il risultato fornito a setResult(); in caso contrario, il risultato viene ignorato.