কাস্টম ব্রাউজ কর্ম বাস্তবায়ন

প্লেব্যাক ভিউতে স্বতন্ত্র ক্ষমতা প্রদানের জন্য আপনি যেভাবে কাস্টম প্লেব্যাক অ্যাকশন ব্যবহার করেন, ঠিক একইভাবে ব্রাউজিং ভিউতে স্বতন্ত্র ক্ষমতা প্রদানের জন্য কাস্টম ব্রাউজ অ্যাকশন ব্যবহার করতে পারেন। উদাহরণস্বরূপ, আপনি কাস্টম ব্রাউজ অ্যাকশন ব্যবহার করতে পারেন যাতে ব্যবহারকারীরা প্লেলিস্ট ডাউনলোড করতে বা কোনো কিউ-তে একটি আইটেম যোগ করতে পারে।

মূল সরঞ্জাম প্রস্তুতকারক (OEM) দ্বারা প্রদর্শিত অ্যাকশনের চেয়ে বেশি কাস্টম অ্যাকশন থাকলে, ব্যবহারকারীকে একটি ওভারফ্লো মেনু দেখানো হয়। প্রতিটি কাস্টম ব্রাউজ অ্যাকশন একটি দিয়ে সংজ্ঞায়িত করা হয়:

• অ্যাকশন আইডি: অনন্য স্ট্রিং শনাক্তকারী
• অ্যাকশন লেবেল: ব্যবহারকারীকে প্রদর্শিত লেখা।
• অ্যাকশন আইকন ইউনিফর্ম রিসোর্স আইডেন্টিফায়ার (URI): ভেক্টর ড্রয়েবল যা রঙ করা যায়

চিত্র ১. কাস্টম ব্রাউজ অ্যাকশন ওভারফ্লো।

আপনি আপনার 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 জন্য অনুমোদিত সর্বাধিক সংখ্যক অ্যাকশন জানুন। লিমিট ০ হলে তা নির্দেশ করে যে ফিচারটি সিস্টেম দ্বারা সমর্থিত নয়।

3. কাস্টম ব্রাউজ অ্যাকশনগুলির গ্লোবাল তালিকা তৈরি করুন। প্রতিটি অ্যাকশনের জন্য, এই কীগুলি সহ একটি Bundle অবজেক্ট তৈরি করুন:

   • অ্যাকশন আইডি EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ID
   • অ্যাকশন লেবেল EXTRAS_KEY_CUSTOM_BROWSER_ACTION_LABEL
   • অ্যাকশন আইকন URI EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ICON_URI

4. সমস্ত অ্যাকশন Bundle অবজেক্ট একটি তালিকায় যুক্ত করুন।

5. আপনার BrowseRoot এ গ্লোবাল তালিকাটি যোগ করুন। BrowseRoot extras Bundle এর মধ্যে, BROWSER_SERVICE_EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ROOT_LIST কী-টি ব্যবহার করে অ্যাকশনগুলির তালিকাটিকে একটি Parcelable ArrayList হিসেবে যোগ করুন।

6. আপনার MediaItem অবজেক্টগুলিতে অ্যাকশন যোগ করুন। আপনি DESCRIPTION_EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ID_LIST কী-টি ব্যবহার করে MediaDescriptionCompat এক্সট্রা-তে অ্যাকশন আইডিগুলির তালিকা অন্তর্ভুক্ত করার মাধ্যমে স্বতন্ত্র MediaItem অবজেক্টগুলিতে অ্যাকশন যোগ করতে পারেন। এই তালিকাটি অবশ্যই BrowseRoot এ আপনার সংজ্ঞায়িত অ্যাকশনগুলির গ্লোবাল তালিকার একটি উপসেট হতে হবে।

7. কার্যক্রম পরিচালনা করুন এবং অগ্রগতি বা ফলাফল ফেরত দিন:

   • onCustomAction এ, অ্যাকশন আইডি এবং আপনার প্রয়োজনীয় অন্যান্য ডেটার উপর ভিত্তি করে অ্যাকশনটি পরিচালনা করুন। আপনি EXTRAS_KEY_CUSTOM_BROWSER_ACTION_MEDIA_ITEM_ID কী-টি ব্যবহার করে এক্সট্রাস থেকে যে MediaItem অ্যাকশনটি ট্রিগার করেছে তার আইডি পেতে পারেন।

   • আপনি progress বা result বান্ডেলে 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 এর Browse Actions ID-গুলিকে অবশ্যই onGetRoot এ প্রদত্ত Browse Actions-এর গ্লোবাল তালিকার একটি উপসেট হতে হবে। যে অ্যাকশনগুলি গ্লোবাল তালিকায় নেই, সেগুলি উপেক্ষা করা হয়।

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);

