הפעלה של בקרת ההפעלה

כדי להפעיל השמעת מדיה ב-Android Auto וב-Android Automotive OS‏ (AAOS), צריך להטמיע אמצעי בקרה להשמעה על ידי רישום של סשן מדיה וטיפול בשיטות הקריאה החוזרת שלו. בדף הזה נסביר איך:

• רושמים אובייקט MediaSessionCompat בשירות דפדפן המדיה.

• מטמיעים שיטות MediaSessionCompat.Callback כדי להגיב לבקשות של משתמשים להפעלה.

• הגדרת פעולות הפעלה רגילות ומותאמות אישית.

• מגדירים את מצב ההפעלה הראשוני של סשן המדיה.

• הוספת סמלים לציון פורמט האודיו.

• יצירת קישורים מפריטי מדיה שמופעלים כרגע.

‫Android Auto ו-AAOS שולחות פקודות לשליטה בהפעלה דרך MediaSessionCompat בשירות שלכם. צריך לרשום סשן ולהטמיע את שיטות הקריאה החוזרות שמשויכות אליו.

רישום של סשן מדיה

בשיטה onCreate של שירות הדפדפן למדיה, יוצרים מופע של MediaSessionCompat ואז קוראים ל-setSessionToken כדי לרשום את סשן המדיה. בקטע הקוד הבא מוצג איך ליצור ולהירשם לסשן מדיה:

Kotlin

override fun onCreate() {
    super.onCreate()
    ...
    // Start a new MediaSession.
    val session = MediaSessionCompat(this, "session tag").apply {
        // Set a callback object that implements MediaSession.Callback
        // to handle play control requests.
        setCallback(MyMediaSessionCallback())
    }
    sessionToken = session.sessionToken
    ...
}

Java

public void onCreate() {
    super.onCreate();
    ...
    // Start a new MediaSession.
    MediaSessionCompat session = new MediaSessionCompat(this, "session tag");
    setSessionToken(session.getSessionToken());

    // Set a callback object that implements MediaSession.Callback
    // to handle play control requests.
    session.setCallback(new MyMediaSessionCallback());
    ...
}

כשיוצרים את אובייקט סשן המדיה, מגדירים אובייקט של קריאה חוזרת שמשמש לטיפול בבקשות של בקרת ההפעלה. כדי ליצור את אובייקט הקריאה החוזרת (callback), צריך לספק הטמעה של המחלקה MediaSessionCompat.Callback באפליקציה. בסעיף הבא מוסבר איך להטמיע את האובייקט הזה.

הערה: כדי לבדוק את ההפעלה של סשן המדיה adb shell dumpsys media_session

הטמעה של פקודות הפעלה

כשמשתמש מבקש להפעיל פריט מדיה מהאפליקציה שלכם, מערכת Android Automotive OS ו-Android Auto משתמשות במחלקה MediaSessionCompat.Callback מאובייקט MediaSessionCompat של האפליקציה, שהן קיבלו משירות דפדפן המדיה של האפליקציה. כשמשתמש רוצה לשלוט בהפעלת התוכן, כמו השהיית ההפעלה או דילוג לטראק הבא, מערכות Android Auto ו-Android Automotive OS מפעילות אחת מהשיטות של אובייקט הקריאה החוזרת.

כדי לטפל בהפעלת תוכן, האפליקציה צריכה להרחיב את המחלקה המופשטת MediaSessionCompat.Callback ולהטמיע את השיטות שהאפליקציה תומכת בהן.

צריך להטמיע כל אחת משיטות הקריאה החוזרת האלה שמתאימות לסוג התוכן שמוצע באפליקציה:

onPrepare

מערכת AAOS מפעילה את השיטה הזו כשמקור המדיה משתנה.

onPlay

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

הערה: האפליקציה לא יכולה להתחיל להפעיל מוזיקה באופן אוטומטי כשמערכת Android Automotive או Android Auto מתחברות לשירות של דפדפן המדיה. מידע נוסף זמין במאמר בנושא הגדרת PlaybackState ראשוני.

