Notifiche locali in Android

Questa sezione illustra come implementare le notifiche locali in Xamarin.Android. Illustra i vari elementi dell'interfaccia utente di una notifica Android e illustra l'API coinvolta nella creazione e nella visualizzazione di una notifica.

Panoramica delle notifiche locali

Android offre due aree controllate dal sistema per visualizzare le icone di notifica e le informazioni di notifica all'utente. Quando una notifica viene pubblicata per la prima volta, la relativa icona viene visualizzata nell'area di notifica, come illustrato nello screenshot seguente:

Per ottenere informazioni dettagliate sulla notifica, l'utente può aprire il pannello delle notifiche (che espande ogni icona di notifica per visualizzare il contenuto delle notifiche) ed eseguire tutte le azioni associate alle notifiche. Lo screenshot seguente mostra un pannello di notifica corrispondente all'area di notifica visualizzata sopra:

Le notifiche Android usano due tipi di layout:

• Layout di base: formato di presentazione compatto e fisso.

• Layout espanso: un formato di presentazione che può espandersi fino a dimensioni maggiori per visualizzare altre informazioni.

Ognuno di questi tipi di layout (e come crearli) è illustrato nelle sezioni seguenti.

Nota

Questa guida è incentrata sulle API NotificationCompat dalla libreria di supporto android. Queste API garantiranno la massima compatibilità con le versioni precedenti di Android 4.0 (livello API 14).

Layout di base

Tutte le notifiche Android sono basate sul formato di layout di base, che include almeno gli elementi seguenti:

1. Icona di notifica, che rappresenta l'app di origine o il tipo di notifica se l'app supporta tipi diversi di notifiche.

2. Titolo della notifica o nome del mittente se la notifica è un messaggio personale.

3. Messaggio di notifica.

4. Timestamp.

Questi elementi vengono visualizzati come illustrato nel diagramma seguente:

I layout di base sono limitati a 64 pixel indipendenti dalla densità (dp) in altezza. Android crea questo stile di notifica di base per impostazione predefinita.

Facoltativamente, le notifiche possono visualizzare un'icona di grandi dimensioni che rappresenta l'applicazione o la foto del mittente. Quando un'icona di grandi dimensioni viene usata in una notifica in Android 5.0 e versioni successive, l'icona di notifica piccola viene visualizzata come badge sull'icona grande:

A partire da Android 5.0, le notifiche possono essere visualizzate anche nella schermata di blocco:

L'utente può toccare due volte la notifica della schermata di blocco per sbloccare il dispositivo e passare all'app che ha originato tale notifica o scorrere rapidamente per ignorare la notifica. Le app possono impostare il livello di visibilità di una notifica per controllare ciò che viene visualizzato nella schermata di blocco e gli utenti possono scegliere se consentire la visualizzazione di contenuti sensibili nelle notifiche della schermata di blocco.

Android 5.0 ha introdotto un formato di presentazione di notifica ad alta priorità denominato Heads-up. Le notifiche in testa si spostano verso il basso dalla parte superiore dello schermo per alcuni secondi e quindi riprendono fino all'area di notifica:

Le notifiche testa-up consentono all'interfaccia utente di sistema di inserire informazioni importanti davanti all'utente senza interrompere lo stato dell'attività attualmente in esecuzione.

Android include il supporto per i metadati delle notifiche in modo che le notifiche possano essere ordinate e visualizzate in modo intelligente. I metadati delle notifiche controllano anche la modalità di presentazione delle notifiche nella schermata di blocco e nel formato heads-up. Le applicazioni possono impostare i tipi di metadati di notifica seguenti:

• Priorità: il livello di priorità determina come e quando vengono presentate le notifiche. Ad esempio, in Android 5.0, le notifiche con priorità alta vengono visualizzate come notifiche di testa.

• Visibilità : specifica la quantità di contenuto della notifica da visualizzare quando la notifica viene visualizzata nella schermata di blocco.

• Categoria : informa il sistema come gestire la notifica in varie circostanze, ad esempio quando il dispositivo è in modalità Non disturbare .

Nota

Visibilità e categoria sono stati introdotti in Android 5.0 e non sono disponibili nelle versioni precedenti di Android. A partire da Android 8.0, i canali di notifica vengono usati per controllare la modalità di presentazione delle notifiche all'utente.

Layout espansi

A partire da Android 4.1, le notifiche possono essere configurate con stili di layout espansi che consentono all'utente di espandere l'altezza della notifica per visualizzare più contenuto. Ad esempio, l'esempio seguente illustra una notifica di layout espansa in modalità contrattata:

Quando questa notifica viene espansa, viene visualizzato l'intero messaggio:

Android supporta tre stili di layout espansi per le notifiche a evento singolo:

• Testo grande: in modalità contrattata, visualizza un estratto della prima riga del messaggio seguito da due punti. In modalità espansa visualizza l'intero messaggio (come illustrato nell'esempio precedente).

• Posta in arrivo : in modalità contrattata, visualizza il numero di nuovi messaggi. In modalità espansa, visualizza il primo messaggio di posta elettronica o un elenco dei messaggi nella posta in arrivo.

• Immagine : in modalità contrattata visualizza solo il testo del messaggio. In modalità espansa, visualizza il testo e un'immagine.

Oltre alla notifica di base (più avanti in questo articolo) viene illustrato come creare notifiche di Testo grande, Posta in arrivo e Immagine .

Canali di notifica

