Visualizzare le attività in corso

I dispositivi Wear OS vengono spesso utilizzati per esperienze di lunga durata, ad esempio il monitoraggio di un allenamento. Questo pone una sfida all'esperienza utente: se un utente avvia un'attività e poi torna al quadrante, come può riaprire l'app? Tornare all'app utilizzando l'avvio app può essere difficile, soprattutto quando si è in movimento, creando inutili attriti.

La soluzione è abbinare una notifica continua a un OngoingActivity. In questo modo, il dispositivo può visualizzare informazioni sull'attività di lunga durata nell'interfaccia utente, abilitando funzionalità come l'icona toccabile nella parte inferiore del quadrante. In questo modo, gli utenti sono a conoscenza dell'attività in background e hanno un modo per tornare all'app con un solo tocco.

Un'attività continua mantiene anche la tua app visibile più a lungo, impedendo al sistema di tornare al quadrante dopo un periodo di inattività. Per ulteriori informazioni, consulta Mantenere la visibilità dell'app su Wear.

Ad esempio, in questa app di allenamento, le informazioni possono essere visualizzate sul quadrante dell'utente come un'icona di corsa toccabile:

Figura 1. Indicatore di attività.

Una notifica continua mostra anche informazioni nella sezione Recenti dell'avvio app globale. Questo offre agli utenti un altro posto comodo per visualizzare lo stato della loro attività e interagire di nuovo con l'app:

Figura 2. Avvio app globale.

Di seguito sono riportate alcune situazioni in cui è consigliabile utilizzare una notifica continua collegata a un'attività continua:

Figura 3. Timer: esegue attivamente il conto alla rovescia e termina quando il timer viene messo in pausa o arrestato.

Figura 4. Indicazioni stradali passo passo: annuncia le indicazioni per una destinazione. Termina quando l'utente raggiunge la destinazione o interrompe la navigazione.

Figura 5. Contenuti multimediali: riproduce musica durante una sessione. Termina immediatamente dopo che l'utente mette in pausa la sessione.

Wear crea automaticamente attività continue per le app di contenuti multimediali.

Consulta il codelab Attività continua per un esempio dettagliato della creazione di attività continue per altri tipi di app.

Configurazione

Per iniziare a utilizzare l'API Attività continua nella tua app, aggiungi le seguenti dipendenze al file build.gradle dell'app:

dependencies {
  implementation "androidx.wear:wear-ongoing:1.1.0"
  implementation "androidx.core:core:1.18.0"
}

Creare un'attività continua

La procedura prevede tre passaggi:

1. Crea un NotificationCompat.Builder standard e configuralo come continuo.
2. Crea e configura un OngoingActivity oggetto, passandogli il builder di notifiche.
3. Applica l'attività continua al builder di notifiche e pubblica la notifica risultante.

Creare e configurare la notifica

Inizia creando un NotificationCompat.Builder. Il passaggio chiave è chiamare setOngoing(true) per contrassegnarlo come notifica continua. In questa fase puoi anche impostare altre proprietà di notifica, come l'icona piccola e la categoria.

// Create a PendingIntent to pass to the notification builder
val pendingIntent =
    PendingIntent.getActivity(
        this,
        0,
        Intent(this, AlwaysOnActivity::class.java).apply {
            flags = Intent.FLAG_ACTIVITY_SINGLE_TOP
        },
        PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
    )

val notificationBuilder = NotificationCompat.Builder(this, CHANNEL_ID)
    .setContentTitle("Always On Service")
    .setContentText("Service is running in background")
    .setSmallIcon(R.drawable.animated_walk)
    // Category helps the system prioritize the ongoing activity
    .setCategory(NotificationCompat.CATEGORY_WORKOUT)
    .setContentIntent(pendingIntent)
    .setVisibility(NotificationCompat.VISIBILITY_PUBLIC)
    .setOngoing(true) // Important!
AlwaysOnService.kt

Creare l'attività continua

Poi, crea un'istanza di OngoingActivity utilizzando il relativo builder. OngoingActivity.Builder richiede un Context, un ID notifica e NotificationCompat.Builder che hai creato nel passaggio precedente.

Configura le proprietà chiave che verranno visualizzate sulle nuove superfici dell'UI:

