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

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

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

מבוא

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

יחסי תלות

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

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

אתחול

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

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 בתג application בקובץ 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 ותיבת הדו-שיח של 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() של כל Activity באמצעות 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;
}

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

בקרת מכשיר

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

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

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

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

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

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

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

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

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

פקד מדיה

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

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

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

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

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

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

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

ב-CAF, המחלקה UIMediaController אחראית לרוב הפעולות האלה.

שכבת-על של היכרות

בגרסה 2 אין ממשק משתמש של שכבת-על עם הסבר.

CAF מספק תצוגה מותאמת אישית IntroductoryOverlay כדי להדגיש את הכפתור להפעלת Cast כשהוא מוצג למשתמשים בפעם הראשונה.

שלט קטן

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

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

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

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

ב-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.