A partire da Android 8.0 (Oreo), è possibile usare la funzionalità canali di notifica per creare un canale personalizzabile dall'utente per ogni tipo di notifica da visualizzare. I canali di notifica consentono di raggruppare le notifiche in modo che tutte le notifiche inviate a un canale mostrino lo stesso comportamento. Ad esempio, potrebbe essere disponibile un canale di notifica destinato alle notifiche che richiedono un'attenzione immediata e un canale separato "più silenzioso" usato per i messaggi informativi.

L'app YouTube installata con Android Oreo elenca due categorie di notifica: Scarica notifiche e Notifiche generali:

Ognuna di queste categorie corrisponde a un canale di notifica. L'app YouTube implementa un canale Download Notifications e un canale di notifiche generali. L'utente può toccare Scarica notifiche, che visualizza la schermata delle impostazioni per il canale di notifiche di download dell'app:

In questa schermata l'utente può modificare il comportamento del canale Scarica notifiche eseguendo le operazioni seguenti:

• Impostare il livello di importanza su Urgente, Alto, Medio o Basso, che configura il livello di interruzione audio e visiva.

• Attivare o disattivare il punto di notifica.

• Accendere o disattivare la luce lampeggiante.

• Visualizzare o nascondere le notifiche nella schermata di blocco.

• Eseguire l'override dell'impostazione Non disturbare .

Il canale Notifiche generali ha impostazioni simili:

Si noti che non si ha il controllo assoluto sul modo in cui i canali di notifica interagiscono con l'utente: l'utente può modificare le impostazioni per qualsiasi canale di notifica nel dispositivo, come illustrato negli screenshot precedenti. Tuttavia, è possibile configurare i valori predefiniti (come descritto di seguito). Come illustrato in questi esempi, la nuova funzionalità dei canali di notifica consente di fornire agli utenti un controllo granulare su diversi tipi di notifiche.

Creazione di notifiche

Per creare una notifica in Android, usare la classe NotificationCompat.Builder dal pacchetto NuGet Xamarin.Android.Support.v4 . Questa classe consente di creare e pubblicare notifiche nelle versioni precedenti di Android. NotificationCompat.Builder viene inoltre discusso.

NotificationCompat.Builder fornisce metodi per impostare le varie opzioni in una notifica, ad esempio:

• Il contenuto, incluso il titolo, il testo del messaggio e l'icona di notifica.

• Stile della notifica, ad esempio Testo grande, Posta in arrivo o Stile immagine.

• Priorità della notifica: minimo, basso, predefinito, alto o massimo. In Android 8.0 e versioni successive, la priorità viene impostata tramite un canale di notifica.

• Visibilità della notifica nella schermata di blocco: pubblica, privata o segreta.

• Metadati di categoria che consentono ad Android di classificare e filtrare la notifica.

• Finalità facoltativa che indica un'attività da avviare quando viene toccata la notifica.

• ID del canale di notifica in cui verrà pubblicata la notifica (Android 8.0 e versioni successive).

Dopo aver impostato queste opzioni nel generatore, si genera un oggetto notifica che contiene le impostazioni. Per pubblicare la notifica, passare questo oggetto di notifica a Gestione notifiche. Android fornisce la classe NotificationManager , responsabile della pubblicazione delle notifiche e della relativa visualizzazione all'utente. Un riferimento a questa classe può essere ottenuto da qualsiasi contesto, ad esempio un'attività o un servizio.

Creazione di un canale di notifica

Le app in esecuzione in Android 8.0 devono creare un canale di notifica per le notifiche. Un canale di notifica richiede le tre informazioni seguenti:

• Stringa ID univoca per il pacchetto che identificherà il canale.
• Nome del canale che verrà visualizzato all'utente. Il nome deve essere compreso tra uno e 40 caratteri.
• Importanza del canale.

Le app dovranno controllare la versione di Android in esecuzione. I dispositivi che eseguono versioni precedenti a Android 8.0 non devono creare un canale di notifica. Il metodo seguente è un esempio di come creare un canale di notifica in un'attività:

void CreateNotificationChannel()
{
    if (Build.VERSION.SdkInt < BuildVersionCodes.O)
    {
        // Notification channels are new in API 26 (and not a part of the
        // support library). There is no need to create a notification
        // channel on older versions of Android.
        return;
    }

    var channelName = Resources.GetString(Resource.String.channel_name);
    var channelDescription = GetString(Resource.String.channel_description);
    var channel = new NotificationChannel(CHANNEL_ID, channelName, NotificationImportance.Default)
                  {
                      Description = channelDescription
                  };

    var notificationManager = (NotificationManager) GetSystemService(NotificationService);
    notificationManager.CreateNotificationChannel(channel);
}

Il canale di notifica deve essere creato ogni volta che viene creata l'attività. Per il CreateNotificationChannel metodo , deve essere chiamato nel OnCreate metodo di un'attività.

Creazione e pubblicazione di una notifica

Per generare una notifica in Android, seguire questa procedura:

1. Creare un oggetto NotificationCompat.Builder.

2. Chiamare vari metodi sull'oggetto NotificationCompat.Builder per impostare le opzioni di notifica.

3. Chiamare il metodo Build dell'oggetto per creare un'istanza NotificationCompat.Builder di un oggetto di notifica.

4. Chiamare il metodo Notify del gestore delle notifiche per pubblicare la notifica.

Per ogni notifica è necessario fornire almeno le informazioni seguenti:

• Icona piccola (dimensioni 24x24 dp)

• Titolo breve

• Testo della notifica

