ब्राउज़ करने की कस्टम कार्रवाइयां लागू करना

कस्टम प्लेबैक ऐक्शन का इस्तेमाल करके, प्लेबैक व्यू में खास सुविधाएं जोड़ी जा सकती हैं. इसी तरह, कस्टम ब्राउज़ ऐक्शन का इस्तेमाल करके, ब्राउज़िंग व्यू में खास सुविधाएं जोड़ी जा सकती हैं. उदाहरण के लिए, कस्टम ब्राउज़ ऐक्शन का इस्तेमाल किया जा सकता है, ताकि उपयोगकर्ता प्लेलिस्ट डाउनलोड कर सकें या किसी आइटम को कतार में जोड़ सकें.

जब ओरिजनल इक्विपमेंट मैन्युफ़ैक्चरर (ओईएम) की ओर से दिखाई गई कस्टम कार्रवाइयों से ज़्यादा कस्टम कार्रवाइयां मौजूद होती हैं, तो उपयोगकर्ता को ओवरफ़्लो मेन्यू दिखता है. हर कस्टम ब्राउज़ ऐक्शन को इनके साथ तय किया जाता है:

• कार्रवाई का आईडी: यूनीक स्ट्रिंग आइडेंटिफ़ायर
• कार्रवाई का लेबल: उपयोगकर्ता को दिखने वाला टेक्स्ट
• कार्रवाई वाले आइकॉन का यूनिफ़ॉर्म रिसॉर्स आइडेंटिफ़ायर (यूआरआई): वेक्टर ड्रॉएबल, जिसे रंग दिया जा सकता है

पहली इमेज. कस्टम ब्राउज़ ऐक्शन ओवरफ़्लो.

BrowseRoot के हिस्से के तौर पर, कस्टम ब्राउज़ कार्रवाइयों की सूची को ग्लोबल लेवल पर तय किया जाता है. इसके बाद, इनमें से कुछ कार्रवाइयों को अलग-अलग MediaItem से अटैच करें.

जब कोई उपयोगकर्ता, ब्राउज़ करने की कस्टम कार्रवाई से इंटरैक्ट करता है, तो आपके ऐप्लिकेशन को onCustomAction में कॉलबैक मिलता है. इसके बाद, कार्रवाई को मैनेज करें. अगर ज़रूरी हो, तो MediaItem के लिए कार्रवाइयों की सूची अपडेट करें. यह Favorite और Download जैसी स्टेटफ़ुल कार्रवाइयों के लिए उपयोगी है. जिन कार्रवाइयों के लिए अपडेट की ज़रूरत नहीं होती है उनके लिए, कार्रवाइयों की सूची को अपडेट करने की ज़रूरत नहीं होती. जैसे, Play Radio.

दूसरी इमेज. कस्टम ब्राउज़ ऐक्शन टूलबार.

ब्राउज़ नोड रूट में, कस्टम ब्राउज़ ऐक्शन भी जोड़े जा सकते हैं. ये कार्रवाइयां, प्राइमरी टूलबार के नीचे मौजूद सेकंडरी टूलबार में दिखती हैं.

अपने ऐप्लिकेशन में कस्टम ब्राउज़ ऐक्शन जोड़ने के लिए:

1. MediaBrowserServiceCompat लागू करने के दौरान, इन दो तरीकों को बदलें:

   • onLoadItem(String itemId, @NonNull Result<MediaBrowserCompat.MediaItem> result)
   • onCustomAction(@NonNull String action, Bundle extras, @NonNull Result<Bundle> result)

2. रनटाइम पर कार्रवाई की सीमाओं को पार्स करें:

   onGetRoot में, rootHints Bundle में मौजूद BROWSER_ROOT_HINTS_KEY_CUSTOM_BROWSER_ACTION_LIMIT कुंजी का इस्तेमाल करके, हर MediaItem के लिए ज़्यादा से ज़्यादा कार्रवाइयां पाएं. सीमा के तौर पर 0 का मतलब है कि सिस्टम में यह सुविधा मौजूद नहीं है.

