העברה של אפליקציית Android Sender מ-Cast SDK v2 ל-Cast Application Framework (CAF)

התהליך הבא מאפשר להמיר את אפליקציית השולח ל-Android מ-Cast SDK v2 ל-CAF Sender, שמבוסס על הסינגלטון של CastContext.

ערכת ה-SDK של השולח CAF להעברה משתמשת ב-CastContext כדי לנהל את GoogleAPIClient בשמך. חברת CastContext מנהלת עבורך מחזורי חיים, שגיאות וקריאות חוזרות (callback) ומפשטת מאוד את הפיתוח של אפליקציית Cast.

מבוא

  • השירות CAF Sender עדיין מופץ כחלק משירותי Google Play באמצעות מנהל ה-SDK של Android
  • נוספו חבילות חדשות שמקבלות אחריות על הציות לרשימת המשימות לעיצוב Google Cast (com.google.android.gms.cast.framework.*)
  • ה-CAF שולח מספק ווידג'טים שתואמים לדרישות של Cast UX. גרסה 2 לא סיפקה רכיבים בממשק המשתמש ודורשת ממך להטמיע את הווידג'טים האלה.
  • השימוש ב-GoogleApiClient אינו נדרש יותר לשימוש ב-Cast API.
  • כתוביות ב-CAF שולח דומות לגרסה 2.

יחסי תלות

יחסי התלות של V2 ו-CAF בין ספריות התמיכה לבין Google Play Services (9.2.0 ואילך) הם זהים, כפי שמתואר במדריך לתכונות של ספריית התמיכה

גרסת ה-SDK המינימלית של Android שנתמכת ב-CAF היא 9 (Gingerbread).

אתחול

ב-CAF, נדרש שלב אתחול מפורש עבור ה-Cast framework. כדי לעשות את זה צריך להפעיל את ה-singleton CastContext, באמצעות OptionsProvider מתאים כדי לציין את מזהה האפליקציה של Web Acceptr וכל אפשרות גלובלית אחרת.

public class CastOptionsProvider implements OptionsProvider {

    @Override
    public CastOptions getCastOptions(Context context) {
        return new CastOptions.Builder()
                .setReceiverApplicationId(context.getString(R.string.app_id))
                .build();
    }

    @Override
    public List<SessionProvider> getAdditionalSessionProviders(Context context) {
        return null;
    }
}

מצהירים על OptionsProvider בתג "אפליקציה" בקובץ AndroidManifest.xml של האפליקציה:

<application>
...
    <meta-data
        android:name=
            "com.google.android.gms.cast.framework.OPTIONS_PROVIDER_CLASS_NAME"
        android:value="com.google.sample.cast.refplayer.CastOptionsProvider" />
</application>

מאתחלים באופן מדורג את CastContext בשיטת onCreate של כל פעילות:

private CastContext mCastContext;

protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.video_browser);
    setupActionBar();

    mCastContext = CastContext.getSharedInstance(this);
}

לא היה צורך בצעדים האלה בגרסה 2.

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

ב-CAF, תהליך הגילוי מתחיל ונעצר אוטומטית על ידי ה-framework כשהאפליקציה עוברת לחזית ועוברת לרקע, בהתאמה. אין להשתמש ב-MediaRouteSelector וב-MediaRouter.Callback.

לחצן הפעלת Cast ותיבת הדו-שיח 'העברה'

כמו בגרסה 2, הרכיבים האלה מסופקים על ידי ספריית התמיכה של MediaRouter.

לחצן הפעלת Cast עדיין מוטמע על ידי MediaRouteButton וניתן להוסיף אותו לפעילות שלך (באמצעות ActionBar או Toolbar), כפריט בתפריט שלך.

<item
    android:id="@+id/media_route_menu_item"
    android:title="@string/media_route_menu_title"
    app:actionProviderClass="android.support.v7.app.MediaRouteActionProvider"
    app:showAsAction="always"/>

כדי לשנות את השיטה onCreateOptionMenu() בכל פעילות, אפשר להשתמש ב-CastButtonFactory כדי לחבר את MediaRouteButton ל-Cast framework:

private MenuItem mediaRouteMenuItem;

public boolean onCreateOptionsMenu(Menu menu) {
    super.onCreateOptionsMenu(menu);
    getMenuInflater().inflate(R.menu.browse, menu);
    mediaRouteMenuItem =
        CastButtonFactory.setUpMediaRouteButton(getApplicationContext(),
                                                menu,
                                                R.id.media_route_menu_item);
    return true;
}

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

