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

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

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

מבוא

• CAF Sender עדיין מופץ כחלק מ-Google Play Services באמצעות מנהל ה-SDK של Android
• נוספו חבילות חדשות שלוקחות אחריות לעמוד בדרישות רשימת המשימות של 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 ב"אפליקציה" תג האפליקציה קובץ 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"/>

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

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

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

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

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

בדומה ל-v2, CAF מנסה ליצור מחדש חיבורי רשת אבדו בגלל אובדן זמני של אות Wi-Fi או שגיאות רשת אחרות. זה עכשיו מתבצעת ברמת הסשן, סשן יכול להיכנס ל"השעיה" כשהערך החיבור ינותק, ויועבר חזרה אל מתי? הקישוריות משוחזרת. ה-framework מטפל בחיבור מחדש אל האפליקציה של מכשיר העזר באינטרנט וחיבור מחדש של כל ערוצי ההעברה (cast) במסגרת התהליך הזה.

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

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

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

פקד מדיה

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

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

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

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

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

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

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

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