Nell'esempio di codice seguente viene illustrato come usare NotificationCompat.Builder per generare una notifica di base. Si noti che NotificationCompat.Builder i metodi supportano il concatenamento dei metodi, ovvero ogni metodo restituisce l'oggetto builder in modo da poter utilizzare il risultato dell'ultima chiamata al metodo per richiamare la chiamata al metodo successivo:

// Instantiate the builder and set notification elements:
NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
    .SetContentTitle ("Sample Notification")
    .SetContentText ("Hello World! This is my first notification!")
    .SetSmallIcon (Resource.Drawable.ic_notification);

// Build the notification:
Notification notification = builder.Build();

// Get the notification manager:
NotificationManager notificationManager =
    GetSystemService (Context.NotificationService) as NotificationManager;

// Publish the notification:
const int notificationId = 0;
notificationManager.Notify (notificationId, notification);

In questo esempio viene creata un'istanza di un nuovo NotificationCompat.Builder oggetto denominato builder insieme all'ID del canale di notifica da usare. Il titolo e il testo della notifica vengono impostati e l'icona di notifica viene caricata da Risorse/drawable/ic_notification.png. La chiamata al metodo del Build generatore di notifiche crea un oggetto notifica con queste impostazioni. Il passaggio successivo consiste nel chiamare il Notify metodo di Gestione notifiche. Per individuare gestione notifiche, chiamare GetSystemService, come illustrato in precedenza.

Il Notify metodo accetta due parametri: l'identificatore di notifica e l'oggetto notifica. L'identificatore di notifica è un numero intero univoco che identifica la notifica all'applicazione. In questo esempio, l'identificatore di notifica è impostato su zero (0); Tuttavia, in un'applicazione di produzione, è necessario assegnare a ogni notifica un identificatore univoco. Il riutilizzo del valore dell'identificatore precedente in una chiamata a Notify fa sì che l'ultima notifica venga sovrascritta.

Quando questo codice viene eseguito in un dispositivo Android 5.0, genera una notifica simile all'esempio seguente:

L'icona di notifica viene visualizzata sul lato sinistro della notifica: questa immagine di un "i" cerchiato ha un canale alfa in modo che Android possa disegnare uno sfondo circolare grigio dietro di esso. È anche possibile fornire un'icona senza un canale alfa. Per visualizzare un'immagine fotografica come icona, vedere Formato icona grande più avanti in questo argomento.

Il timestamp viene impostato automaticamente, ma è possibile eseguire l'override di questa impostazione chiamando il metodo SetWhen del generatore di notifiche. Nell'esempio di codice seguente, ad esempio, il timestamp viene impostato sull'ora corrente:

builder.SetWhen (Java.Lang.JavaSystem.CurrentTimeMillis());

Abilitazione del suono e della vibrazione

Se vuoi che la notifica riproducesse anche un suono, puoi chiamare il metodo SetDefaults del generatore di notifiche e passare il NotificationDefaults.Sound flag:

// Instantiate the notification builder and enable sound:
NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
    .SetContentTitle ("Sample Notification")
    .SetContentText ("Hello World! This is my first notification!")
    .SetDefaults (NotificationDefaults.Sound)
    .SetSmallIcon (Resource.Drawable.ic_notification);

Questa chiamata a SetDefaults causerà la riproduzione di un suono da parte del dispositivo quando viene pubblicata la notifica. Se vuoi che il dispositivo vibra invece di riprodurre un suono, puoi passare NotificationDefaults.Vibrate a SetDefaults. Se vuoi che il dispositivo riprodurre un suono e vibrare il dispositivo, puoi passare entrambi i flag a SetDefaults:

builder.SetDefaults (NotificationDefaults.Sound | NotificationDefaults.Vibrate);

Se si abilita l'audio senza specificare un suono da riprodurre, Android usa il suono di notifica di sistema predefinito. Tuttavia, è possibile modificare il suono che verrà riprodotto chiamando il metodo SetSound del generatore di notifiche. Ad esempio, per riprodurre il suono dell'allarme con la notifica (invece del suono di notifica predefinito), è possibile ottenere l'URI per il suono dell'allarme da RingtoneManager e passarlo a SetSound:

builder.SetSound (RingtoneManager.GetDefaultUri(RingtoneType.Alarm));

In alternativa, è possibile usare il suono suoneria predefinito del sistema per la notifica:

builder.SetSound (RingtoneManager.GetDefaultUri(RingtoneType.Ringtone));

Dopo aver creato un oggetto di notifica, è possibile impostare le proprietà di notifica nell'oggetto notifica anziché configurarle in anticipo tramite NotificationCompat.Builder i metodi. Ad esempio, invece di chiamare il SetDefaults metodo per abilitare la vibrazione su una notifica, è possibile modificare direttamente il flag di bit della proprietà Defaults della notifica:

// Build the notification:
Notification notification = builder.Build();

// Turn on vibrate:
notification.Defaults |= NotificationDefaults.Vibrate;

Questo esempio fa sì che il dispositivo vibra quando viene pubblicata la notifica.

Aggiornamento di una notifica

Se si desidera aggiornare il contenuto di una notifica dopo la pubblicazione, è possibile riutilizzare l'oggetto esistente NotificationCompat.Builder per creare un nuovo oggetto notifica e pubblicare questa notifica con l'identificatore dell'ultima notifica. Ad esempio:

// Update the existing notification builder content:
builder.SetContentTitle ("Updated Notification");
builder.SetContentText ("Changed to this message.");