בקרת מכשיר

ב-CAF, בקרת המכשיר מטופלת ברובה על ידי ה-framework. אפליקציית השולח לא צריכה לטפל (ולא לנסות לטפל בה) בהתחברות למכשיר והפעלת האפליקציה Web Aware באמצעות GoogleApiClient. האינטראקציה בין השולח לבין המקבל מיוצגת עכשיו כ "סשן". המחלקה SessionManager מטפלת במחזור החיים של ההפעלה ומתחילה ומפסיקה באופן אוטומטי פעילות בהתאם לתנועות של המשתמשים: סשן מתחיל כשהמשתמש בוחר מכשיר העברה בתיבת הדו-שיח של ההעברה, ומסתיים כשהמשתמש מקיש על הלחצן 'הפסקת ההעברה' בתיבת הדו-שיח של ההעברה, או כשאפליקציית השולח עצמה מסתיימת. אפשר להודיע לאפליקציית השולח לגבי אירועים במחזור החיים של הסשן על ידי רישום SessionManagerListener ב-SessionManager. הקריאות החוזרות של SessionManagerListener מגדירות שיטות קריאה חוזרת לכל אירועי מחזור החיים של ההפעלה.

המחלקה CastSession מייצגת סשן עם מכשיר CAST. לכיתה יש שיטות לשליטה בעוצמת הקול ובמצב ההשתקה של המכשיר, כפי שנעשה בעבר בגרסה 2 באמצעות שיטות ב-Cast.CastApi.

בגרסה 2, קריאות חוזרות (callback) של Cast.Listener סיפקו התראות לגבי שינויים במצב המכשיר, כולל עוצמת קול, מצב השתקה, סטטוס המתנה וכו'.

ב-CAF, ההתראות על שינוי מצב עוצמת הקול או ההשתקה עדיין נשלחות בשיטות של קריאה חוזרת (callback) ב-Cast.Listener; המאזינים האלה רשומים ב-CastSession. כל ההתראות על מצבי המכשיר שנותרו מועברות באמצעות CastStateListener callbacks; המאזינים האלה רשומים ב-CastSession. חשוב לוודא שעדיין מבטלים רישום של מאזינים כשהקטעים, הפעילויות או האפליקציות המשויכים עוברים לרקע.

לוגיקת החיבור מחדש

בדומה לגרסה 2, CAF מנסה ליצור מחדש חיבורי רשת שאבדו בגלל אובדן זמני של אות Wi-Fi או שגיאות אחרות ברשת. זהו עכשיו ברמת הסשן. סשן יכול לעבור למצב 'מושעה' כשהחיבור יאבד, והוא יעבור בחזרה למצב 'מחובר' כשהקישוריות תשוחזר. במסגרת התהליך הזה, תצטרכו להתחבר מחדש לאפליקציית Web Aware ולחבר מחדש את כל ערוצי ה-Cast.