onPlayFromMediaId

מופעל כשהמשתמש בוחר להפעיל פריט ספציפי. השיטה מקבלת את המזהה ששירות הדפדפן למדיה הקצה לפריט המדיה בהיררכיית התוכן.

onPlayFromSearch

מופעל כשמשתמש בוחר להפעיל תוכן מתוך שאילתת חיפוש. האפליקציה צריכה לבחור את האפשרות המתאימה על סמך מחרוזת החיפוש שהועברה.

onPause

מופעל כשמשתמש בוחר להשהות את ההפעלה.

onSkipToNext

מופעל כשהמשתמש בוחר לדלג לפריט הבא.

onSkipToPrevious

מופעל כשהמשתמש בוחר לדלג לפריט הקודם.

onStop

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

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

מידע נוסף על הפעלת תוכן אודיו זמין במאמרים סקירה כללית של Media Player, סקירה כללית של אפליקציית האודיו וסקירה כללית של ExoPlayer.

הגדרת פעולות הפעלה רגילות

מערכות Android Auto ו-AAOS מציגות אמצעי בקרה להפעלה על סמך הפעולות שמופעלות באובייקט PlaybackStateCompat. כברירת מחדל, האפליקציה צריכה לתמוך בפעולות הבאות:

• ACTION_PLAY
• ACTION_PAUSE
• ACTION_STOP
• ACTION_PLAY_FROM_MEDIA_ID
• ACTION_PLAY_FROM_SEARCH

בנוסף, האפליקציה יכולה לתמוך בפעולות הבאות אם הן רלוונטיות לתוכן של האפליקציה:

• ACTION_SKIP_TO_PREVIOUS
• ACTION_SKIP_TO_NEXT

בנוסף, אתם יכולים ליצור תור השמעה שיוצג למשתמש. כדי לעשות את זה, שולחים קריאה לרכיבי ה-method‏ setQueue ו-setQueueTitle, מפעילים את הפעולה ACTION_SKIP_TO_QUEUE_ITEM ומגדירים את הקריאה החוזרת onSkipToQueueItem.

בנוסף, הוספנו תמיכה בסמל מה שומעים עכשיו?, שמציין מה מושמע. כדי לעשות את זה, מבצעים קריאה ל-method‏ setActiveQueueItemId ומעבירים את המזהה של הפריט שמופעל בתור. צריך לעדכן את setActiveQueueItemId בכל פעם שיש שינוי בתור.

הערה: הוספת תמיכה בסמל השיר שמושמע עכשיו נדרשת רק כשמוסיפים תמיכה בתור השמעה.

‫Android Auto ו-AAOS מציגים כפתורים לכל פעולה שהופעלה, וגם את תור ההשמעה. כשמשתמשים לוחצים על הלחצנים האלה, המערכת מפעילה את הקריאה החוזרת המתאימה מ-MediaSessionCompat.Callback.

הזמנת מרחב שלא נמצא בשימוש

מערכות Android Auto ו-AAOS שומרות מקום בממשק המשתמש לפעולות ACTION_SKIP_TO_PREVIOUS ו-ACTION_SKIP_TO_NEXT. אם האפליקציה לא תומכת באחת מהפונקציות האלה, מערכות Android Auto ו-AAOS משתמשות במקום הזה כדי להציג פעולות מותאמות אישית שאתם יוצרים.

אם לא רוצים למלא את המקומות האלה בפעולות מותאמות אישית, אפשר להזמין אותם כך שמערכות Android Auto ו-AAOS ישאירו את המקום ריק בכל פעם שהאפליקציה לא תומכת בפונקציה המתאימה.

כדי לעשות את זה, מפעילים את ה-method‏ setExtras עם חבילת extras שמכילה קבועים שתואמים לפונקציות השמורות. ‫SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_NEXT תואם ל-ACTION_SKIP_TO_NEXT, ו- ‫SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_PREV תואם ל-ACTION_SKIP_TO_PREVIOUS. משתמשים בקבועי הערכים האלה כמפתחות בחבילה, ומשתמשים בערך הבוליאני true כערכים.

