Riferimento API Android aptics

Questa sezione fornisce un'introduzione alle varie API aptiche disponibili in Android. Inoltre, spiega quando e come verificare l'eventuale necessità di supporto del dispositivo per garantire che gli effetti aptici vengano riprodotti come previsto.

Esistono diversi modi per creare effetti aptici ed è importante considerare i principi di progettazione dell'aptica di Android quando scegli tra questi. La tabella seguente riepiloga questi attributi di alto livello di ciascun approccio:

  • La disponibilità è particolarmente importante quando si pianifica il fallback del comportamento e deve essere combinata con il controllo del supporto dei singoli dispositivi.
  • La risposta aptica chiara è una sensazione nitida e pulita che risulta meno fastidiosa per gli utenti.
  • La feedback aptico avanzato ha una maggiore espressività e spesso richiede hardware più ricco di funzionalità.
Piattaforma API Disponibilità Cancella feedback aptico Tecnologia aptica avanzata
HapticFeedbackConstants Android 1.5+
(per constant)
VibrationEffect predefinito Android 10+
VibrationEffect Composition Android 11+ (per costante)
Vibrazioni on/off, one-shot e a forma d'onda Android 1

Inoltre, le API di notifica, descritte in questa pagina, ti consentono di personalizzare gli effetti aptici riprodotti per le notifiche in arrivo.

In questa pagina vengono descritti anche concetti aggiuntivi che riguardano le superfici API:

HapticFeedbackConstants

La classe HapticFeedbackConstants fornisce costanti basate su azioni per consentire alle app di aggiungere feedback aptico coerente con l'esperienza del dispositivo, anziché avere effetti diversi per azioni comuni.

Compatibilità e requisiti

L'utilizzo del metodo View.performHapticFeedback con queste costanti non richiede autorizzazioni speciali per l'app. È soggetto alla proprietà View.hapticFeedbackEnabled, che, se impostata su false, disattiva tutte le chiamate di feedback aptico nella visualizzazione, incluse quelle predefinite.L'impostazione principale correlata è la proprietà View.hapticFeedbackEnabled, che, se impostata su false, disattiva tutte le chiamate di feedback aptico nella visualizzazione, incluse quelle predefinite. Il metodo rispetta anche l'impostazione di sistema dell'utente per l'attivazione del feedback tattile.

L'unica considerazione relativa alla compatibilità è il livello SDK della costante specifica per l'azione.

Non è necessario fornire un comportamento di fallback quando utilizzi HapticFeedbackConstants.

Utilizzo di HapticsFeedbackConstants

Per informazioni dettagliate sull'utilizzo di HapticFeedbackConstants, vedi Aggiungere il feedback aptico agli eventi.

Predefinito VibrationEffect

La classe VibrationEffect fornisce diverse costanti predefinite come CLICK, TICK e DOUBLE_CLICK. Questi effetti potrebbero essere ottimizzati per il dispositivo.

Compatibilità e requisiti

La riproduzione di qualsiasi VibrationEffect richiede l'autorizzazione VIBRATE nel file manifest dell'app.

Non è necessario fornire un comportamento di riserva quando si utilizzano VibrationEffect predefiniti, poiché le costanti che non hanno un'implementazione ottimizzata per il dispositivo vengono ripristinate a un fallback della piattaforma standard.

Le API Vibrator.areEffectsSupported e Vibrator.areAllEffectsSupported servono per determinare se esiste un'implementazione ottimizzata per il dispositivo. Gli effetti predefiniti possono comunque essere utilizzati senza un'implementazione ottimizzata e utilizzano il fallback della piattaforma standard. Di conseguenza, queste API areEffectsSupported sono necessarie solo se un'applicazione vuole tenere conto del fatto che l'effetto sia ottimizzato o meno per il dispositivo.

I metodi di controllo dell'effetto possono restituire uno dei tre valori seguenti:

Poiché il valore UNKNOWN indica che l'API di controllo non è disponibile, in genere viene restituito per tutti gli effetti o per nessuno. Questi dispositivi eseguono il fallback in modo dinamico.

Utilizzo di VibrationEffect predefinito

Per informazioni dettagliate sull'utilizzo di un VibrationEffect predefinito, vedi Utilizzare un VibrationEffect predefinito per generare feedback aptico.

Envelope VibrationEffect

Le vibrazioni basate sull'inviluppo consentono un controllo preciso dell'ampiezza e della frequenza della vibrazione nel tempo definendo una sequenza di punti di controllo. Ciò consente agli sviluppatori di creare esperienze di feedback aptico più ricche e sfumate. Queste vibrazioni possono essere create utilizzando le classi BasicEnvelopeBuilder e WaveformEnvelopeBuilder.

Compatibilità e requisiti

Per riprodurre qualsiasi effetto di vibrazione, la tua app deve dichiarare l'autorizzazione VIBRATE nel manifest dell'app.

