הפניית API של Android haptics

בקטע הזה נספק מבוא לממשקי ה-API השונים של משוב מגע (haptics) שזמינים ב-Android. בנוסף, מוסבר מתי ואיך בודקים את תמיכת המכשיר הנדרשת כדי לוודא שהאפקטים החזותיים יפעלו כמצופה.

יש כמה דרכים שונות ליצור אפקטים של משוב מישוש, וחשוב להביא בחשבון את עקרונות העיצוב של משוב המישוש ב-Android כשבוחרים איזה אפקט להשתמש בו. בטבלה הבאה מפורטים המאפיינים הכלליים של כל גישה:

  • הזמינות חשובה במיוחד כשמתכננים חלופה להתנהגות, וצריך לשלב אותה עם בדיקת התמיכה במכשירים ספציפיים.
  • רטט ברור הוא תחושות חדות וברורות, פחות מטרידות למשתמשים.
  • חוויית מגע עשירה מאפשרת להביע רגשות בצורה חזקה יותר, ולרוב נדרשת לה חומרה עשירה יותר בתכונות.
ממשק API זמינות משוב מישוש ברור משוב פיזי עשיר
HapticFeedbackConstants Android מגרסה 1.5 ואילך
(לכל קבוע)
VibrationEffect מוגדר מראש Android 10 וגרסאות חדשות יותר
הרכב של VibrationEffect Android מגרסה 11 ואילך (לכל קבוע)
רטט מופעל/מושבת, רטט חד-פעמי ורטט גל Android 1

בנוסף, ממשקי API של התראות, שמתוארים בדף הזה, מאפשרים לכם להתאים אישית את האפקטים ההדמיים (haptic) שמתנגנים כשמתקבלות התראות.

בדף הזה מתוארים גם מושגים נוספים שקשורים לממשקי ה-API:

  • האם במכשיר יש ויברטור?
  • בקרת האמפליטודה מאפשרת לקבל אפקטים של משוב מישוש חלקים ועשירים יותר, אבל לא כל המכשירים תומכים בה.
  • VibrationAttributes() עוזר לכם לסווג את הרטט על סמך השימוש בו, כדי לוודא שההגדרות המתאימות של המשתמש יחולו עליו, וכך למנוע הפתעות למשתמש.

HapticFeedbackConstants

הכיתה HapticFeedbackConstants מספקת קבועים שמבוססים על פעולות, כדי לאפשר לאפליקציות להוסיף משוב מהותי (haptic) עקבי בחוויית השימוש במכשיר, במקום שתהיה לכל אפליקציה השפעה שונה על פעולות נפוצות.

תאימות ודרישות

השימוש בשיטה View.performHapticFeedback עם הקבועים האלה לא מחייב הרשאות מיוחדות לאפליקציה. הוא כפוף לנכס View.hapticFeedbackEnabled, שאם מגדירים אותו לערך false, הוא משבית את כל הקריאות לתגובת משוב מהרטט בתצוגה, כולל אלה שמוגדרות כברירת מחדל.ההגדרה העיקרית שקשורה לכך היא הנכס View.hapticFeedbackEnabled, שאם מגדירים אותו לערך false, הוא משבית את כל הקריאות לתגובת משוב מהרטט בתצוגה, כולל אלה שמוגדרות כברירת מחדל. השיטה גם מתייחסת להגדרת המערכת של המשתמש בנוגע להפעלת משוב מגע.

השיקול היחיד לגבי תאימות הוא רמת ה-SDK של הקבוע הספציפי של הפעולה.

אין צורך לספק התנהגות חלופית כשמשתמשים ב-HapticFeedbackConstants.

שימוש ב-HapticsFeedbackConstants

פרטים על השימוש ב-HapticFeedbackConstants זמינים במאמר הוספת משוב פיזי לאירועים.

מוגדרים מראש VibrationEffect

המחלקה VibrationEffect מספקת כמה קבועים מוגדרים מראש, כמו CLICK,‏ TICK ו-DOUBLE_CLICK. יכול להיות שהאפקטים האלה יעברו אופטימיזציה למכשיר.

תאימות ודרישות

כדי להפעיל VibrationEffect כלשהו, נדרשת ההרשאה VIBRATE במניפסט של האפליקציה.

אין צורך לספק התנהגות חלופית כשמשתמשים ב-VibrationEffect מוגדר מראש, כי קבועים שלא הוגדרה להם הטמעה שמותאמת למכשיר חוזרים לחלופה הרגילה של הפלטפורמה.