// Build a notification object with updated content:
notification = builder.Build();

// Publish the new notification with the existing ID:
notificationManager.Notify (notificationId, notification);

In questo esempio l'oggetto esistente NotificationCompat.Builder viene usato per creare un nuovo oggetto di notifica con un titolo e un messaggio diversi. Il nuovo oggetto notifica viene pubblicato usando l'identificatore della notifica precedente e questo aggiorna il contenuto della notifica pubblicata in precedenza:

Il corpo della notifica precedente viene riutilizzato: solo il titolo e il testo della notifica cambia mentre la notifica viene visualizzata nel pannello delle notifiche. Il testo del titolo passa da "Notifica di esempio" a "Notifica aggiornata" e il testo del messaggio cambia da "Hello World! Questa è la mia prima notifica!" in "Modificato in questo messaggio".

Una notifica rimane visibile fino a quando non si verifica una delle tre operazioni seguenti:

• L'utente ignora la notifica o tocca Cancella tutto.

• L'applicazione effettua una chiamata a NotificationManager.Cancel, passando l'ID di notifica univoco assegnato al momento della pubblicazione della notifica.

• L'applicazione chiama NotificationManager.CancelAll.

Per altre informazioni sull'aggiornamento delle notifiche Android, vedere Modificare una notifica.

Avvio di un'attività da una notifica

In Android è comune associare una notifica a un'azione , ovvero un'attività avviata quando l'utente tocca la notifica. Questa attività può risiedere in un'altra applicazione o anche in un'altra attività. Per aggiungere un'azione a una notifica, creare un oggetto PendingIntent e associarlo PendingIntent alla notifica. Un PendingIntent è un tipo speciale di finalità che consente all'applicazione destinatario di eseguire una parte di codice predefinita con le autorizzazioni dell'applicazione di invio. Quando l'utente tocca la notifica, Android avvia l'attività specificata da PendingIntent.

Il frammento di codice seguente illustra come creare una notifica con un PendingIntent che avvierà l'attività dell'app di origine, MainActivity:

// Set up an intent so that tapping the notifications returns to this app:
Intent intent = new Intent (this, typeof(MainActivity));

// Create a PendingIntent; we're only using one PendingIntent (ID = 0):
const int pendingIntentId = 0;
PendingIntent pendingIntent =
    PendingIntent.GetActivity (this, pendingIntentId, intent, PendingIntentFlags.OneShot);

// Instantiate the builder and set notification elements, including pending intent:
NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
    .SetContentIntent (pendingIntent)
    .SetContentTitle ("Sample Notification")
    .SetContentText ("Hello World! This is my first action notification!")
    .SetSmallIcon (Resource.Drawable.ic_notification);

// Build the notification:
Notification notification = builder.Build();

// Get the notification manager:
NotificationManager notificationManager =
    GetSystemService (Context.NotificationService) as NotificationManager;

// Publish the notification:
const int notificationId = 0;
notificationManager.Notify (notificationId, notification);

Questo codice è molto simile al codice di notifica nella sezione precedente, ad eccezione del fatto che un PendingIntent oggetto viene aggiunto all'oggetto notifica. In questo esempio, l'oggetto PendingIntent è associato all'attività dell'app di origine prima che venga passata al metodo SetContentIntent del generatore di notifiche. Il PendingIntentFlags.OneShot flag viene passato al PendingIntent.GetActivity metodo in modo che PendingIntent venga usato una sola volta. Quando viene eseguito questo codice, viene visualizzata la notifica seguente:

Toccando questa notifica, l'utente torna all'attività di origine.

In un'app di produzione, l'app deve gestire lo stack indietro quando l'utente preme il pulsante Indietro all'interno dell'attività di notifica (se non si ha familiarità con le attività Android e lo stack indietro, vedere Attività e stack back). Nella maggior parte dei casi, spostarsi all'indietro dell'attività di notifica deve restituire l'utente dall'app e tornare alla schermata Home. Per gestire lo stack back, l'app usa la classe TaskStackBuilder per creare un PendingIntent oggetto con uno stack back.

Un'altra considerazione reale è che l'attività di origine potrebbe dover inviare dati all'attività di notifica. Ad esempio, la notifica può indicare che è arrivato un sms e l'attività di notifica (una schermata di visualizzazione di messaggi), richiede l'ID del messaggio per visualizzare il messaggio all'utente. L'attività PendingIntent che crea può usare il metodo Intent.PutExtra per aggiungere dati (ad esempio, una stringa) alla finalità in modo che questi dati vengano passati all'attività di notifica.

L'esempio di codice seguente illustra come usare TaskStackBuilder per gestire lo stack back e include un esempio di come inviare una singola stringa di messaggio a un'attività di notifica denominata SecondActivity:

// Setup an intent for SecondActivity:
Intent secondIntent = new Intent (this, typeof(SecondActivity));

// Pass some information to SecondActivity:
secondIntent.PutExtra ("message", "Greetings from MainActivity!");

// Create a task stack builder to manage the back stack:
TaskStackBuilder stackBuilder = TaskStackBuilder.Create(this);

// Add all parents of SecondActivity to the stack:
stackBuilder.AddParentStack (Java.Lang.Class.FromType (typeof (SecondActivity)));

// Push the intent that starts SecondActivity onto the stack:
stackBuilder.AddNextIntent (secondIntent);

