Questa sezione fornisce un'introduzione alle varie API di tecnologia aptica disponibili in Android. Inoltre, spiega quando e come verificare se il tuo dispositivo supporta gli effetti aptico necessari per garantire che vengano riprodotti come previsto.
Esistono diversi modi per creare effetti aptico ed è importante tenere conto dei principi di progettazione della tecnologia aptica di Android quando si sceglie tra le varie opzioni. La tabella seguente riassume 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.
- Le chiare vibrazioni sono sensazioni nitide e pulite meno fastidiose per gli utenti.
- Le funzionalità di aptica avanzata sono più espressive e spesso richiedono hardware più ricco di funzionalità.
| API surface | Disponibilità | Feedback aptico chiaro | Feedback aptico avanzato |
|---|---|---|---|
| HapticFeedbackConstants | Android 1.5 e versioni successive (in base alla costante) |
||
| VibrationEffect predefinito | Android 10 e versioni successive | ||
| Composizione VibrationEffect | Android 11 e versioni successive (per costante) | ||
| Vibrazioni on/off, una tantum e con forma d'onda | Android 1 |
Inoltre, le API di notifica, descritte in questa pagina, ti consentono di personalizzare gli effetti aptico riprodotti per le notifiche in arrivo.
In questa pagina sono descritti anche altri concetti che riguardano le interfacce API:
- Il dispositivo è dotato di vibrazione?
- Il controllo dell'ampiezza consente effetti aptico più fluidi e intensi, ma non è supportato da tutti i dispositivi.
VibrationAttributes()ti aiuta a classificare la vibrazione in base al suo utilizzo, garantendo che vengano applicate le impostazioni utente appropriate ed evitando così sorprese all'utente.
HapticFeedbackConstants
La classe HapticFeedbackConstants fornisce costanti basate sulle azioni per consentire alle app di aggiungere feedback aptico coerenti nell'esperienza del dispositivo, anziché avere effetti diversi per le azioni comuni in ogni app.
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 al tocco.
L'unico aspetto di compatibilità è il livello SDK della costante specifica per l'azione.
Non è necessario fornire un comportamento alternativo quando si utilizza
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 utilizza VibrationEffect predefinito, poiché le costanti che non hanno un'implementazione ottimizzata per il dispositivo tornano a un valore 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 essere utilizzati anche senza un'implementazione ottimizzata e si basano sulla funzionalità di riserva della piattaforma standard. Di conseguenza, queste APIareEffectsSupported sono necessarie solo se un'applicazione vuole prendere in considerazione se l'effetto è ottimizzato per il dispositivo o meno.
I metodi di controllo dell'effetto possono restituire uno dei tre valori:
VIBRATION_EFFECT_SUPPORT_YESindica che il dispositivo ha un supporto ottimizzato per questo effetto.VIBRATION_EFFECT_SUPPORT_NOindica che il dispositivo non ha un'assistenza ottimizzata, ma utilizza comunque la piattaforma di riserva.VIBRATION_EFFECT_SUPPORT_UNKNOWNindica che il sistema non sa se l'implementazione è ottimizzata o meno.
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.
Composizione VibrationEffect
Una composizione VibrationEffect è un effetto di vibrazione creato utilizzando l'API
VibrationEffect.startComposition. Questa API consente di creare feedback aptico espressivi creando una sequenza di primitive con ritardi e intensità personalizzati. Tuttavia, assicurati 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 di composizione ed è importante assicurarsi che le primitive siano disponibili.
Verificare il supporto delle primitive di vibrazione
Il supporto per elemento può essere recuperato utilizzando il metodo
Vibrator.arePrimitivesSupported. In alternativa, un insieme di primitive può essere controllato insieme utilizzando il metodo Vibrator.areAllPrimitivesSupported, il che equivale a AND il supporto per primitiva.
Utilizzo di VibrationEffect Compositions
Per informazioni dettagliate sull'utilizzo delle composizioni VibrationEffect, vedi Creare composizioni di vibrazione.
Vibrazioni on-off, una tantum e con forma d'onda
La forma più antica di vibrazione supportata su Android è costituita da semplici pattern di accensione/spegnimento del vibratore con durate configurabili. In genere, queste API non sono ben allineate ai principi di progettazione dell'aptica perché possono generare vibrazioni. Evitale, a meno che non sia l'ultima risorsa.
Il caso d'uso più comune per le vibrazioni on-off è costituito dalle notifiche, in cui, indipendentemente da cosa accade, è auspicabile una certa vibrazione. Le vibrazioni con forma d'onda consentono inoltre di ripetere in modo unico un pattern a tempo indeterminato, come puoi immaginare per una suoneria.
Un pattern una tantum si riferisce alla vibrazione una volta per N millisecondi.
Esistono due tipi di pattern di forma d'onda:
- Solo tempistiche. Questo tipo di forma d'onda è una descrizione di durate spente in modalità off e durate spente in modalità on. I tempi iniziano con la durata in stato di disattivazione. Di conseguenza, i pattern di forme d'onda iniziano spesso con un valore zero per indicare di iniziare immediatamente a vibrare.
- Tempi e ampiezze. Questo tipo di forma d'onda ha un array aggiuntivo di amplitudini da abbinare a ogni valore di tempo, anziché all'on/off implicito del primo modulo. Tuttavia, è importante verificare che il dispositivo supporti il controllo dell'ampiezza per assicurarsi che sia possibile ottenere la scalabilità prevista.
Compatibilità e requisiti
Poiché le vibrazioni on/off sono la forma più antica di vibrazioni, sono supportate su quasi tutti i dispositivi con un vibratore, come descritto più avanti in questa pagina.
La riproduzione di chiamate VibrationEffect o vibrate di tipo precedente richiede l'autorizzazione VIBRATE nel file manifest dell'app.
Quando utilizzi valori di ampiezza diversi in un'onda, ti consigliamo vivamente di verificare che il dispositivo supporti il controllo dell'ampiezza.
Verificare il supporto del controllo dell'ampiezza
I valori di ampiezza diversi da zero vengono arrotondati per eccesso al 100% sui dispositivi senza controllo dell'ampiezza, pertanto è importante verificare se il supporto è presente utilizzando
Vibrator.hasAmplitudeControl. Per ulteriori dettagli, consulta il controllo dell'ampiezza.
Devi valutare attentamente se l'effetto ha una qualità sufficiente senza il controllo dell'ampiezza. Potrebbe essere meglio ricorrere a una vibrazione on/off progettata esplicitamente.
Utilizzo delle vibrazioni on-off
Nei livelli SDK più recenti, tutte le modalità di vibrazione sono state consolidate in una singola 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 ciascun canale di notifica:
- AndroidX
- Android
Tutti questi moduli adottano un pattern di forma d'onda on-off di base, come descritto in precedenza, dove la prima voce è il ritardo prima di attivare il vibratore.
Concetti generali
A tutte le piattaforme API descritte sopra si applicano diversi concetti.
Il dispositivo ha un vibratore?
Puoi ottenere un oggetto Vibrator non nullo 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 attivare tutte le funzionalità di aptica in base 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 tecnologia aptica tocco?
Alcune implementazioni personalizzate potrebbero richiedere di verificare manualmente se l'utente ha disattivato completamente l'impostazione Feedback tocco di Android, nel qual caso gli effetti di feedback tocco devono essere eliminati. È possibile eseguire query su questa impostazione utilizzando la chiave HAPTIC_FEEDBACK_ENABLED, dove un valore pari a zero indica che l'impostazione è disattivata.
Attributi 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 avvii una vibrazione quando l'app è in background, poiché solo le tecnologie aptica di attenzione sono supportate per l'utilizzo in background.
La creazione di AudioAttributes è trattata nella documentazione della classe e deve essere considerata come vibrazione anziché suono.
Come guida, nella maggior parte dei casi il tipo di contenuto è CONTENT_TYPE_SONIFICATION e l'utilizzo potrebbe essere valori come USAGE_ASSISTANCE_SONIFICATION per il feedback tocco 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 produrre feedback aptico avanzato, oltre a consentire potenzialmente all'utente di controllare le intensità aptica 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/diverso da zero. Di conseguenza, le applicazioni che utilizzano feedback aptico avanzato con ampiezze diverse dovrebbero valutare la possibilità di disattivarle se il dispositivo non dispone del controllo dell'ampiezza.