ממשקי ה-API Vibrator.areEffectsSupported ו-Vibrator.areAllEffectsSupported משמשים לקביעת אם יש הטמעה שמותאמת למכשיר. עדיין אפשר להשתמש באפקטים מוגדרים מראש בלי הטמעה אופטימלית, והם ישתמשו בחלופה הרגילה של הפלטפורמה. לכן, צריך להשתמש בממשקי ה-API האלה רק אם רוצים לבדוק אם האפקט מותאם למכשיר.areEffectsSupported

השיטות לבדיקת ההשפעה יכולות להחזיר אחד משלושת הערכים הבאים:

  • VIBRATION_EFFECT_SUPPORT_YES מציין שהמכשיר תומך באפקט הזה ועברה לו אופטימיזציה.
  • VIBRATION_EFFECT_SUPPORT_NO מציין שהמכשיר לא כולל תמיכה אופטימיזציה, אבל עדיין משתמש בחלופה של הפלטפורמה.
  • הערך VIBRATION_EFFECT_SUPPORT_UNKNOWN מציין שהמערכת לא יודעת אם ההטמעה בוצעה בצורה אופטימלית או לא.

מאחר שערך UNKNOWN מציין ש-API הבדיקה לא זמין, בדרך כלל הוא מוחזר לכל האפקטים או לאף אחד מהם. במכשירים האלה מתבצעת חזרה דינמית.

שימוש ב-VibrationEffect שהוגדר מראש

פרטים על שימוש ב-VibrationEffect מוגדר מראש זמינים במאמר שימוש ב-VibrationEffect מוגדר מראש ליצירת משוב חישתי.

הרכב VibrationEffect

קומפוזיציה של VibrationEffect היא אפקט רטט שנוצר באמצעות ה-API של VibrationEffect.startComposition. ממשק ה-API הזה מאפשר ליצור חוויית מגע עשירה באמצעות יצירת רצף של רכיבים בסיסיים עם עיכובים ועוצמות בהתאמה אישית. עם זאת, חשוב לוודא שהמכשיר תומך בתכונות שאתם משלבים כדי למנוע חוויה כללית לא עקבית.

תאימות ודרישות

כדי להפעיל VibrationEffect כלשהו, נדרשת ההרשאה VIBRATE במניפסט של האפליקציה.

לא כל המכשירים תומכים בכל התכונות של Composition API, וחשוב לוודא שהפרימיטיבים זמינים.

בדיקת התמיכה ברכיב הרטט הבסיסי

אפשר לאחזר את התמיכה לכל פרימיטיב באמצעות השיטה Vibrator.arePrimitivesSupported. לחלופין, אפשר לבדוק יחד קבוצה של פרימיטיבים באמצעות השיטה Vibrator.areAllPrimitivesSupported – זה שווה ערך לקריאה ל-AND של התמיכה לכל פרימיטיב.

שימוש ב-VibrationEffect Compositions

פרטים על שימוש בהרכבים של VibrationEffect זמינים במאמר יצירת קומפוזיציות של רטט.

רטט בפולסים, רטט חד-פעמי ורטט גל

צורת הרטט העתיקה ביותר שנתמכת ב-Android היא דפוסים פשוטים של הפעלה/כיבוי של הרטט עם משכי זמן שניתן להגדיר. בדרך כלל, ממשקי ה-API האלה לא תואמים לעקרונות העיצוב של משוב מגע כי הם יכולים ליצור משוב מגע צורמני. מומלץ להימנע מהם, אלא אם אין ברירה אחרת.

התרחיש לדוגמה הנפוץ ביותר לשימוש ברטט מופעל-מושבת הוא התראות, שבהן תמיד רצוי שתהיה רטט כלשהו. רטט של צורת גל מאפשר גם לחזור על דפוס ללא הגבלת זמן, כמו צלצול.

דפוס חד-פעמי מתייחס לרטט פעם אחת למשך N אלפיות השנייה.

יש שני סוגים של דפוסי צורת גל:

  • Timings-only סוג הגל הזה הוא תיאור של משכי זמן לסירוגין שבהם המכשיר כבוי ומשכי זמן שבהם הוא מופעל. התזמונים מתחילים עם משך הזמן שבו המכשיר היה מושבת. לכן, לרוב דפוסי הגל מתחילים עם ערך אפס כדי לציין שהרטט מתחיל באופן מיידי.
  • זמנים ואמפליטודות לסוג הגל הזה יש מערך נוסף של אמפליטודות שתואמות לכל נתון תזמון, במקום הפעלה/כיבוי משתמעים של הטופס הראשון. עם זאת, חשוב לבדוק שהמכשיר תומך בשליטה באמפליטודה כדי לוודא שאפשר להשיג את השינוי הרצוי בקנה המידה.

תאימות ודרישות

רטט הפעלה/כיבוי הוא צורת הרטט העתיקה ביותר, ולכן יש תמיכה בו כמעט בכל המכשירים עם ויברטור, כפי שמתואר בהמשך הדף.