Per verificare il supporto degli effetti di inviluppo, chiama Vibrator.areEnvelopeEffectsSupported().

Basic Envelope Builder

Per creare un'esperienza aptica fluida e senza interruzioni, gli effetti di inviluppo devono iniziare e terminare con un'intensità di \( 0.0 \). L'API lo applica impostando l'intensità iniziale su zero e genera un'eccezione se l'intensità finale non è zero. Questo vincolo impedisce effetti dinamici indesiderati nelle vibrazioni dovuti a discontinuità nell'ampiezza che possono influire negativamente sulla percezione aptica dell'utente.

Per fornire un rendering coerente dell'effetto busta su tutti i dispositivi, il framework richiede che i dispositivi che supportano questa funzionalità possano gestire una durata minima di 20 ms tra i punti di controllo e almeno 16 punti per gli effetti busta.

Generatore di inviluppi della forma d'onda

Il framework non modifica i valori di frequenza e ampiezza richiesti forniti dallo sviluppatore. Tuttavia, l'API fissa anche l'ampiezza iniziale a zero per creare transizioni fluide.

Per aiutarti a ottimizzare gli effetti di inviluppo della forma d'onda della tua app e fornire compatibilità tra i dispositivi, Android fornisce API per interrogare importanti funzionalità del dispositivo. Questi metodi forniscono informazioni sulle limitazioni del dispositivo, ad esempio la durata massima e minima della transizione tra i punti di controllo e il numero massimo di punti di controllo supportati per un singolo effetto:

getMaxSize()
Recupera il numero massimo di punti di controllo supportati per un effetto inviluppo.
getMinControlPointDurationMillis()
Recupera la durata minima supportata, in millisecondi, tra due punti di controllo all'interno di un effetto inviluppo.
getMaxControlPointDurationMillis()
Recupera la durata massima supportata, in millisecondi, tra due punti di controllo all'interno di un effetto inviluppo.
getMaxDurationMillis()
Recupera la durata massima supportata per un effetto envelope, in millisecondi.

Se un effetto supera i limiti del dispositivo, ad esempio consentendo troppi punti di controllo o una durata superiore a quella massima, il framework lo regola automaticamente per rientrare nei limiti consentiti. Questa procedura di aggiustamento cerca di preservare il più possibile l'intento e l'aspetto originali del design.

Utilizzo di Envelope VibrationEffects

Per informazioni dettagliate sulla creazione di effetti di forma d'onda di inviluppo, vedi Creare una forma d'onda di vibrazione con gli inviluppi.

VibrationEffect composizione

Una composizione VibrationEffect è un effetto di vibrazione creato utilizzando l'API VibrationEffect.startComposition. Questa API consente di creare feedback aptico avanzato creando una sequenza di primitive con ritardi e intensità personalizzati. Tuttavia, presta particolare attenzione per assicurarti che il dispositivo supporti le funzionalità combinate per evitare un'esperienza complessiva incoerente.

Compatibilità e requisiti

La riproduzione di qualsiasi VibrationEffect richiede l'autorizzazione VIBRATE nel file manifest dell'app.

Non tutti i dispositivi supportano tutte le funzionalità dell'API Composition ed è importante assicurarsi che le primitive siano disponibili.

Controllare il supporto dei primitivi di vibrazione

Il supporto per primitiva può essere recuperato utilizzando il metodo Vibrator.arePrimitivesSupported. In alternativa, un insieme di primitive può essere controllato insieme utilizzando il metodo Vibrator.areAllPrimitivesSupported, che equivale a AND il supporto per primitiva.

Utilizzo delle composizioni di VibrationEffect

Per informazioni dettagliate sull'utilizzo delle composizioni VibrationEffect, vedi Creare composizioni di vibrazione.

Vibrazioni on/off, one-shot e a forma d'onda

La forma più antica di vibrazione supportata su Android è la semplice vibrazione con schemi di accensione e spegnimento con durate configurabili. Queste API in genere non sono ben allineate ai principi di progettazione aptica perché possono generare feedback aptico vibrante; evitali, tranne come ultima risorsa.

Il caso d'uso più comune per le vibrazioni on/off sono le notifiche, in cui, indipendentemente da tutto, è desiderata una vibrazione. Le vibrazioni a forma d'onda consentono inoltre a un pattern di ripetersi all'infinito, come potresti immaginare per una suoneria.

Un pattern one-shot si riferisce a una vibrazione singola per N millisecondi.

Esistono due tipi di pattern di forma d'onda:

  • Solo tempistiche. Questo tipo di forma d'onda è una descrizione delle durate alternate di spegnimento e accensione. Le tempistiche iniziano con la durata di spegnimento. Di conseguenza, i pattern della forma d'onda spesso iniziano con un valore pari a zero per indicare di iniziare immediatamente a vibrare.
  • Tempi e ampiezze. Questo tipo di forma d'onda ha un array aggiuntivo di ampiezze da abbinare a ogni figura temporale, anziché l'on-off implicito della prima forma. Tuttavia, è importante verificare che il dispositivo supporti il controllo dell'ampiezza per garantire che sia possibile ottenere il ridimensionamento previsto.