// Obtain the PendingIntent for launching the task constructed by
// stackbuilder. The pending intent can be used only once (one shot):
const int pendingIntentId = 0;
PendingIntent pendingIntent =
    stackBuilder.GetPendingIntent (pendingIntentId, PendingIntentFlags.OneShot);

// Instantiate the builder and set notification elements, including
// the pending intent:
NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
    .SetContentIntent (pendingIntent)
    .SetContentTitle ("Sample Notification")
    .SetContentText ("Hello World! This is my second action notification!")
    .SetSmallIcon (Resource.Drawable.ic_notification);

// Build the notification:
Notification notification = builder.Build();

// Get the notification manager:
NotificationManager notificationManager =
    GetSystemService (Context.NotificationService) as NotificationManager;

// Publish the notification:
const int notificationId = 0;
notificationManager.Notify (notificationId, notification);

In questo esempio di codice l'app è costituita da due attività: MainActivity (che contiene il codice di notifica precedente) e SecondActivity, la schermata visualizzata dall'utente dopo aver toccato la notifica. Quando questo codice viene eseguito, viene presentata una semplice notifica (simile all'esempio precedente). Toccando la notifica, l'utente viene visualizzato sullo SecondActivity schermo:

Il messaggio stringa (passato al metodo della PutExtra finalità) viene recuperato tramite SecondActivity questa riga di codice:

// Get the message from the intent:
string message = Intent.Extras.GetString ("message", "");

Questo messaggio recuperato, "Greetings from MainActivity!", viene visualizzato nella SecondActivity schermata, come illustrato nello screenshot precedente. Quando l'utente preme il pulsante Indietro mentre in , SecondActivitylo spostamento porta all'esterno dell'app e torna alla schermata precedente all'avvio dell'app.

Per altre informazioni sulla creazione di finalità in sospeso, vedere PendingIntent.

Oltre la notifica di base

Per impostazione predefinita, le notifiche hanno un formato di layout di base semplice in Android, ma è possibile migliorare questo formato di base effettuando chiamate di metodo aggiuntive NotificationCompat.Builder . In questa sezione si apprenderà come aggiungere un'icona di foto di grandi dimensioni alla notifica e verranno visualizzati esempi di come creare notifiche di layout espanse.

Formato icona grande

Le notifiche Android visualizzano in genere l'icona dell'app di origine (sul lato sinistro della notifica). Tuttavia, le notifiche possono visualizzare un'immagine o una foto (un'icona grande) anziché l'icona di piccole dimensioni standard. Ad esempio, un'app di messaggistica potrebbe visualizzare una foto del mittente anziché l'icona dell'app.

Ecco un esempio di notifica android 5.0 di base: visualizza solo l'icona piccola dell'app:

Di seguito è riportato uno screenshot della notifica dopo averlo modificato per visualizzare un'icona di grandi dimensioni, che usa un'icona creata da un'immagine di una scimmia del codice Xamarin:

Si noti che quando viene visualizzata una notifica in formato icona di grandi dimensioni, l'icona piccola dell'app viene visualizzata come badge nell'angolo in basso a destra dell'icona grande.

Per usare un'immagine come icona di grandi dimensioni in una notifica, chiamare il metodo SetLargeIcon del generatore di notifiche e passare una bitmap dell'immagine. A differenza di SetSmallIcon, SetLargeIcon accetta solo una bitmap. Per convertire un file di immagine in una bitmap, usare la classe BitmapFactory . Ad esempio:

builder.SetLargeIcon (BitmapFactory.DecodeResource (Resources, Resource.Drawable.monkey_icon));

Questo codice di esempio apre il file di immagine in Resources/drawable/monkey_icon.png, lo converte in una bitmap e passa la bitmap risultante a NotificationCompat.Builder. In genere, la risoluzione dell'immagine di origine è maggiore dell'icona piccola, ma non molto più grande. Un'immagine troppo grande potrebbe causare operazioni di ridimensionamento non necessarie che potrebbero ritardare la registrazione della notifica.

Stile testo grande

Lo stile Testo grande è un modello di layout espanso usato per la visualizzazione di messaggi lunghi nelle notifiche. Analogamente a tutte le notifiche di layout espanse, la notifica Testo grande viene inizialmente visualizzata in un formato di presentazione compatto:

In questo formato viene visualizzato solo un estratto del messaggio, terminato da due punti. Quando l'utente trascina verso il basso la notifica, si espande per visualizzare l'intero messaggio di notifica:

Questo formato di layout espanso include anche testo di riepilogo nella parte inferiore della notifica. L'altezza massima della notifica big text è 256 dp.

Per creare una notifica big text , creare un'istanza di un NotificationCompat.Builder oggetto, come in precedenza, e quindi creare un'istanza e aggiungere un oggetto BigTextStyle all'oggetto NotificationCompat.Builder . Ecco un esempio:

// Instantiate the Big Text style:
Notification.BigTextStyle textStyle = new Notification.BigTextStyle();

// Fill it with text:
string longTextMessage = "I went up one pair of stairs.";
longTextMessage += " / Just like me. ";
//...
textStyle.BigText (longTextMessage);

// Set the summary text:
textStyle.SetSummaryText ("The summary text goes here.");

// Plug this style into the builder:
builder.SetStyle (textStyle);

// Create the notification and publish it ...

In questo esempio, il testo del messaggio e il testo di riepilogo vengono archiviati nell'oggetto BigTextStyle (textStyle) prima che venga passato a NotificationCompat.Builder.

Stile immagine