• Icone animate e statiche: fornisci le icone visualizzate sul quadrante in modalità attiva e Ambient.
• Intent di tocco: un PendingIntent che riporta l'utente alla tua app quando tocca l'icona Attività continua. Puoi riutilizzare pendingIndent creato nel passaggio precedente.

val ongoingActivity =
    OngoingActivity.Builder(applicationContext, NOTIFICATION_ID, notificationBuilder)
        // Sets the icon that appears on the watch face in active mode.
        .setAnimatedIcon(R.drawable.animated_walk)
        // Sets the icon that appears on the watch face in ambient mode.
        .setStaticIcon(R.drawable.ic_walk)
        // Sets the tap target to bring the user back to the app.
        .setTouchIntent(pendingIntent)
        .build()
AlwaysOnService.kt

Applicare alla notifica e pubblicare

Il passaggio finale consiste nel collegare OngoingActivity alla notifica e poi pubblicarla. Il metodo ongoingActivity.apply() modifica il builder di notifiche originale, aggiungendo i dati necessari in modo che il sistema possa visualizzarlo sulle superfici aggiuntive. Dopo averlo applicato, puoi creare e pubblicare la notifica come di consueto.

// This call modifies notificationBuilder to include the ongoing activity data.
ongoingActivity.apply(applicationContext)

// Post the notification.
startForeground(NOTIFICATION_ID, notificationBuilder.build())
AlwaysOnService.kt

Aggiungere testo di stato dinamico all'avvio app

Il codice precedente aggiunge l'icona toccabile al quadrante. Per fornire aggiornamenti in tempo reale ancora più ricchi nella sezione Recenti dell'avvio app, crea un oggetto Status e collegalo a OngoingActivity. Se non fornisci un Status, il sistema utilizza per impostazione predefinita il testo del contenuto della notifica (impostato utilizzando setContentText()). Per visualizzare il testo dinamico, utilizza un Status.Builder. Puoi definire una stringa di modello con segnaposto e fornire oggetti Status.Part per riempire questi segnaposto. Status.Part può essere dinamico, ad esempio un cronometro o un timer.

L'esempio seguente mostra come creare uno stato che visualizza "Corri per [un timer cronometro]":

// Define a template with placeholders for the activity type and the timer.
val statusTemplate = "#type# for #time#"

// Set the start time for a stopwatch.
// Use SystemClock.elapsedRealtime() for time-based parts.
val runStartTime = SystemClock.elapsedRealtime()

val ongoingActivityStatus = Status.Builder()
    // Sets the template string.
    .addTemplate(statusTemplate)
    // Fills the #type# placeholder with a static text part.
    .addPart("type", Status.TextPart("Run"))
    // Fills the #time# placeholder with a stopwatch part.
    .addPart("time", Status.StopwatchPart(runStartTime))
    .build()
AlwaysOnService.kt

Infine, collega questo Status a OngoingActivity chiamando setStatus() su OngoingActivity.Builder.

val ongoingActivity =
    OngoingActivity.Builder(applicationContext, NOTIFICATION_ID, notificationBuilder)
        // ...
        // Add the status to the OngoingActivity.
        .setStatus(ongoingActivityStatus)
        .build()
AlwaysOnService.kt

Personalizzazioni aggiuntive

Oltre a Status, puoi personalizzare l'attività continua o le notifiche nei seguenti modi. Tuttavia, queste personalizzazioni potrebbero non essere utilizzate, in base all'implementazione dell'OEM.

Notifica continua

• La categoria impostata determina la priorità dell'attività continua.
  • CATEGORY_CALL: una chiamata vocale o video in arrivo o una richiesta di comunicazione sincrona simile
  • CATEGORY_NAVIGATION: una mappa o navigazione passo passo
  • CATEGORY_TRANSPORT: controllo del trasporto di contenuti multimediali per la riproduzione
  • CATEGORY_ALARM: una sveglia o un timer
  • CATEGORY_WORKOUT: un allenamento
  • CATEGORY_LOCATION_SHARING: categoria di condivisione della posizione temporanea
  • CATEGORY_STOPWATCH: cronometro

Attività continua