3. कस्टम ब्राउज़ ऐक्शन की ग्लोबल सूची बनाएं. हर कार्रवाई के लिए, इन कुंजियों के साथ एक Bundle ऑब्जेक्ट बनाएं:

   • कार्रवाई का आईडी EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ID
   • कार्रवाई का लेबल EXTRAS_KEY_CUSTOM_BROWSER_ACTION_LABEL
   • ऐक्शन आइकॉन यूआरआई EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ICON_URI

4. सभी ऐक्शन Bundle ऑब्जेक्ट को सूची में जोड़ें.

5. अपनी BrowseRoot में ग्लोबल लिस्ट जोड़ें. BrowseRoot extras Bundle में, कार्रवाइयों की सूची को Parcelable ArrayList के तौर पर जोड़ें. इसके लिए, BROWSER_SERVICE_EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ROOT_LIST कुंजी का इस्तेमाल करें.

6. अपने MediaItem ऑब्जेक्ट में कार्रवाइयां जोड़ें. DESCRIPTION_EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ID_LIST कुंजी का इस्तेमाल करके, MediaDescriptionCompat एक्स्ट्रा में कार्रवाई आईडी की सूची शामिल करके, अलग-अलग MediaItem ऑब्जेक्ट में कार्रवाइयां जोड़ी जा सकती हैं. यह सूची, BrowseRoot में तय की गई कार्रवाइयों की ग्लोबल सूची का सबसेट होनी चाहिए.

7. कार्रवाइयों को मैनेज करना और प्रोग्रेस या नतीजे दिखाना:

   • onCustomAction में, कार्रवाई के आईडी और ज़रूरत के हिसाब से किसी अन्य डेटा के आधार पर कार्रवाई करें. EXTRAS_KEY_CUSTOM_BROWSER_ACTION_MEDIA_ITEM_ID कुंजी का इस्तेमाल करके, कार्रवाई को ट्रिगर करने वाले MediaItem का आईडी, एक्स्ट्रा से पाया जा सकता है.

   • प्रोग्रेस या नतीजे के बंडल में EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM कुंजी शामिल करके, MediaItem के लिए कार्रवाइयों की सूची अपडेट की जा सकती है.

कार्रवाई की स्थिति अपडेट करना

MediaBrowserServiceCompat में इन तरीकों को बदलने के लिए:

public void onLoadItem(String itemId, @NonNull Result<MediaBrowserCompat.MediaItem> result)

और

public void onCustomAction(@NonNull String action, Bundle extras, @NonNull Result<Bundle> result)

कार्रवाइयों को पार्स करने की सीमा

देखें कि कितनी कस्टम ब्राउज़ कार्रवाइयां काम करती हैं:

public BrowserRoot onGetRoot(@NonNull String clientPackageName, int clientUid, Bundle rootHints) {
    rootHints.getInt(
            MediaConstants.BROWSER_ROOT_HINTS_KEY_CUSTOM_BROWSER_ACTION_LIMIT, 0)
}

ब्राउज़ करने की कस्टम कार्रवाई बनाना

हर कार्रवाई को अलग-अलग Bundle में पैक किया जाना चाहिए.

• कार्रवाई का आईडी:

  bundle.putString(MediaConstants.EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ID,
                  "<ACTION_ID>")
  

• कार्रवाई का लेबल:

  bundle.putString(MediaConstants.EXTRAS_KEY_CUSTOM_BROWSER_ACTION_LABEL,
                  "<ACTION_LABEL>")
  

• ऐक्शन आइकॉन यूआरआई:

  bundle.putString(MediaConstants.EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ICON_URI,
                  "<ACTION_ICON_URI>")
  

Parcelable ArrayList में कस्टम ब्राउज़ कार्रवाइयां जोड़ना

सभी कस्टम ब्राउज़ ऐक्शन Bundle ऑब्जेक्ट को ArrayList में जोड़ें:

