Riferimento API Android aptics

Questa sezione introduce le varie API aptiche disponibili in Android. Inoltre, spiega quando e come verificare se è necessario supporto per il 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 nitida è una sensazione chiara e pulita che risulta meno fastidiosa per gli utenti.
  • La vibrazione intensa ha una maggiore espressività e spesso richiede hardware con più funzionalità.
Piattaforma API Disponibilità Cancella feedback aptico Feedback aptico avanzato
HapticFeedbackConstants Android 1.5+
(per constant)
Predefined VibrationEffect Android 10+
VibrationEffect composizione (preferita) Android 16+ (4° trimestre 2026)
VibrationEffect composizione di primitive 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 sono descritti anche altri concetti che riguardano le superfici API:

HapticFeedbackConstants

La classe HapticFeedbackConstants fornisce costanti basate sull'azione per consentire alle app di aggiungere un feedback aptico coerente con l'esperienza del dispositivo, anziché avere effetti diversi per le 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 riserva 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 manifest dell'app.

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

Le API Vibrator.areEffectsSupported e Vibrator.areAllEffectsSupported servono a 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:

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. In questo modo, gli sviluppatori possono 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 busta, chiama Vibrator.areEnvelopeEffectsSupported().

Generatore di buste di base

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 a causa di 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 a busta.
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 di inviluppo, in millisecondi.

Se un effetto supera i limiti del dispositivo, ad esempio consentendo troppi punti di controllo o una durata superiore al massimo, il framework regola automaticamente l'effetto in modo che rientri 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

A partire da Android 16 (T4 2026), VibrationEffect.Builder è l'API preferita per comporre effetti aptici espressivi e avanzati sequenziando più elementi aptici lungo una sequenza temporale progettata. Sostituisce VibrationEffect.Composition offrendo la pianificazione ancorata alla sequenza temporale, l'incapsulamento atomico, il supporto di eventi misti (che combinano preset e inviluppi) e il fallback automatico integrato.

Componenti di base

Lo strumento di creazione ti consente di sequenziare i seguenti elementi aptici:

  • VibrationEffect.Preset: sensazioni aptiche predefinite che rappresentano impulsi brevi comuni, ad esempio PRESET_CLICK, PRESET_TICK e PRESET_LOW_TICK. I preset sostituiscono le primitive brevi dell'API VibrationEffect.Composition. Per effetti più lunghi, continui o in rampa (gestiti in precedenza da salita, discesa e altre primitive), utilizza invece le inviluppi (PWLE). I preset possono essere scalati da 0.0f a 1.0f utilizzando Preset.create(presetId, scale).
  • VibrationEffect.Envelope: inviluppi lineari a tratti (PWLE) creati utilizzando BasicEnvelopeBuilder (con intensità e nitidezza) o WaveformEnvelopeBuilder (con frequenza e ampiezza). Le buste vengono costruite utilizzando Envelope.create(builder).
  • VibrationEffect.Event: eventi della sequenza temporale recuperati da un VibrationEffect esistente utilizzando getEvents(). Questi possono essere aggiunti con un offset della cronologia utilizzando addEvents(startTimeShiftMillis, events).

Pianificazione e convalida della sequenza temporale

Ogni elemento viene aggiunto al generatore con un startTimeMillis che rappresenta l'offset temporale (in millisecondi) dall'inizio della composizione:

  • Convalida in fase di compilazione:gli elementi devono essere aggiunti in ordine strettamente crescente dei relativi orari di inizio. Lo strumento di creazione esegue la convalida nel miglior modo possibile al momento della creazione controllando la durata minima (ad esempio 1 ms per i preset o le durate note per gli inviluppi). Se viene rilevata una sovrapposizione in fase di compilazione, viene generato un IllegalArgumentException.
  • Allineamento della sincronizzazione della riproduzione:il framework fornisce il supporto della sincronizzazione best effort durante la riproduzione. Se un evento precedente è ancora in esecuzione quando arriva l'ora di inizio dell'evento successivo pianificato, il framework sposta automaticamente l'evento successivo al primo slot disponibile. In questo modo si evita la sovrapposizione degli eventi nella riproduzione fisica, garantendo che nessun evento aptico venga eliminato.

Effetti ripetuti

Un effetto ripetuto può essere aggiunto alla composizione utilizzando setRepeatingEffect(startTimeMillis, repeatingEffect, durationMillis). Una volta configurato un effetto ripetuto, non è possibile aggiungere altri elementi al generatore.

Supporto di riserva

Il supporto automatico di fallback a livello di framework è abilitato per impostazione predefinita per la vibrazione creata da VibrationEffect.Builder:

  • Fallback della piattaforma trasparente:se un dispositivo non supporta un Preset o un Envelope di base richiesto, il framework sostituisce automaticamente l'elemento non supportato con una vibrazione supportata appropriata in fase di runtime con il massimo impegno. La tua app non deve controllare manualmente le funzionalità del dispositivo (ad esempio isPresetSupported) prima di riprodurre composizioni create con VibrationEffect.Builder.
  • Eccezione per WaveformEnvelopeBuilder: gli effetti di inviluppo creati da WaveformEnvelopeBuilder (che specificano frequenze fisiche assolute in Hertz e ampiezze in G) non hanno il supporto di fallback automatico. Poiché le PWLE avanzate si basano su curve di frequenza hardware specifiche (FOAM), la loro sostituzione automatica comprometterebbe l'intento di progettazione. Se il dispositivo non supporta gli effetti PWLE o le frequenze richieste, queste vibrazioni non verranno riprodotte. Per la compatibilità universale, preferisci BasicEnvelopeBuilder.

Utilizzo di VibrationEffect.Builder

Per esempi di codice sulla composizione di effetti con VibrationEffect.Builder, vedi Creare composizioni ancorate alla cronologia con VibrationEffect.Builder.

VibrationEffect composizione di primitive

Una composizione di primitive VibrationEffect è un effetto di vibrazione creato utilizzando l'API VibrationEffect.startComposition. Questa API ti consente di creare una sequenza di primitive.

Compatibilità e requisiti

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

Controllare il supporto dei primitivi

Pertanto, quando utilizzi l'API VibrationEffect.Composition, devi controllare il supporto per primitiva utilizzando Vibrator.arePrimitivesSupported o Vibrator.areAllPrimitivesSupported prima di giocare.

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-are il supporto per primitiva.

Utilizzo delle composizioni primitive VibrationEffect

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

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

La forma più antica di vibrazione supportata su Android è la semplice attivazione/disattivazione del vibratore 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 intermittenti sono le notifiche, in cui, in ogni caso, è desiderata una vibrazione. Le vibrazioni a forma d'onda consentono inoltre in modo univoco 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 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 ritmica, 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 quasi tutti i dispositivi con un vibratore, come descritto più avanti in questa pagina.

La riproduzione di chiamate VibrationEffect o vibrate in stile precedente richiede 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 una soluzione migliore.

Utilizzo delle vibrazioni di attivazione/disattivazione

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

API di notifica

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

Tutti questi moduli utilizzano un modello di forma d'onda di base on-off, come descritto in precedenza, in cui la prima voce è il ritardo prima di attivare il vibratore.

Concetti generali

Diversi concetti si applicano alle superfici API descritte in precedenza.

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 il feedback aptico 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 indica che è 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 come 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 o on a seconda che siano zero o diversi da zero. Di conseguenza, le applicazioni che utilizzano il feedback aptico avanzato con ampiezze variabili devono valutare la possibilità di disattivarlo se il dispositivo non dispone del controllo dell'ampiezza.

Supporto degli effetti 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 sull'inviluppo vengono ignorate.