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

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

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

מבוא

• עדיין מפיצים את CAF Sender כחלק מ-Google Play Services באמצעות Android SDK Manager
• נוספו חבילות חדשות שכוללות אחריות לתאימות לרשימת המשימות לעיצוב של Google Cast (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. הפעולה הזו כוללת אתחול של 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 באופן עצלני ב-method 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, תהליך הגילוי מתחיל ומסתיים אוטומטית על ידי ה-framework כשהאפליקציה עוברת לחזית ולרקע, בהתאמה. אין להשתמש ב-MediaRouteSelector וב-MediaRouter.Callback.

כפתור הפעלת Cast ותיבת הדו-שיח של Cast

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

הכפתור להפעלת Cast עדיין מיושם על ידי MediaRouteButton ואפשר להוסיף אותו ל-Activity (באמצעות 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. חשוב לוודא שעדיין מבטלים את הרישום של רכיבי Listener כשהפרגמנטים, הפעילויות או האפליקציות המשויכים עוברים לרקע.

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

בדומה לגרסה 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.