Lo stile Immagine (detto anche stile Immagine grande) è un formato di notifica espanso che è possibile usare per visualizzare un'immagine nel corpo di una notifica. Ad esempio, un'app screenshot o un'app foto può usare lo stile di notifica Immagine per fornire all'utente una notifica dell'ultima immagine acquisita. Si noti che l'altezza massima della notifica immagine è 256 dp: Android ridimensiona l'immagine in base a questa restrizione massima di altezza, entro i limiti della memoria disponibile.

Analogamente a tutte le notifiche di layout espanse, le notifiche immagine vengono prima visualizzate in un formato compatto che visualizza un estratto del testo del messaggio a comparsa:

Quando l'utente trascina verso il basso nella notifica Immagine , si espande per visualizzare un'immagine. Ad esempio, ecco la versione espansa della notifica precedente:

Si noti che quando la notifica viene visualizzata in formato compatto, visualizza il testo della notifica (il testo passato al metodo del SetContentText generatore di notifiche, come illustrato in precedenza). Tuttavia, quando la notifica viene espansa per rivelare l'immagine, visualizza il testo di riepilogo sopra l'immagine.

Per creare una notifica Image , creare un'istanza di un NotificationCompat.Builder oggetto come in precedenza e quindi creare e inserire un oggetto BigPictureStyle nell'oggetto NotificationCompat.Builder . Ad esempio:

// Instantiate the Image (Big Picture) style:
Notification.BigPictureStyle picStyle = new Notification.BigPictureStyle();

// Convert the image to a bitmap before passing it into the style:
picStyle.BigPicture (BitmapFactory.DecodeResource (Resources, Resource.Drawable.x_bldg));

// Set the summary text that will appear with the image:
picStyle.SetSummaryText ("The summary text goes here.");

// Plug this style into the builder:
builder.SetStyle (picStyle);

// Create the notification and publish it ...

Come il SetLargeIcon metodo di NotificationCompat.Builder, il metodo BigPicture di BigPictureStyle richiede una bitmap dell'immagine che si desidera visualizzare nel corpo della notifica. In questo esempio, il metodo DecodeResource di legge il file di BitmapFactory immagine che si trova in Resources/drawable/x_bldg.png e lo converte in una bitmap.

È anche possibile visualizzare immagini non incluse in un pacchetto come risorsa. Ad esempio, il codice di esempio seguente carica un'immagine dalla scheda SD locale e la visualizza in una notifica immagine :

// Using the Image (Big Picture) style:
Notification.BigPictureStyle picStyle = new Notification.BigPictureStyle();

// Read an image from the SD card, subsample to half size:
BitmapFactory.Options options = new BitmapFactory.Options();
options.InSampleSize = 2;
string imagePath = "/sdcard/Pictures/my-tshirt.jpg";
picStyle.BigPicture (BitmapFactory.DecodeFile (imagePath, options));

// Set the summary text that will appear with the image:
picStyle.SetSummaryText ("Check out my new T-Shirt!");

// Plug this style into the builder:
builder.SetStyle (picStyle);

// Create notification and publish it ...

In questo esempio, il file di immagine che si trova in /sdcard/Pictures/my-tshirt.jpg viene caricato, ridimensionato a metà delle dimensioni originali e quindi convertito in una bitmap da usare nella notifica:

Se non si conoscono le dimensioni del file di immagine in anticipo, è consigliabile eseguire il wrapping della chiamata a BitmapFactory.DecodeFile in un gestore eccezioni. Potrebbe essere generata un'eccezione OutOfMemoryError se l'immagine è troppo grande per android da ridimensionare.

Per altre informazioni sul caricamento e la decodifica di immagini bitmap di grandi dimensioni, vedere Caricare bitmap di grandi dimensioni in modo efficiente.

Stile posta in arrivo

Il formato Posta in arrivo è un modello di layout espanso destinato alla visualizzazione di righe di testo separate (ad esempio un riepilogo della posta in arrivo di posta elettronica) nel corpo della notifica. La notifica in formato Posta in arrivo viene visualizzata per la prima volta in un formato compatto:

Quando l'utente trascina verso il basso la notifica, si espande per visualizzare un riepilogo della posta elettronica come illustrato nello screenshot seguente:

Per creare una notifica posta in arrivo , creare un'istanza di un NotificationCompat.Builder oggetto, come in precedenza, e aggiungere un oggetto InboxStyle all'oggetto NotificationCompat.Builder. Ecco un esempio:

// Instantiate the Inbox style:
Notification.InboxStyle inboxStyle = new Notification.InboxStyle();

// Set the title and text of the notification:
builder.SetContentTitle ("5 new messages");
builder.SetContentText ("chimchim@xamarin.com");

// Generate a message summary for the body of the notification:
inboxStyle.AddLine ("Cheeta: Bananas on sale");
inboxStyle.AddLine ("George: Curious about your blog post");
inboxStyle.AddLine ("Nikko: Need a ride to Evolve?");
inboxStyle.SetSummaryText ("+2 more");

// Plug this style into the builder:
builder.SetStyle (inboxStyle);

Per aggiungere nuove righe di testo al corpo della notifica, chiamare il metodo Addline dell'oggetto InboxStyle (l'altezza massima della notifica Posta in arrivo è 256 dp). Si noti che, a differenza dello stile Big Text , lo stile Posta in arrivo supporta singole righe di testo nel corpo della notifica.