private ArrayList<Bundle> createCustomActionsList(
                                        CustomBrowseAction browseActions) {
    ArrayList<Bundle> browseActionsBundle = new ArrayList<>();
    for (CustomBrowseAction browseAction : browseActions) {
        Bundle action = new Bundle();
        action.putString(EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ID,
                browseAction.mId);
        action.putString(EXTRAS_KEY_CUSTOM_BROWSER_ACTION_LABEL,
                getString(browseAction.mLabelResId));
        action.putString(EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ICON_URI,
                browseAction.mIcon);
        browseActionsBundle.add(action);
    }
    return browseActionsBundle;
}

ब्राउज़ रूट में ब्राउज़ करने की कस्टम कार्रवाई की सूची जोड़ें

public BrowserRoot onGetRoot(@NonNull String clientPackageName, int clientUid,
                             Bundle rootHints) {
    Bundle browserRootExtras = new Bundle();
    browserRootExtras.putParcelableArrayList(
            BROWSER_SERVICE_EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ROOT_LIST,
            createCustomActionsList()));
    mRoot = new BrowserRoot(ROOT_ID, browserRootExtras);
    return mRoot;
}

MediaItem में कार्रवाइयां जोड़ना

MediaItem में मौजूद 'ब्राउज़ करें' कार्रवाइयों के आईडी, onGetRoot पर दी गई 'ब्राउज़ करें' कार्रवाइयों की ग्लोबल सूची का सबसेट होना चाहिए. ग्लोबल सूची में शामिल नहीं की गई कार्रवाइयों को अनदेखा कर दिया जाता है.

MediaDescriptionCompat buildDescription (long id, String title, String subtitle,
                String description, Uri iconUri, Uri mediaUri,
                ArrayList<String> browseActionIds) {

    MediaDescriptionCompat.Builder bob = new MediaDescriptionCompat.Builder();
    bob.setMediaId(id);
    bob.setTitle(title);
    bob.setSubtitle(subtitle);
    bob.setDescription(description);
    bob.setIconUri(iconUri);
    bob.setMediaUri(mediaUri);

    Bundle extras = new Bundle();
    extras.putStringArrayList(
          DESCRIPTION_EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ID_LIST,
          browseActionIds);

    bob.setExtras(extras);
    return bob.build();
}
MediaItem mediaItem = new MediaItem(buildDescription(...), flags);

onCustomAction का नतीजा बनाएं

नतीजा बनाने के लिए:

1. Bundle extras से mediaId पार्स करना

   @Override
   public void onCustomAction(
               @NonNull String action, Bundle extras, @NonNull Result<Bundle> result){
       String mediaId = extras.getString(MediaConstans.EXTRAS_KEY_CUSTOM_BROWSER_ACTION_MEDIA_ITEM_ID);
               }
   

2. एसिंक्रोनस नतीजों के लिए, नतीजे को अलग करें result.detach.

3. नतीजों का बंडल बनाएं:

   1. उपयोगकर्ता को मैसेज दिखाएं:

      mResultBundle.putString(EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_MESSAGE,
                    mContext.getString(stringRes))
      

   2. आइटम अपडेट करें (इसका इस्तेमाल किसी आइटम में कार्रवाइयां अपडेट करने के लिए किया जाता है):

      mResultBundle.putString(EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM, mediaId);
      

   3. प्लेबैक व्यू खोलें:

      //Shows user the PBV without changing the playback state
      mResultBundle.putString(EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_SHOW_PLAYING_ITEM, null);
      

   4. ब्राउज़ नोड अपडेट करना:

      //Change current browse node to mediaId
      mResultBundle.putString(EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_BROWSE_NODE, mediaId);
      

4. नतीजा देखें:

   • गड़बड़ी: कॉल result.sendError(resultBundle)
   • प्रोग्रेस अपडेट: कॉल result.sendProgressUpdate(resultBundle)
   • पूरा करें: result.sendResult(resultBundle) को कॉल करें

कार्रवाई की स्थिति अपडेट करना

EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM कुंजी के साथ result.sendProgressUpdate(resultBundle) तरीके का इस्तेमाल करके, कार्रवाई की नई स्थिति दिखाने के लिए MediaItem को अपडेट किया जा सकता है. इससे उपयोगकर्ता को, उसकी कार्रवाई की प्रोग्रेस और नतीजे के बारे में रीयल-टाइम में जानकारी दी जा सकती है.

डाउनलोड करने की कार्रवाई का सैंपल

इस उदाहरण में बताया गया है कि इस सुविधा का इस्तेमाल करके, डाउनलोड करने की कार्रवाई को तीन स्थितियों में कैसे लागू किया जा सकता है:

• डाउनलोड करें, कार्रवाई की शुरुआती स्थिति होती है. जब उपयोगकर्ता यह कार्रवाई चुनता है, तो इसे डाउनलोड करने की कार्रवाई से बदला जा सकता है. साथ ही, यूज़र इंटरफ़ेस (यूआई) को अपडेट करने के लिए sendProgressUpdate को कॉल किया जा सकता है.

• डाउनलोड हो रहा है स्थिति से पता चलता है कि डाउनलोड हो रहा है. इस स्थिति का इस्तेमाल करके, उपयोगकर्ता को प्रोग्रेस बार या कोई दूसरा इंडिकेटर दिखाया जा सकता है.

• डाउनलोड हो गया स्थिति से पता चलता है कि डाउनलोड पूरा हो गया है. डाउनलोड पूरा होने के बाद, डाउनलोड किए जा रहे आइटम को डाउनलोड किए गए आइटम से बदला जा सकता है. साथ ही, sendResult को EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM कुंजी के साथ कॉल करके यह बताया जा सकता है कि आइटम को रीफ़्रेश किया जाना चाहिए. इसके अलावा, उपयोगकर्ता को पुष्टि हो जाने का मैसेज दिखाने के लिए, EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_MESSAGE कुंजी का इस्तेमाल किया जा सकता है.

इस तरीके से, उपयोगकर्ता को डाउनलोड करने की प्रोसेस और उसकी मौजूदा स्थिति के बारे में साफ़ तौर पर जानकारी दी जा सकती है. आइकॉन की मदद से ज़्यादा जानकारी जोड़ी जा सकती है. इससे 25%, 50%, और 75% डाउनलोड की स्थिति दिखाई जा सकती है.

पसंदीदा कार्रवाई का सैंपल

एक और उदाहरण, दो स्थितियों वाली पसंदीदा कार्रवाई का है:

• पसंदीदा विकल्प उन आइटम के लिए दिखता है जो उपयोगकर्ता की पसंदीदा सूची में नहीं हैं. जब उपयोगकर्ता इस कार्रवाई को चुनता है, तो इसे पसंदीदा के साथ स्वैप करें. साथ ही, यूज़र इंटरफ़ेस (यूआई) को अपडेट करने के लिए, EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM कुंजी के साथ sendResult को कॉल करें.

• उपयोगकर्ता की पसंदीदा सूची में मौजूद आइटम के लिए, पसंदीदा के तौर पर मार्क किया गया दिखता है. जब उपयोगकर्ता इस ऐक्शन को चुनता है, तो इसे पसंदीदा के साथ स्वैप करें. इसके बाद, यूज़र इंटरफ़ेस (यूआई) को अपडेट करने के लिए, EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM कुंजी के साथ sendResult को कॉल करें.

इस तरीके से, उपयोगकर्ताओं को अपने पसंदीदा आइटम मैनेज करने का एक आसान और एक जैसा तरीका मिलता है. इन उदाहरणों में, ब्राउज़ करने की कस्टम कार्रवाइयों की सुविधा के बारे में बताया गया है. साथ ही, यह भी बताया गया है कि कार के मीडिया ऐप्लिकेशन में, बेहतर उपयोगकर्ता अनुभव के लिए इनका इस्तेमाल करके अलग-अलग फ़ंक्शन कैसे लागू किए जा सकते हैं. साथ ही, रीयल-टाइम में सुझाव भी पाए जा सकते हैं.

TestMediaApp प्रोजेक्ट में, इस सुविधा को लागू करने का पूरा उदाहरण देखा जा सकता है.