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

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

אזהרה: אם אתם מפתחים אפליקציית שולח CAF או עוברים ל-CAF, אתם צריכים להשתמש ב-CastContext ולא ב-GoogleAPIClient כדי לגשת ל-Cast API. מומלץ להשתמש ב-GoogleAPIClient כדי לגשת לממשקי API אחרים של Google Play Services.

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

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

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

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

אזהרה: אם העברתם את האפליקציה ל-CAF והיא עדיין משתמשת ב-GoogleAPIClient כדי לגשת ל-Cast API, אתם צריכים להסיר את GoogleAPIClient ולפעול לפי ההוראות להפעלה כדי להשתמש ב-CastContext.