È anche possibile utilizzare lo stile Posta in arrivo per qualsiasi notifica che deve visualizzare singole righe di testo in un formato espanso. Ad esempio, lo stile di notifica Posta in arrivo può essere usato per combinare più notifiche in sospeso in una notifica di riepilogo. È possibile aggiornare una singola notifica in stile Posta in arrivo con nuove righe di contenuto di notifica (vedere Aggiornamento di una notifica precedente), anziché generare un flusso continuo di notifiche nuove, principalmente simili.

Configurazione dei metadati

NotificationCompat.Builder include metodi che è possibile chiamare per impostare i metadati relativi alla notifica, ad esempio priorità, visibilità e categoria. Android usa queste informazioni, insieme alle impostazioni delle preferenze utente, per determinare come e quando visualizzare le notifiche.

Impostazioni di priorità

Le app in esecuzione in Android 7.1 e versioni precedenti devono impostare la priorità direttamente nella notifica stessa. L'impostazione di priorità di una notifica determina due risultati quando viene pubblicata la notifica:

• Posizione in cui viene visualizzata la notifica in relazione ad altre notifiche. Ad esempio, le notifiche con priorità alta vengono presentate sopra le notifiche con priorità più bassa nel pannello delle notifiche, indipendentemente dal momento in cui ogni notifica è stata pubblicata.

• Indica se la notifica viene visualizzata nel formato di notifica heads-up (Android 5.0 e versioni successive). Solo le notifiche con priorità alta e massima vengono visualizzate come notifiche di teste.

Xamarin.Android definisce le enumerazioni seguenti per impostare la priorità di notifica:

• NotificationPriority.Max : avvisa l'utente di una condizione urgente o critica, ad esempio una chiamata in ingresso, indicazioni stradali turn-by-turn o un avviso di emergenza. Nei dispositivi Android 5.0 e versioni successive, le notifiche con priorità massima vengono visualizzate in formato heads-up.

• NotificationPriority.High – Informa l'utente di eventi importanti (ad esempio messaggi di posta elettronica importanti o l'arrivo di messaggi di chat in tempo reale). Nei dispositivi Android 5.0 e versioni successive, le notifiche con priorità alta vengono visualizzate in formato heads-up.

• NotificationPriority.Default – Notifica all'utente di condizioni che hanno un livello medio di importanza.

• NotificationPriority.Low – Per informazioni non urgenti di cui l'utente deve essere informato (ad esempio, promemoria di aggiornamento software o aggiornamenti di social network).

• NotificationPriority.Min : per informazioni di base che l'utente rileva solo quando si visualizzano le notifiche (ad esempio, la posizione o le informazioni meteo).

Per impostare la priorità di una notifica, chiamare il metodo SetPriority dell'oggetto NotificationCompat.Builder passando il livello di priorità. Ad esempio:

builder.SetPriority (NotificationPriority.High);

Nell'esempio seguente viene visualizzata la notifica ad alta priorità "Un messaggio importante!" nella parte superiore del pannello delle notifiche:

Poiché si tratta di una notifica ad alta priorità, viene visualizzata anche come notifica heads-up sopra la schermata dell'attività corrente dell'utente in Android 5.0:

Nell'esempio seguente, la notifica "Thought for the day" con priorità bassa viene visualizzata con una notifica a livello di batteria con priorità più alta:

Poiché la notifica "Thought for the day" è una notifica con priorità bassa, Android non lo visualizzerà in formato Heads-up.

Nota

In Android 8.0 e versioni successive, la priorità del canale di notifica e delle impostazioni utente determinerà la priorità della notifica.

Impostazioni di visibilità

A partire da Android 5.0, l'impostazione di visibilità è disponibile per controllare la quantità di contenuto della notifica visualizzata nella schermata di blocco sicura. Xamarin.Android definisce le enumerazioni seguenti per impostare la visibilità delle notifiche:

• NotificationVisibility.Public : il contenuto completo della notifica viene visualizzato nella schermata di blocco sicura.