Compatibilità e requisiti

Poiché le vibrazioni on/off sono la forma più antica di vibrazione, sono supportate su praticamente tutti i dispositivi con un vibratore, come descritto più avanti in questa pagina.

Per effettuare chiamate VibrationEffect o vibrate in stile precedente, è necessaria l'autorizzazione VIBRATE nel manifest dell'app.

Quando utilizzi valori di ampiezza diversi in una forma d'onda, ti consigliamo vivamente di verificare che il dispositivo supporti il controllo dell'ampiezza.

Controlla il supporto del controllo dell'ampiezza

I valori di ampiezza diversi da zero vengono arrotondati al 100% sui dispositivi senza controllo dell'ampiezza, pertanto è importante verificare se il supporto è presente utilizzando Vibrator.hasAmplitudeControl. Per ulteriori dettagli, consulta la sezione Controllo dell'ampiezza.

Valuta attentamente se il tuo effetto ha una qualità sufficiente senza controllo dell'ampiezza. Il ricorso a una vibrazione di accensione/spegnimento progettata esplicitamente potrebbe essere più efficace.

Utilizzo delle vibrazioni di attivazione/disattivazione

Nei livelli SDK più recenti, tutte le modalità di vibrazione sono state consolidate in un'unica classe VibrationEffect espressiva, in cui queste semplici vibrazioni vengono create utilizzando VibrationEffect.createOneshot o VibrationEffect.createWaveform.

API di notifica

Quando personalizzi le notifiche dell'app, puoi utilizzare una delle seguenti API per associare un pattern a ogni canale di notifica:

Tutte queste forme assumono un pattern di forma d'onda di base on/off, come descritto in precedenza, in cui la prima voce è il ritardo prima dell'attivazione del vibratore.

Concetti generali

Diversi concetti si applicano alle superfici API descritte sopra.

Il dispositivo ha un vibratore?

Puoi ottenere una classe Vibrator non nulla da context.getSystemService(Vibrator.class). Se il dispositivo non ha un vibratore, le chiamate alle API di vibrazione non hanno alcun effetto, quindi le app non devono limitare tutta la loro aptica a una condizione. Tuttavia, se necessario, un'applicazione può chiamare hasVibrator() per determinare se si tratta di un vibratore reale (true) o di uno stub (false).

L'utente ha disattivato la risposta aptica al tocco?

Alcune implementazioni personalizzate potrebbero richiedere di verificare manualmente se l'utente ha disattivato completamente l'impostazione Feedback tattile di Android, nel qual caso gli effetti del feedback tattile devono essere eliminati. Questa impostazione può essere interrogata utilizzando la chiave HAPTIC_FEEDBACK_ENABLED, dove un valore pari a zero significa disabilitata.

Attributi di vibrazione

Gli attributi di vibrazione (attualmente sotto forma di AudioAttributes) possono essere forniti per aiutare il sistema a comprendere lo scopo della vibrazione. Questo è obbligatorio quando si avvia una vibrazione quando l'app è in background, in quanto per l'utilizzo in background sono supportati solo gli aptici di attenzione.

La creazione di AudioAttributes è trattata nella documentazione della classe e deve essere considerata come vibrazione piuttosto che suono.

Come guida, nella maggior parte dei casi, il tipo di contenuti è CONTENT_TYPE_SONIFICATION e l'utilizzo potrebbe essere valori come USAGE_ASSISTANCE_SONIFICATION per il feedback tattile in primo piano o USAGE_ALARM per una sveglia in background. I flag audio non hanno alcun effetto sulle vibrazioni.

Controllo dell'ampiezza

Se un vibratore ha il controllo dell'ampiezza, può riprodurre vibrazioni con intensità diverse. Si tratta di una funzionalità importante per la produzione di feedback aptico avanzato, nonché per consentire potenzialmente il controllo da parte dell'utente delle intensità aptiche predefinite.

Il supporto del controllo dell'ampiezza può essere verificato chiamando Vibrator.hasAmplitudeControl. Se un vibratore non supporta l'ampiezza, tutti i valori di ampiezza verranno mappati su off/on in base al fatto che siano zero/non zero. Di conseguenza, le applicazioni che utilizzano l'aptica avanzata con ampiezze variabili devono valutare la possibilità di disattivarla se il dispositivo non dispone del controllo dell'ampiezza.

Supporto degli effetti di busta

I vibratori con supporto degli effetti di inviluppo consentono di creare vibrazioni più dinamiche e sfumate, offrendo un controllo più preciso su intensità e nitidezza per esperienze aptiche più ricche. Utilizza Vibration.areEnvelopeEffectsSupported per determinare se il tuo dispositivo supporta questa funzionalità. In caso contrario, le vibrazioni basate sulla busta vengono ignorate.