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

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

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

מבוא

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

תלויות

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

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

אתחול

ב-CAF, נדרש שלב אתחול מפורש עבור Cast Framework. התהליך הזה כולל הפעלה של CastContextsingleton באמצעות 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 של Activity:

private CastContext mCastContext;

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

    mCastContext = CastContext.getSharedInstance(this);
}

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

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

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

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

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

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

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

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

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

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

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

פקד מדיה

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

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

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

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

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

ב-CAF, ‏ RemoteMediaClient מספק קריאות חוזרות שוות ערך דרך הממשק RemoteMediaClient.Listener. אפשר לרשום כל מספר של מאזינים ל-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.