• NotificationVisibility.Private - Solo le informazioni essenziali vengono visualizzate nella schermata di blocco sicura (ad esempio l'icona di notifica e il nome dell'app che l'ha pubblicata), ma il resto dei dettagli della notifica è nascosto. Per impostazione predefinita, tutte le notifiche sono NotificationVisibility.Private.

• NotificationVisibility.Secret - Niente viene visualizzato nella schermata di blocco sicura, nemmeno l'icona di notifica. Il contenuto della notifica è disponibile solo dopo che l'utente sblocca il dispositivo.

Per impostare la visibilità di una notifica, le app chiamano il SetVisibility metodo dell'oggetto NotificationCompat.Builder , passando l'impostazione di visibilità. Ad esempio, questa chiamata a SetVisibility effettua la notifica Private:

builder.SetVisibility (NotificationVisibility.Private);

Quando viene inviata una Private notifica, nella schermata di blocco sicura viene visualizzata solo il nome e l'icona dell'app. Anziché il messaggio di notifica, l'utente visualizza "Sblocca il dispositivo per visualizzare questa notifica":

In questo esempio NotificationsLab è il nome dell'app di origine. Questa versione modificata della notifica viene visualizzata solo quando la schermata di blocco è protetta (ad esempio, protetta tramite PIN, modello o password) - se la schermata di blocco non è sicura, il contenuto completo della notifica è disponibile nella schermata di blocco.

Impostazioni categoria

A partire da Android 5.0, le categorie predefinite sono disponibili per le notifiche di classificazione e filtro. Xamarin.Android fornisce le enumerazioni seguenti per queste categorie:

• Notification.CategoryCall – Chiamata telefonica in arrivo.

• Notification.CategoryMessage – Messaggio di testo in arrivo.

• Notification.CategoryAlarm : una condizione di allarme o una scadenza del timer.

• Notification.CategoryEmail : messaggio di posta elettronica in arrivo.

• Notification.CategoryEvent – Un evento del calendario.

• Notification.CategoryPromo – Messaggio promozionale o annuncio pubblicitario.

• Notification.CategoryProgress : stato di un'operazione in background.

• Notification.CategorySocial – Aggiornamento dei social network.

• Notification.CategoryError : errore di un'operazione in background o di un processo di autenticazione.

• Notification.CategoryTransport : aggiornamento della riproduzione multimediale.

• Notification.CategorySystem – Riservato per l'uso del sistema (stato del sistema o del dispositivo).

• Notification.CategoryService : indica che è in esecuzione un servizio in background.

• Notification.CategoryRecommendation : un messaggio di raccomandazione correlato all'app attualmente in esecuzione.

• Notification.CategoryStatus : informazioni sul dispositivo.

Quando le notifiche vengono ordinate, la priorità della notifica ha la precedenza sull'impostazione della categoria. Ad esempio, una notifica ad alta priorità verrà visualizzata come heads-up anche se appartiene alla Promo categoria. Per impostare la categoria di una notifica, chiamare il SetCategory metodo dell'oggetto NotificationCompat.Builder passando l'impostazione della categoria. Ad esempio:

builder.SetCategory (Notification.CategoryCall);

La funzionalità Non disturbare (novità di Android 5.0) filtra le notifiche in base alle categorie. Ad esempio, la schermata Non disturbare in Impostazioni consente all'utente di esentare le notifiche per le telefonate e i messaggi:

Quando l'utente configura Non disturbare per bloccare tutti gli interrupt ad eccezione delle chiamate telefoniche (come illustrato nello screenshot precedente), Android consente le notifiche con un'impostazione di categoria di Notification.CategoryCall da presentare mentre il dispositivo è in modalità Non disturbare. Si noti che Notification.CategoryAlarm le notifiche non vengono mai bloccate in modalità Non disturbare .

L'esempio LocalNotifications illustra come usare NotificationCompat.Builder per avviare una seconda attività da una notifica. Questo codice di esempio è illustrato nella procedura dettagliata Using Local Notifications in Xamarin.Android (Uso delle notifiche locali in Xamarin.Android ).

Stili di notifica

Per creare notifiche di tipo Testo grande, Immagine o Posta in arrivo con NotificationCompat.Builder, l'app deve usare le versioni di compatibilità di questi stili. Ad esempio, per usare lo stile Big Text, creare un'istanza di NotificationCompat.BigTextstyle:

NotificationCompat.BigTextStyle textStyle = new NotificationCompat.BigTextStyle();

// Plug this style into the builder:
builder.SetStyle (textStyle);

Analogamente, l'app può usare NotificationCompat.InboxStyle e rispettivamente per gli stili Posta in arrivo e ImmagineNotificationCompat.BigPictureStyle.

Priorità di notifica e categoria

NotificationCompat.Builder supporta il SetPriority metodo (disponibile a partire da Android 4.1). Tuttavia, il SetCategory metodo non è supportato da NotificationCompat.Builder perché le categorie fanno parte del nuovo sistema di metadati di notifica introdotto in Android 5.0.

Per supportare le versioni precedenti di Android, dove SetCategory non è disponibile, il codice può controllare il livello API in fase di esecuzione per chiamare SetCategory in modo condizionale quando il livello API è uguale o maggiore di Android 5.0 (livello API 21):

if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop) {
    builder.SetCategory (Notification.CategoryEmail);
}

In questo esempio il framework di destinazione dell'app è impostato su Android 5.0 e la versione minima di Android è impostata su Android 4.1 (livello API 16). Poiché SetCategory è disponibile nel livello API 21 e versioni successive, questo codice di esempio chiamerà SetCategory solo quando è disponibile. Non chiamerà SetCategory quando il livello API è minore di 21.

Visibilità della schermata di blocco

Poiché Android non supportava le notifiche della schermata di blocco prima di Android 5.0 (livello API 21), NotificationCompat.Builder non supporta il SetVisibility metodo . Come illustrato in precedenza per SetCategory, il codice può controllare il livello api in fase di esecuzione e chiamare SetVisiblity solo quando è disponibile:

if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop) {
    builder.SetVisibility (Notification.Public);
}

Riepilogo

Questo articolo ha illustrato come creare notifiche locali in Android. Descrive l'anatomia di una notifica, spiega come usare NotificationCompat.Builder per creare notifiche, come applicare stili alle notifiche in formati icona di grandi dimensioni, Testo grande, Immagine e Posta in arrivo, come impostare le impostazioni dei metadati di notifica, ad esempio priorità, visibilità e categoria, e come avviare un'attività da una notifica. Questo articolo descrive anche come funzionano queste impostazioni di notifica con le nuove funzionalità teste up, schermata di blocco e Non disturbare introdotte in Android 5.0. Infine, si è appreso come usare NotificationCompat.Builder per mantenere la compatibilità delle notifiche con le versioni precedenti di Android.

Per linee guida sulla progettazione di notifiche per Android, vedere Notifiche.

Collegamenti correlati

• NotificationsLab (esempio)
• LocalNotifications (esempio)
• Procedura dettagliata per le notifiche locali in Android
• Notifica dell'utente
• Notifica
• NotificationManager
• NotificationCompat.Builder
• PendingIntent