בנוסף, ב-CAF מוסיפים גם המשך אוטומטי של סשן, שמופעל כברירת מחדל (ואפשר להשבית אותו באמצעות CastOptions. אם אפליקציית השולח נשלחת לרקע או מפסיקה (על ידי החלקה הצידה או בגלל קריסה) בזמן שמתבצעת סשן העברה, ה-framework ינסה להמשיך את הסשן כשאפליקציית השולח תחזור לחזית או תופעל מחדש. הדבר מטופל באופן אוטומטי על ידי SessionManager, מה שינפיק את הקריאות החוזרות המתאימות בכל מכונות SessionManagerListener רשומות.

רישום ערוץ מותאם אישית

בגרסה 2, ערוצים מותאמים אישית (המוטמעים באמצעות Cast.MessageReceivedCallback) רשומים ב-Cast.CastApi. ב-CAF, ערוצים מותאמים אישית רשומים במקום זאת במכונה CastSession. אפשר לבצע את הרישום באמצעות שיטת הקריאה החוזרת SessionManagerListener.onSessionStarted. באפליקציות מדיה אין יותר צורך לרשום את ערוץ הבקרה של המדיה באופן מפורש דרך Cast.CastApi.setMessageReceivedCallbacks; פרטים נוספים מופיעים בקטע הבא.

פקד מדיה

המחלקה v2 RemoteMediaPlayer הוצאה משימוש ואין להשתמש בה. ב-CAF הן מחליפה את המחלקה החדשה RemoteMediaClient, שמספקת פונקציונליות מקבילה ב-API נוח יותר. אין צורך לאתחל או לרשום את האובייקט הזה באופן מפורש. ה-framework תיצור ממנו באופן אוטומטי את האובייקט ותרשום את ערוץ המדיה שבבסיסו בזמן ההתחלה של ההפעלה, אם אפליקציית Web Acceptr שמחוברת אליו תומכת במרחב השמות של המדיה.

ניתן לגשת ל-RemoteMediaClient בתור השיטה getRemoteMediaClient של האובייקט CastSession.

בגרסה 2, כל בקשות המדיה שיישלחו ב-RemoteMediaPlayer יחזירו RemoteMediaPlayer.MediaChannelResult באמצעות קריאה חוזרת (callback) של PendingResult.

ב-CAF, כל בקשות המדיה שנשלחות ב-RemoteMediaClient מחזירות RemoteMediaClient.MediaChannelResult באמצעות PendingResult קריאה חוזרת, שיכולה לשמש למעקב אחר ההתקדמות והתוצאה הסופית של הבקשה.

גרסה 2 RemoteMediaPlayer תשלח התראות על שינויים במצב נגן המדיה ב-WebReceiver דרך RemoteMediaPlayer.OnStatusUpdatedListener.

ב-CAF, RemoteMediaClient מספק קריאות חוזרות (callback) מקבילות דרך הממשק של RemoteMediaClient.Listener. אפשר לרשום כל מספר של מאזינים באמצעות RemoteMediaClient, דבר שמאפשר למספר רכיבי שולח לשתף את המופע היחיד של RemoteMediaClient שמשויך לסשן.

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

ב-CAF, הכיתה UIMediaController לוקחת את רוב האחריות הזו.

שכבת-על למתחילים

V2 לא מספק ממשק משתמש מקדים של שכבת-על.

ב-CAF יש תצוגה בהתאמה אישית IntroductoryOverlay, שלחיצה עליו תדגיש את לחצן הפעלת Cast כשהוא מוצג למשתמשים בפעם הראשונה.

מיני שלט רחוק

בגרסה 2, צריך להטמיע מיני שלט רחוק מאפס באפליקציית השולח.

ב-CAF, ה-SDK מספק תצוגה מותאמת אישית, MiniControllerFragment, שאפשר להוסיף לקובץ הפריסה של האפליקציה, שבו יוצגו הפעילויות שבהן רוצים להציג את המיני-בקר.

התראות ומסך נעילה

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

ב-CAF, ה-SDK מספק NotificationsOptions.Builder כדי ליצור בקרי מדיה להתראות ולמסך הנעילה באפליקציית השולח. ניתן להפעיל את פקדי ההתראות ומסך הנעילה באמצעות CastOptions כשמפעילים את CastContext.

public CastOptions getCastOptions(Context context) {
    NotificationOptions notificationOptions = new NotificationOptions.Builder()
            .setTargetActivityClassName(VideoBrowserActivity.class.getName())
            .build();
    CastMediaOptions mediaOptions = new CastMediaOptions.Builder()
            .setNotificationOptions(notificationOptions)
            .build();

    return new CastOptions.Builder()
            .setReceiverApplicationId(context.getString(R.string.app_id))
            .setCastMediaOptions(mediaOptions)
            .build();
}

שלט רחוק מורחב

בגרסה 2, צריך להטמיע בקר מורחב מאפס באפליקציית השולח.

ב-CAF יש כיתת עזרה ל-UIMediaController שבה קל יותר לבנות בקר מורחב משלכם.

ב-CAF מוסיפים ווידג'ט מורחב מראש של בקר, ExpandedControllerActivity, שתוכלו פשוט להוסיף לאפליקציה. כבר לא צריך להטמיע בקר מורחב בהתאמה אישית באמצעות UIMediaController.

מיקוד אודיו

בגרסה 2, צריך להשתמש ב-MediaSessionCompat כדי לנהל את מיקוד האודיו.

ב-CAF, מיקוד האודיו מנוהל באופן אוטומטי.

רישום ביומן של ניפוי באגים

ב-CAF אין אפשרויות לרישום ביומן.

אפליקציות לדוגמה

יש לנו מדריכים ל-Codelab ואפליקציות לדוגמה שמשתמשות ב-CAF.