কাস্টম অ্যাকশন ফলাফল তৈরি করুন

ফলাফল তৈরি করতে:

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 আপডেট করতে পারেন। এর মাধ্যমে আপনি ব্যবহারকারীকে তার কাজের অগ্রগতি এবং ফলাফল সম্পর্কে রিয়েল-টাইম ফিডব্যাক দিতে পারেন।

নমুনা ডাউনলোড অ্যাকশন

এই উদাহরণে বর্ণনা করা হয়েছে, কীভাবে আপনি এই ফিচারটি ব্যবহার করে তিনটি অবস্থা সহ একটি ডাউনলোড অ্যাকশন বাস্তবায়ন করতে পারেন:

• ডাউনলোড হলো অ্যাকশনটির প্রাথমিক অবস্থা। যখন ব্যবহারকারী এই অ্যাকশনটি নির্বাচন করেন, তখন আপনি এটিকে ডাউনলোডিং-এর সাথে অদলবদল করতে পারেন এবং ইউজার ইন্টারফেস (UI) আপডেট করার জন্য sendProgressUpdate কল করতে পারেন।

• ডাউনলোডিং অবস্থা নির্দেশ করে যে ডাউনলোড চলছে। আপনি এই অবস্থাটি ব্যবহার করে ব্যবহারকারীকে একটি অগ্রগতি বার বা অন্য কোনো নির্দেশক দেখাতে পারেন।

• ডাউনলোডেড অবস্থা নির্দেশ করে যে ডাউনলোড সম্পন্ন হয়েছে। ডাউনলোড শেষ হলে, আপনি ডাউনলোডিং-এর পরিবর্তে ডাউনলোডেড ব্যবহার করতে পারেন এবং আইটেমটি রিফ্রেশ করার জন্য EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM কী-সহ sendResult কল করতে পারেন। এছাড়াও, ব্যবহারকারীকে একটি সফলতার বার্তা দেখানোর জন্য আপনি EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_MESSAGE কী ব্যবহার করতে পারেন।

এই পদ্ধতিটি আপনাকে ডাউনলোড প্রক্রিয়া এবং এর বর্তমান অবস্থা সম্পর্কে ব্যবহারকারীকে স্পষ্ট ধারণা দিতে সাহায্য করে। আপনি ২৫%, ৫০% এবং ৭৫% ডাউনলোড অবস্থা দেখানোর জন্য আইকন ব্যবহার করে আরও বিস্তারিত তথ্য যোগ করতে পারেন।

নমুনা প্রিয় কাজ

এর আরেকটি উদাহরণ হলো দুটি অবস্থা সহ একটি পছন্দের কাজ:

• যেসব আইটেম ব্যবহারকারীর পছন্দের তালিকায় নেই, সেগুলোর জন্য 'Favorite' প্রদর্শিত হয়। যখন ব্যবহারকারী এই অ্যাকশনটি নির্বাচন করেন, তখন এটিকে 'Favorated'-এর সাথে অদলবদল করুন এবং UI আপডেট করার জন্য EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM কী-সহ sendResult কল করুন।

• ব্যবহারকারীর পছন্দের তালিকায় থাকা আইটেমগুলোর জন্য 'পছন্দের' (Favorited) বিকল্পটি প্রদর্শিত হয়। যখন ব্যবহারকারী এই অ্যাকশনটি নির্বাচন করেন, তখন এটিকে 'পছন্দ' (Favorite) এর সাথে অদলবদল করুন এবং UI আপডেট করার জন্য EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM কী-টি সহ sendResult কল করুন।

এই পদ্ধতিটি ব্যবহারকারীদের তাদের পছন্দের আইটেমগুলো পরিচালনা করার জন্য একটি সুস্পষ্ট এবং সামঞ্জস্যপূর্ণ উপায় প্রদান করে। এই উদাহরণগুলো কাস্টম ব্রাউজ অ্যাকশনের নমনীয়তা এবং গাড়ির মিডিয়া অ্যাপে ব্যবহারকারীর অভিজ্ঞতা উন্নত করার জন্য রিয়েল-টাইম ফিডব্যাকসহ বিভিন্ন কার্যকারিতা বাস্তবায়নে এগুলোর ব্যবহার পদ্ধতি তুলে ধরে।

এই ফিচারটির একটি বিশদ নমুনা বাস্তবায়ন আপনি TestMediaApp প্রজেক্টে দেখতে পারেন।