• Icona animata: un vettore in bianco e nero, preferibilmente con uno sfondo trasparente. Viene visualizzata sul quadrante in modalità attiva. Se l'icona animata non viene fornita, viene utilizzata l'icona di notifica predefinita. L'icona di notifica predefinita è diversa per ogni applicazione.

• Icona statica: un'icona vettoriale con sfondo trasparente. Viene visualizzata sul quadrante in modalità Ambient. Se l'icona animata non è impostata, l'icona statica viene utilizzata sul quadrante in modalità attiva. Se non viene fornita, viene utilizzata l'icona di notifica. Se non viene impostata nessuna delle due, viene generata un'eccezione. (L'avvio app utilizza comunque l'icona dell'app.)

• OngoingActivityStatus: testo normale o Chronometer. Viene visualizzato nella sezione Recenti dell'avvio app. Se non viene fornito, viene utilizzato il "testo del contesto" della notifica.

• Intent di tocco: un PendingIntent utilizzato per tornare all'app se l'utente tocca l'icona Attività continua. Viene visualizzato sul quadrante o sull'elemento di avvio app. Può essere diverso dall'intent originale utilizzato per avviare l'app. Se non viene fornito, viene utilizzato l'intent del contenuto della notifica. Se non viene impostata nessuna delle due, viene generata un'eccezione.

• LocusId: ID che assegna la scorciatoia di avvio app a cui corrisponde l'attività continua. Viene visualizzato nell'avvio app nella sezione Recenti mentre l'attività è in corso. Se non viene fornito, l'avvio app nasconde tutti gli elementi dell'app nella sezione Recenti dello stesso pacchetto e mostra solo l'attività continua.

• ID attività continua: ID utilizzato per distinguere le chiamate a fromExistingOngoingActivity() quando un'applicazione ha più di un' attività continua.

Aggiornare un'attività continua

Quando devi modificare lo stato, devi aggiornare l'attività continua per la notifica esistente anziché creare una nuova notifica e un'attività continua. Per aggiornare l'attività continua e la notifica pubblicata, utilizza l'oggetto che hai creato in precedenza e chiama update(), come mostrato nell'esempio seguente:

ongoingActivity.update(context, newStatus)
AlwaysOnService.kt

Nei casi in cui non è possibile memorizzare un riferimento all'attività continua, esiste un metodo statico per recuperarla. Tuttavia, questo metodo è meno preferibile:

OngoingActivity.recoverOngoingActivity(context)
    ?.update(context, newStatus)
AlwaysOnService.kt

Interrompere un'attività continua

Quando l'app ha terminato l'esecuzione come attività continua, deve solo annullare la notifica continua.

Puoi anche scegliere di annullare la notifica o l'attività continua quando viene visualizzata in primo piano, quindi ricrearle quando torni in background, ma non è obbligatorio.

Mettere in pausa un'attività continua

Se la tua app ha un'azione di arresto esplicita, continua l'attività continua dopo averla ripresa. Per un'app senza un'azione di arresto esplicita, termina l'attività quando viene messa in pausa.

Considerazioni principali

Tieni presente quanto segue quando utilizzi l'API Attività continua:

• Imposta un'icona statica per l'attività continua, in modo esplicito o come fallback utilizzando la notifica. In caso contrario, riceverai un IllegalArgumentException.

• Utilizza icone vettoriali in bianco e nero con sfondi trasparenti.

• Imposta un intent di tocco per l'attività continua, in modo esplicito o come fallback utilizzando la notifica. In caso contrario, riceverai un IllegalArgumentException.

• Se la tua app ha più di un'attività MAIN LAUNCHER dichiarata nel manifest, pubblica una scorciatoia dinamica e associala all'attività continua utilizzando LocusId.

Pubblicare notifiche di contenuti multimediali durante la riproduzione di contenuti multimediali su dispositivi Wear OS

Se i contenuti multimediali vengono riprodotti su un dispositivo Wear OS, pubblica una notifica di contenuti multimediali. In questo modo, il sistema crea l'attività continua corrispondente.

Se utilizzi Media3, la notifica viene pubblicata automaticamente. Se crei la notifica manualmente, deve utilizzare MediaStyleNotificationHelper.MediaStyle e la MediaSession corrispondente deve avere l'attività della sessione compilata.