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

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

ערכת ה-SDK של Cast CAF Sender משתמשת ב-CastContext כדי לנהל את GoogleAPIClient בשמכם. CastContext מנהל עבורכם מחזורי חיים, שגיאות וקריאות חוזרות (callback), כדי לפשט מאוד את הפיתוח של אפליקציית 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.

יחסי תלות

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

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

אתחול

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

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 בכל method ב-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"/>

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

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 Acceptr באמצעות GoogleApiClient. האינטראקציה בין השולח למקלט האינטרנט מיוצגת עכשיו כ'סשן'. המחלקה SessionManager מטפלת במחזור החיים של הסשן, ומתחילה ומפסיקה סשנים בתגובה לתנועות של משתמשים: סשן מתחיל כשהמשתמש בוחר מכשיר Cast בתיבת הדו-שיח של הפעלת Cast ומסתיים כשהמשתמש מקיש על הלחצן 'הפסקת ההעברה' בתיבת הדו-שיח של הפעלת Cast או כשאפליקציית השולח עצמה מסתיימת. אפליקציית השולח יכולה לקבל התראה על אירועים במחזור החיים של הסשן על ידי רישום של SessionManagerListener ב-SessionManager. הקריאות החוזרות (callback) של SessionManagerListener מגדירות שיטות לקריאה חוזרת (callback) לכל האירועים במחזור החיים של הסשן.

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

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

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

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

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

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

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

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

פקד מדיה

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

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

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

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

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

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

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

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

שכבת-על של סרטון היכרות

גרסה 2 לא מספקת ממשק משתמש בשכבת-על מסוג מבוא.

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.