הגדרת PlaybackState ראשוני

מערכות Android Auto ו-AAOS מתקשרות עם שירות דפדפן המדיה, וסשן המדיה מתקשר עם סטטוס הפעלת התוכן באמצעות PlaybackStateCompat.

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

כדי לעשות את זה, צריך להגדיר את הערך הראשוני של PlaybackStateCompat בסשן המדיה ל-STATE_STOPPED,‏ STATE_PAUSED,‏ STATE_NONE או STATE_ERROR.

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

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

הוספה של פעולות הפעלה בהתאמה אישית

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

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

כדי להוסיף פעולות בהתאמה אישית, משתמשים בשיטה addCustomAction במחלקה PlaybackStateCompat.Builder. קטע הקוד הזה מראה איך להוסיף פעולה מותאמת אישית ל'הפעלת תחנת רדיו':

Kotlin

val customActionExtras = Bundle()
customActionExtras.putInt(
  androidx.media3.session.MediaConstants.EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT,
  androidx.media3.session.CommandButton.ICON_RADIO)

stateBuilder.addCustomAction(
    PlaybackStateCompat.CustomAction.Builder(
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA,
        resources.getString(R.string.start_radio_from_media),
        startRadioFromMediaIcon // or R.drawable.media3_icon_radio
    ).run {
        setExtras(customActionExtras)
        build()
    }
)

Java

Bundle customActionExtras = new Bundle();
customActionExtras.putInt(
  androidx.media3.session.MediaConstants.EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT,
  androidx.media3.session.CommandButton.ICON_RADIO);

stateBuilder.addCustomAction(
    new PlaybackStateCompat.CustomAction.Builder(
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA,
        resources.getString(R.string.start_radio_from_media),
        startRadioFromMediaIcon) // or R.drawable.media3_icon_radio
    .setExtras(customActionExtras)
    .build());

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

קטע הקוד הזה מראה איך האפליקציה יכולה להגיב לפעולה 'הפעלת תחנת רדיו':

Kotlin

override fun onCustomAction(action: String, extras: Bundle?) {
    when(action) {
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA -> {
            ...
        }
    }
}

Java

@Override
public void onCustomAction(@NonNull String action, Bundle extras) {
    if (CUSTOM_ACTION_START_RADIO_FROM_MEDIA.equals(action)) {
        ...
    }
}

מידע נוסף זמין בשיטה onCustomAction באפליקציה לדוגמה Universal Android Music Player ב-GitHub.

יצירת סמלים לפעולות מותאמות אישית

לכל פעולה בהתאמה אישית שיוצרים צריך להוסיף סמל.

אם התיאור של הסמל הזה תואם לאחד מהקבועים CommandButton.ICON_, מגדירים את ערך המספר השלם של המפתח EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT בתוספים של הפעולה המותאמת אישית. במערכות נתמכות, הפעולה הזו מבטלת את משאב הסמל שמועבר אל CustomAction.Builder, וכך מאפשרת לרכיבי המערכת לעבד באופן עקבי את הפעולה שלכם ופעולות הפעלה אחרות.

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

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

הוספת סגנונות סמלים חלופיים לפעולות מושבתות

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

איור 1. דוגמאות לסמלים של פעולות מותאמות אישית שלא תואמים לסגנון.

ציון פורמט האודיו

כדי לציין שהמדיה שמופעלת משתמשת בפורמט אודיו מיוחד, אתם יכולים לציין סמלים שמוצגים במכוניות שתומכות בתכונה הזו. אפשר להגדיר את KEY_CONTENT_FORMAT_TINTABLE_LARGE_ICON_URI ואת KEY_CONTENT_FORMAT_TINTABLE_SMALL_ICON_URI בחבילת התוספים של פריט המדיה שמופעל כרגע (מועבר אל MediaSession.setMetadata). צריך להגדיר את שני התוספים כך שיתאימו לפריסות השונות.

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

הוספת קישורים מהפריט שמופעל כרגע

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

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