כדי להפעיל קריאות מסוג VibrationEffect או קריאות בסגנון הקודם מסוג vibrate, נדרשת ההרשאה VIBRATE במניפסט של האפליקציה.

כשמשתמשים בערכי אמפליטודה שונים בצורת גל, מומלץ מאוד לוודא שהמכשיר תומך בבקרת אמפליטודה.

בדיקת התמיכה בבקרת אמפליטודה

ערכים של אמפליטודה שאינם אפס מעוגלים כלפי מעלה ל-100% במכשירים ללא בקרת אמפליטודה, לכן חשוב לבדוק אם יש תמיכה באמצעות Vibrator.hasAmplitudeControl. פרטים נוספים זמינים במאמר בקרת עוצמה.

כדאי לבדוק היטב אם לאפקט יש איכות מספקת ללא בקרת עוצמה. עדיף להשתמש ברטט מתוכנן במיוחד, עם מצב הפעלה/כיבוי.

שימוש ברטט 'הפעלה-השבתה'

ברמות SDK חדשות יותר, כל מצבי הרטט אוחדו לכיתה אחת VibrationEffect עם יכולות מגוונות, שבה הרטט הפשוט נוצר באמצעות VibrationEffect.createOneshot או VibrationEffect.createWaveform.

Notification APIs

כשאתם מתאימים אישית את ההתראות באפליקציה, אתם יכולים להשתמש באחד מ-API הבאים כדי לשייך דפוס לכל ערוץ התראות:

כל הטפסים האלה כוללים דפוס גל בסיסי של הפעלה/כיבוי, כפי שמתואר למעלה, כאשר הערך הראשון הוא העיכוב לפני הפעלת הרטט.

מושגים כלליים

יש כמה מושגים שחלים על כל ממשקי ה-API שמפורטים למעלה.

האם יש במכשיר ויברטור?

אפשר לקבל מ-context.getSystemService(Vibrator.class) את הכיתה Vibrator שאינה null. אם אין במכשיר ויברטור, לקריאות לממשקי ה-API של הרטט אין השפעה, ולכן האפליקציות לא צריכות לשלוט בכל הפעולות של הרטט בהתאם לתנאי מסוים. עם זאת, אם יש צורך, אפליקציה יכולה להפעיל את hasVibrator() כדי לקבוע אם מדובר ברטט אמיתי (true) או ב-stub (false).

האם המשתמש השבית את המשוב החזותי למגע?

בהטמעות מותאמות אישית מסוימות, יכול להיות שתצטרכו לבדוק באופן ידני אם המשתמש השבית לחלוטין את ההגדרה משוב מגע ב-Android. במקרה כזה, צריך לדכא את ההשפעות של משוב המגע. אפשר לשלוח שאילתה לגבי ההגדרה הזו באמצעות המפתח HAPTIC_FEEDBACK_ENABLED, כאשר ערך אפס מציין שההגדרה מושבתת.

מאפייני רטט

אפשר לספק מאפייני רטט (כרגע בפורמט AudioAttributes) כדי לעזור למערכת להבין את מטרת הרטט. צריך להשתמש בהצהרה הזו כשמפעילים רטט כשהאפליקציה פועלת ברקע, כי רק רטט שמעורר תשומת לב נתמך לשימוש ברקע.

יצירת AudioAttributes מפורטת במסמכי העזרה של הכיתה, וצריך להתייחס אליה כרטט ולא כצליל.

לידיעתכם, ברוב המקרים סוג התוכן הוא CONTENT_TYPE_SONIFICATION, והשימוש יכול להיות בערכים כמו USAGE_ASSISTANCE_SONIFICATION עבור משוב מגע בחזית או USAGE_ALARM עבור אזעקה ברקע. דגלים של אודיו לא משפיעים על הרטט.

בקרת משרעת (אמפליטודה)

אם לוויברטור יש בקרת אמפליטודה, הוא יכול להפעיל רטט בעוצמות שונות. זוהי יכולת חשובה ליצירת רטט עשיר, וגם מאפשרת למשתמש לשלוט בעוצמות ברירת המחדל של הרטט.

כדי לבדוק אם יש תמיכה בשליטה באמפליטודה, אפשר להריץ את הפונקציה Vibrator.hasAmplitudeControl. אם הוויברטור לא תומך באמפלטוּדה, כל ערכי האמפלטוּדה ימופו למצב כבוי/מופעל על סמך הערך שלהם (אפס/לא אפס). לכן, באפליקציות שמשתמשות בהפעלות מגע עשויות עם אמפליטודות משתנות, כדאי להשבית אותן אם אין במכשיר בקרת אמפליטודה.