कार के लिए मीडिया ऐप्लिकेशन बनाएं

Android Auto और Android Automotive OS की मदद से, अपने मीडिया ऐप्लिकेशन का कॉन्टेंट, कार में इस्तेमाल करने वालों तक पहुंचाया जा सकता है. कारों के लिए बने मीडिया ऐप्लिकेशन में मीडिया ब्राउज़र की सेवा उपलब्ध होनी चाहिए, ताकि Android Auto और Android Automotive OS या मीडिया ब्राउज़र वाला कोई अन्य ऐप्लिकेशन आपका कॉन्टेंट ढूंढ सके और उसे दिखा सके.

इस गाइड में यह माना गया है कि आपके पास पहले से ही ऐसा मीडिया ऐप्लिकेशन है जो फ़ोन पर ऑडियो चलाता है और आपका मीडिया ऐप्लिकेशन, Android मीडिया ऐप्लिकेशन आर्किटेक्चर के मुताबिक है.

इस गाइड में, MediaBrowserService और MediaSession के उन ज़रूरी कॉम्पोनेंट के बारे में बताया गया है जिनकी ज़रूरत आपके ऐप्लिकेशन को Android Auto या Android Automotive OS पर काम करने के लिए होती है. मीडिया के बुनियादी इंफ़्रास्ट्रक्चर को पूरा करने के बाद, अपने मीडिया ऐप्लिकेशन में Android Auto के लिए सहायता जोड़ी जा सकती है. साथ ही, Android Automotive OS के लिए सहायता जोड़ी जा सकती है.

शुरू करने से पहले

1. Android Media API का दस्तावेज़ पढ़ें.
2. डिज़ाइन से जुड़े दिशा-निर्देश पाने के लिए, मीडिया ऐप्लिकेशन बनाना देखें.
3. इस सेक्शन में दिए गए मुख्य शब्दों और कॉन्सेप्ट को देखें.

मुख्य शब्द और कॉन्सेप्ट

मीडिया ब्राउज़र सेवा

आपके मीडिया ऐप्लिकेशन की ओर से लागू की गई Android सेवा, जो MediaBrowserServiceCompat एपीआई के मुताबिक हो. आपका ऐप्लिकेशन, अपने कॉन्टेंट को दिखाने के लिए इस सेवा का इस्तेमाल करता है.

मीडिया ब्राउज़र

मीडिया ब्राउज़र सेवाओं को खोजने और उनका कॉन्टेंट दिखाने के लिए, मीडिया ऐप्लिकेशन इसका इस्तेमाल करते हैं. Android Auto और Android Automotive OS, मीडिया ब्राउज़र का इस्तेमाल करके आपके ऐप्लिकेशन की मीडिया ब्राउज़र सेवा ढूंढते हैं.

मीडिया आइटम

मीडिया ब्राउज़र, अपने कॉन्टेंट को MediaItem ऑब्जेक्ट के ट्री में व्यवस्थित करता है. किसी मीडिया आइटम में, इनमें से कोई एक या दोनों फ़्लैग हो सकते हैं:

• FLAG_PLAYABLE: इससे पता चलता है कि आइटम, कॉन्टेंट ट्री में लीफ है. यह आइटम, किसी एक साउंड स्ट्रीम को दिखाता है. जैसे, किसी एल्बम का गाना, ऑडियो बुक का चैप्टर या पॉडकास्ट का एपिसोड.
• FLAG_BROWSABLE: इससे पता चलता है कि आइटम, कॉन्टेंट ट्री का एक नोड है और उसमें चाइल्ड आइटम हैं. उदाहरण के लिए, आइटम किसी एल्बम को दिखाता है और उसके चाइल्ड एलिमेंट, एल्बम में मौजूद गाने होते हैं.

ऐसा मीडिया आइटम जिसे ब्राउज़ किया जा सकता है और चलाया जा सकता है, जो प्लेलिस्ट की तरह काम करता है. किसी आइटम के सभी चाइल्ड आइटम चलाने के लिए, उस आइटम को चुना जा सकता है या उसके चाइल्ड आइटम ब्राउज़ किए जा सकते हैं.

वाहन के लिए ऑप्टिमाइज़

Android Automotive OS ऐप्लिकेशन के लिए ऐसी गतिविधि जो Android Automotive OS के डिज़ाइन से जुड़े दिशा-निर्देशों का पालन करती हो. इन गतिविधियों के लिए इंटरफ़ेस, Android Automotive OS नहीं बनाता. इसलिए, आपको यह पक्का करना होगा कि आपका ऐप्लिकेशन डिज़ाइन से जुड़े दिशा-निर्देशों का पालन करता हो. आम तौर पर, इसमें टैप किए जाने वाले हिस्से और फ़ॉन्ट के साइज़ को बड़ा किया जाता है. साथ ही, दिन और रात मोड के साथ-साथ ज़्यादा कंट्रास्ट रेशियो की सुविधा भी दी जाती है.

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

आपको Android Auto के लिए गतिविधियां डिज़ाइन करने की ज़रूरत नहीं है, क्योंकि Android Auto आपकी मीडिया ब्राउज़र सेवा की जानकारी का इस्तेमाल करके, गाड़ी के हिसाब से ऑप्टिमाइज़ किया गया इंटरफ़ेस बनाता है.

अपने ऐप्लिकेशन की मेनिफ़ेस्ट फ़ाइलों को कॉन्फ़िगर करना

मीडिया ब्राउज़र सेवा बनाने से पहले, आपको अपने ऐप्लिकेशन की मेनिफ़ेस्ट फ़ाइलों को कॉन्फ़िगर करना होगा.

मीडिया ब्राउज़र सेवा का एलान करना

मीडिया आइटम ब्राउज़ करने के लिए, Android Auto और Android Automotive OS, दोनों आपकी मीडिया ब्राउज़र सेवा की मदद से आपके ऐप्लिकेशन से कनेक्ट होते हैं. अपने मेनिफ़ेस्ट में मीडिया ब्राउज़र सेवा का एलान करें, ताकि Android Auto और Android Automotive OS, सेवा को ढूंढ सकें और आपके ऐप्लिकेशन से कनेक्ट कर सकें.

यहां दिया गया कोड स्निपेट, मेनिफ़ेस्ट में मीडिया ब्राउज़र सेवा का एलान करने का तरीका दिखाता है. इस कोड को अपने Android Automotive OS मॉड्यूल की मेनिफ़ेस्ट फ़ाइल और अपने फ़ोन ऐप्लिकेशन की मेनिफ़ेस्ट फ़ाइल में शामिल करें.

<application>
    ...
    <service android:name=".MyMediaBrowserService"
             android:exported="true">
        <intent-filter>
            <action android:name="android.media.browse.MediaBrowserService"/>
        </intent-filter>
    </service>
    ...
</application>

ऐप्लिकेशन के आइकॉन के बारे में बताएं

आपको ऐप्लिकेशन के ऐसे आइकॉन तय करने होंगे जिनका इस्तेमाल Android Auto और Android Automotive OS, सिस्टम यूज़र इंटरफ़ेस में आपके ऐप्लिकेशन को दिखाने के लिए कर सकते हैं. दो तरह के आइकॉन ज़रूरी हैं:

• लॉन्चर आइकॉन
• एट्रिब्यूशन आइकॉन

लॉन्चर आइकॉन

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

<application
    ...
    android:icon="@mipmap/ic_launcher"
    ...
/>

अपने मोबाइल ऐप्लिकेशन के आइकॉन के बजाय कोई दूसरा आइकॉन इस्तेमाल करने के लिए, मेनिफ़ेस्ट में अपनी मीडिया ब्राउज़र सेवा के <service> एलिमेंट पर android:icon प्रॉपर्टी सेट करें:

<application>
    ...
    <service
        ...
        android:icon="@mipmap/auto_launcher"
        ...
    />
</application>

एट्रिब्यूशन का आइकॉन

पहली इमेज. मीडिया कार्ड पर एट्रिब्यूशन आइकॉन.

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

<application>
    ...
    <meta-data
        android:name="androidx.car.app.TintableAttributionIcon"
        android:resource="@drawable/ic_status_icon" />
    ...
</application>

अपनी मीडिया ब्राउज़र सेवा बनाएं

MediaBrowserServiceCompat क्लास को एक्सटेंड करके, मीडिया ब्राउज़र सेवा बनाई जाती है. इसके बाद, Android Auto और Android Automotive OS, दोनों आपकी सेवाओं का इस्तेमाल इन कामों के लिए कर सकते हैं:

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

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

मीडिया ब्राउज़र सेवा का वर्कफ़्लो

इस सेक्शन में बताया गया है कि किसी सामान्य उपयोगकर्ता वर्कफ़्लो के दौरान, Android Automotive OS और Android Auto, मीडिया ब्राउज़र की सेवा के साथ कैसे इंटरैक्ट करते हैं.

1. उपयोगकर्ता, Android Automotive OS या Android Auto पर आपका ऐप्लिकेशन लॉन्च करता है.
2. Android Automotive OS या Android Auto, onCreate() तरीके का इस्तेमाल करके, आपके ऐप्लिकेशन की मीडिया ब्राउज़र सेवा से संपर्क करता है. onCreate() तरीके को लागू करने के लिए, आपको एक MediaSessionCompat ऑब्जेक्ट और उसका कॉलबैक ऑब्जेक्ट बनाना और रजिस्टर करना होगा.
3. Android Automotive OS या Android Auto, कॉन्टेंट की हैरारकी में रूट मीडिया आइटम पाने के लिए, आपकी सेवा के onGetRoot() तरीके का इस्तेमाल करता है. रूट मीडिया आइटम नहीं दिखाया जाता. इसके बजाय, इसका इस्तेमाल आपके ऐप्लिकेशन से ज़्यादा कॉन्टेंट पाने के लिए किया जाता है.
4. Android Automotive OS या Android Auto, रूट मीडिया आइटम के चाइल्ड का पता लगाने के लिए, आपकी सेवा के onLoadChildren() तरीके का इस्तेमाल करता है. Android Automotive OS और Android Auto, इन मीडिया आइटम को कॉन्टेंट आइटम के टॉप लेवल के तौर पर दिखाते हैं. इस लेवल पर सिस्टम की क्या उम्मीद है, इस बारे में ज़्यादा जानकारी के लिए, इस पेज पर रूट मेन्यू को व्यवस्थित करना लेख पढ़ें.
5. अगर उपयोगकर्ता ब्राउज़ किए जा सकने वाले मीडिया आइटम को चुनता है, तो चुने गए मेन्यू आइटम के चाइल्ड आइटम को वापस पाने के लिए, आपकी सेवा के onLoadChildren() तरीके को फिर से कॉल किया जाता है.
6. अगर उपयोगकर्ता, चलाए जा सकने वाले मीडिया आइटम को चुनता है, तो Android Automotive OS या Android Auto, इस कार्रवाई को करने के लिए सही मीडिया सेशन कॉलबैक तरीके को कॉल करता है.
7. अगर आपके ऐप्लिकेशन में यह सुविधा काम करती है, तो उपयोगकर्ता आपका कॉन्टेंट भी खोज सकता है. इस मामले में, Android Automotive OS या Android Auto, आपकी सेवा के onSearch() तरीके को कॉल करता है.

अपने कॉन्टेंट की हैरारकी तैयार करना

उपलब्ध कॉन्टेंट का पता लगाने के लिए, Android Auto और Android Automotive OS आपके ऐप्लिकेशन की मीडिया ब्राउज़र सेवा को कॉल करते हैं. इसका इस्तेमाल करने के लिए, आपको अपनी मीडिया ब्राउज़र सेवा में दो तरीके लागू करने होंगे: onGetRoot() और onLoadChildren()

onGetRoot लागू करना

आपकी सेवा का onGetRoot() तरीका, कॉन्टेंट की हैरारकी के रूट नोड के बारे में जानकारी दिखाता है. Android Auto और Android Automotive OS, इस रूट नोड का इस्तेमाल करके, onLoadChildren() तरीके का इस्तेमाल करके आपके बाकी कॉन्टेंट का अनुरोध करते हैं.

नीचे दिए गए कोड स्निपेट में, onGetRoot() तरीके को आसानी से लागू करने का तरीका बताया गया है:

override fun onGetRoot(
    clientPackageName: String,
    clientUid: Int,
    rootHints: Bundle?
): BrowserRoot? =
    // Verify that the specified package is allowed to access your
    // content. You'll need to write your own logic to do this.
    if (!isValid(clientPackageName, clientUid)) {
        // If the request comes from an untrusted package, return null.
        // No further calls will be made to other media browsing methods.

        null
    } else MediaBrowserServiceCompat.BrowserRoot(MY_MEDIA_ROOT_ID, null)

@Override
public BrowserRoot onGetRoot(String clientPackageName, int clientUid,
    Bundle rootHints) {

    // Verify that the specified package is allowed to access your
    // content. You'll need to write your own logic to do this.
    if (!isValid(clientPackageName, clientUid)) {
        // If the request comes from an untrusted package, return null.
        // No further calls will be made to other media browsing methods.

        return null;
    }

    return new MediaBrowserServiceCompat.BrowserRoot(MY_MEDIA_ROOT_ID, null);
}

इस तरीके के बारे में ज़्यादा जानकारी के लिए, GitHub पर Universal Android Music Player सैंपल ऐप्लिकेशन में onGetRoot() तरीका देखें.

onGetRoot() के लिए पैकेज की पुष्टि करने की सुविधा जोड़ना

जब आपकी सेवा के onGetRoot() तरीके से कॉल किया जाता है, तो कॉल करने वाला पैकेज आपकी सेवा को पहचान से जुड़ी जानकारी भेजता है. आपकी सेवा इस जानकारी का इस्तेमाल यह तय करने के लिए कर सकती है कि वह पैकेज आपके कॉन्टेंट को ऐक्सेस कर सकता है या नहीं. उदाहरण के लिए, clientPackageName की तुलना अनुमति वाली सूची से करके और पैकेज के APK पर हस्ताक्षर करने के लिए इस्तेमाल किए गए सर्टिफ़िकेट की पुष्टि करके, अपने ऐप्लिकेशन के कॉन्टेंट को अनुमति वाले पैकेज की सूची तक सीमित किया जा सकता है. अगर पैकेज की पुष्टि नहीं की जा सकती, तो अपने कॉन्टेंट का ऐक्सेस अस्वीकार करने के लिए, null पर वापस जाएं.

Android Auto और Android Automotive OS जैसे सिस्टम ऐप्लिकेशन को आपके कॉन्टेंट का ऐक्सेस देने के लिए, जब ये सिस्टम ऐप्लिकेशन onGetRoot() विधि को कॉल करते हैं, तो आपकी सेवा को हमेशा कोई ऐसा BrowserRoot दिखाना चाहिए जो शून्य न हो. कार के मॉडल और मैन्युफ़ैक्चरर के हिसाब से, Android Automotive OS सिस्टम ऐप्लिकेशन का हस्ताक्षर अलग-अलग हो सकता है. इसलिए, Android Automotive OS के साथ बेहतर तरीके से काम करने के लिए, आपको सभी सिस्टम ऐप्लिकेशन से कनेक्ट करने की अनुमति देनी होगी.

यहां दिए गए कोड स्निपेट में बताया गया है कि आपकी सेवा, कॉलिंग पैकेज के सिस्टम ऐप्लिकेशन होने की पुष्टि कैसे कर सकती है:

fun isKnownCaller(
    callingPackage: String,
    callingUid: Int
): Boolean {
    ...
    val isCallerKnown = when {
       // If the system is making the call, allow it.
       callingUid == Process.SYSTEM_UID -> true
       // If the app was signed by the same certificate as the platform
       // itself, also allow it.
       callerSignature == platformSignature -> true
       // ... more cases
    }
    return isCallerKnown
}

यह कोड स्निपेट, GitHub पर मौजूद Universal Android Music Player के सैंपल ऐप्लिकेशन में मौजूद PackageValidator क्लास का एक हिस्सा है. अपनी सेवा के onGetRoot() तरीके के लिए, पैकेज की पुष्टि करने के तरीके को लागू करने के बारे में ज़्यादा जानकारी के लिए, वह क्लास देखें.

सिस्टम ऐप्लिकेशन को अनुमति देने के अलावा, आपको Google Assistant को अपने MediaBrowserService से कनेक्ट करने देना होगा. ध्यान दें कि Google Assistant में फ़ोन के लिए अलग-अलग पैकेज नाम होते हैं, जिसमें Android Auto और Android Automotive OS शामिल हैं.

onLoadChildren() लागू करना

आपका रूट नोड ऑब्जेक्ट मिलने के बाद, Android Auto और Android Automotive OS, रूट नोड ऑब्जेक्ट पर onLoadChildren() को कॉल करके, टॉप-लेवल मेन्यू बनाते हैं. इससे, रूट नोड ऑब्जेक्ट के चाइल्ड एलिमेंट मिलते हैं. क्लाइंट ऐप्लिकेशन, चाइल्ड नोड ऑब्जेक्ट का इस्तेमाल करके, इसी तरीके को कॉल करके सबमेन्यू बनाते हैं.

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

नीचे दिए गए कोड स्निपेट में, onLoadChildren() तरीके को आसानी से लागू करने का तरीका बताया गया है:

override fun onLoadChildren(
    parentMediaId: String,
    result: Result<List<MediaBrowserCompat.MediaItem>>
) {
    // Assume for example that the music catalog is already loaded/cached.

    val mediaItems: MutableList<MediaBrowserCompat.MediaItem> = mutableListOf()

    // Check whether this is the root menu:
    if (MY_MEDIA_ROOT_ID == parentMediaId) {

        // Build the MediaItem objects for the top level
        // and put them in the mediaItems list.
    } else {

        // Examine the passed parentMediaId to see which submenu we're at
        // and put the children of that menu in the mediaItems list.
    }
    result.sendResult(mediaItems)
}

@Override
public void onLoadChildren(final String parentMediaId,
    final Result<List<MediaBrowserCompat.MediaItem>> result) {

    // Assume for example that the music catalog is already loaded/cached.

    List<MediaBrowserCompat.MediaItem> mediaItems = new ArrayList<>();

    // Check whether this is the root menu:
    if (MY_MEDIA_ROOT_ID.equals(parentMediaId)) {

        // Build the MediaItem objects for the top level
        // and put them in the mediaItems list.
    } else {

        // Examine the passed parentMediaId to see which submenu we're at
        // and put the children of that menu in the mediaItems list.
    }
    result.sendResult(mediaItems);
}

इस तरीके के उदाहरण देखने के लिए, GitHub पर Universal Android Music Player सैंपल ऐप्लिकेशन में onLoadChildren() तरीका देखें.

रूट मेन्यू को व्यवस्थित करना

दूसरी इमेज. रूट कॉन्टेंट, नेविगेशन टैब के तौर पर दिखता है.

Android Auto और Android Automotive OS में, रूट मेन्यू के स्ट्रक्चर से जुड़ी कुछ खास पाबंदियां होती हैं. इन्हें रूट हिंट के ज़रिए MediaBrowserService को भेजा जाता है. इन्हें onGetRoot() में पास किए गए Bundle आर्ग्युमेंट के ज़रिए पढ़ा जा सकता है. इन संकेतों के बाद सिस्टम, रूट कॉन्टेंट को नेविगेशनल टैब के तौर पर बेहतर तरीके से दिखा पाता है. इन सुझावों का पालन न करने पर, हो सकता है कि सिस्टम कुछ रूट कॉन्टेंट को हटा दे या उसे खोजने में ज़्यादा मुश्किल बना दे. दो हिंट भेजे जाते हैं:

• रूट चाइल्ड की संख्या पर पाबंदी: ज़्यादातर मामलों में, यह संख्या चार हो सकती है. इसका मतलब है कि चार से ज़्यादा टैब नहीं दिखाए जा सकते.
• रूट चाइल्ड पर इस्तेमाल किए जा सकने वाले फ़्लैग: इसकी वैल्यू MediaItem#FLAG_BROWSABLE हो सकती है. इसका मतलब है कि टैब के तौर पर, सिर्फ़ ब्राउज़ किए जा सकने वाले आइटम दिखाए जा सकते हैं, न कि खेले जाने वाले आइटम.

काम के रूट हिंट पढ़ने के लिए, इस कोड का इस्तेमाल करें:

import androidx.media.utils.MediaConstants

// Later, in your MediaBrowserServiceCompat.
override fun onGetRoot(
    clientPackageName: String,
    clientUid: Int,
    rootHints: Bundle
): BrowserRoot {

  val maximumRootChildLimit = rootHints.getInt(
      MediaConstants.BROWSER_ROOT_HINTS_KEY_ROOT_CHILDREN_LIMIT,
      /* defaultValue= */ 4)
  val supportedRootChildFlags = rootHints.getInt(
      MediaConstants.BROWSER_ROOT_HINTS_KEY_ROOT_CHILDREN_SUPPORTED_FLAGS,
      /* defaultValue= */ MediaItem.FLAG_BROWSABLE)

  // Rest of method...
}

import androidx.media.utils.MediaConstants;

// Later, in your MediaBrowserServiceCompat.
@Override
public BrowserRoot onGetRoot(
    String clientPackageName, int clientUid, Bundle rootHints) {

    int maximumRootChildLimit = rootHints.getInt(
        MediaConstants.BROWSER_ROOT_HINTS_KEY_ROOT_CHILDREN_LIMIT,
        /* defaultValue= */ 4);
    int supportedRootChildFlags = rootHints.getInt(
        MediaConstants.BROWSER_ROOT_HINTS_KEY_ROOT_CHILDREN_SUPPORTED_FLAGS,
        /* defaultValue= */ MediaItem.FLAG_BROWSABLE);

    // Rest of method...
}

इन हिंट की वैल्यू के आधार पर, कॉन्टेंट के क्रम के स्ट्रक्चर के लिए लॉजिक को ब्रैंच किया जा सकता है. ऐसा तब ज़रूरी होता है, जब Android Auto और Android Automotive OS के बाहर के MediaBrowser इंटिग्रेशन के बीच आपकी हैरारकी अलग-अलग हो. उदाहरण के लिए, अगर आम तौर पर कोई चलाया जा सकने वाला रूट आइटम दिखाया जाता है, तो हो सकता है कि आप उसे ब्राउज़ किए जा सकने वाले रूट आइटम के नीचे नेस्ट करना चाहें. ऐसा, इस्तेमाल किए जा सकने वाले फ़्लैग के संकेत की वैल्यू की वजह से किया जा सकता है.

यह पक्का करने के लिए कि टैब सही तरीके से रेंडर हों, रूट संकेतों के अलावा, कुछ अतिरिक्त दिशा-निर्देश हैं जिनका पालन करना है:

• हर टैब आइटम के लिए मोनोक्रोम (बेहतर तौर पर सफ़ेद) आइकॉन उपलब्ध कराएं.
• हर टैब आइटम के लिए छोटे, लेकिन काम के लेबल दें. लेबल को छोटा रखने से, स्ट्रिंग में काट-छांट होने की संभावना कम हो जाती है.

मीडिया आर्टवर्क दिखाएं

मीडिया आइटम के आर्टवर्क को लोकल यूआरआई के तौर पर पास किया जाना चाहिए. इसके लिए, ContentResolver.SCHEME_CONTENT या ContentResolver.SCHEME_ANDROID_RESOURCE का इस्तेमाल करें. इस लोकल यूआरआई को ऐप्लिकेशन के संसाधनों में, बिटमैप या वेक्टर ड्रॉबल में बदलना चाहिए. कॉन्टेंट की हैरारकी में आइटम दिखाने वाले MediaDescriptionCompat ऑब्जेक्ट के लिए, यूआरआई को setIconUri() से पास करें. हाल ही में चल रहे आइटम को दिखाने वाले MediaMetadataCompat ऑब्जेक्ट के लिए, इनमें से किसी भी कुंजी का इस्तेमाल करके putString() के ज़रिए यूआरएल को पास करें:

• MediaMetadataCompat.METADATA_KEY_DISPLAY_ICON_URI
• MediaMetadataCompat.METADATA_KEY_ART_URI
• MediaMetadataCompat.METADATA_KEY_ALBUM_ART_URI

यहां बताया गया है कि वेब यूआरआई से आर्टवर्क को कैसे डाउनलोड करें और उसे लोकल यूआरआई के ज़रिए कैसे दिखाएं. ज़्यादा जानकारी के लिए, Universal Android Music Player के सैंपल ऐप्लिकेशन में, openFile() और उससे जुड़े तरीकों को लागू करने का उदाहरण देखें.

1. वेब यूआरआई से जुड़ा content:// यूआरआई बनाएं. मीडिया ब्राउज़र सेवा और मीडिया सेशन, इस कॉन्टेंट यूआरआई को Android Auto और Android Automotive OS को पास करते हैं.

   Kotlin

   fun Uri.asAlbumArtContentURI(): Uri {
     return Uri.Builder()
       .scheme(ContentResolver.SCHEME_CONTENT)
       .authority(CONTENT_PROVIDER_AUTHORITY)
       .appendPath(this.getPath()) // Make sure you trust the URI
       .build()
   }

   Java

   public static Uri asAlbumArtContentURI(Uri webUri) {
     return new Uri.Builder()
       .scheme(ContentResolver.SCHEME_CONTENT)
       .authority(CONTENT_PROVIDER_AUTHORITY)
       .appendPath(webUri.getPath()) // Make sure you trust the URI!
       .build();
   }

2. ContentProvider.openFile() को लागू करते समय, देखें कि उससे जुड़े यूआरआई के लिए कोई फ़ाइल मौजूद है या नहीं. अगर ऐसा नहीं है, तो इमेज फ़ाइल को डाउनलोड और कैश मेमोरी में सेव करें. यहां दिया गया कोड स्निपेट, Glide का इस्तेमाल करता है.

   Kotlin

   override fun openFile(uri: Uri, mode: String): ParcelFileDescriptor? {
     val context = this.context ?: return null
     val file = File(context.cacheDir, uri.path)
     if (!file.exists()) {
       val remoteUri = Uri.Builder()
           .scheme("https")
           .authority("my-image-site")
           .appendPath(uri.path)
           .build()
       val cacheFile = Glide.with(context)
           .asFile()
           .load(remoteUri)
           .submit()
           .get(DOWNLOAD_TIMEOUT_SECONDS, TimeUnit.SECONDS)
   
       cacheFile.renameTo(file)
       file = cacheFile
     }
     return ParcelFileDescriptor.open(file, ParcelFileDescriptor.MODE_READ_ONLY)
   }

   Java

   @Nullable
   @Override
   public ParcelFileDescriptor openFile(@NonNull Uri uri, @NonNull String mode)
       throws FileNotFoundException {
     Context context = this.getContext();
     File file = new File(context.getCacheDir(), uri.getPath());
     if (!file.exists()) {
       Uri remoteUri = new Uri.Builder()
           .scheme("https")
           .authority("my-image-site")
           .appendPath(uri.getPath())
           .build();
       File cacheFile = Glide.with(context)
           .asFile()
           .load(remoteUri)
           .submit()
           .get(DOWNLOAD_TIMEOUT_SECONDS, TimeUnit.SECONDS);
   
       cacheFile.renameTo(file);
       file = cacheFile;
     }
     return ParcelFileDescriptor.open(file, ParcelFileDescriptor.MODE_READ_ONLY);
   }

कॉन्टेंट उपलब्ध कराने वाली कंपनियों के बारे में ज़्यादा जानने के लिए, कॉन्टेंट उपलब्ध कराने वाली कंपनी बनाना लेख पढ़ें.

कॉन्टेंट स्टाइल लागू करना

ब्राउज़ किए जा सकने वाले या चलाए जा सकने वाले आइटम के हिसाब से कॉन्टेंट की हैरारकी बनाने के बाद, कॉन्टेंट की स्टाइल लागू की जा सकती हैं. इससे यह तय किया जा सकता है कि कार में वे आइटम किस तरह दिखेंगे.

इन कॉन्टेंट स्टाइल का इस्तेमाल किया जा सकता है:

आइटम की सूची

इस कॉन्टेंट स्टाइल में, इमेज के बजाय टाइटल और मेटाडेटा को प्राथमिकता दी जाती है.

ग्रिड आइटम

इस कॉन्टेंट स्टाइल में, टाइटल और मेटाडेटा के बजाय इमेज को प्राथमिकता दी जाती है.

कॉन्टेंट के लिए डिफ़ॉल्ट स्टाइल सेट करना

आपके पास मीडिया आइटम को दिखाने के तरीके के लिए, ग्लोबल डिफ़ॉल्ट सेटिंग सेट करने का विकल्प है. इसके लिए, अपनी सेवा के onGetRoot() तरीके के BrowserRoot अतिरिक्त बंडल में कुछ कॉन्सटेंट शामिल करें. Android Auto और Android Automotive OS, इस बंडल को पढ़ते हैं और सही स्टाइल तय करने के लिए उन कॉन्स्टेंट को खोजते हैं.

बंडल में, इन एक्सट्रा का इस्तेमाल कुंजियों के तौर पर किया जा सकता है:

• DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE: ब्राउज़ ट्री में मौजूद उन सभी आइटम के लिए प्रज़ेंटेशन के सुझाव दिखाता है जिन्हें ब्राउज़ किया जा सकता है.
• DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_PLAYABLE: ब्राउज़ ट्री में मौजूद, चलाए जा सकने वाले सभी आइटम के लिए प्रज़ेंटेशन का संकेत दिखाता है.

उन आइटम के प्रज़ेंटेशन को प्रभावित करने के लिए, कुंजियां नीचे दिए गए पूर्णांक कॉन्सटेंट वैल्यू को मैप कर सकती हैं:

• DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_LIST_ITEM: इस स्थिति में, संबंधित आइटम सूची के आइटम के तौर पर दिखाए जाते हैं.
• DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_GRID_ITEM: इस विकल्प को चुनने पर, संबंधित आइटम ग्रिड आइटम के तौर पर दिखाए जाते हैं.
• DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_CATEGORY_LIST_ITEM: इसके लिए, संबंधित आइटम "कैटगरी" की सूची के आइटम के तौर पर दिखाए जाते हैं. ये सूची के सामान्य आइटम की तरह ही होते हैं. हालांकि, इन आइटम के आइकॉन के चारों ओर मार्जिन लागू होते हैं, क्योंकि छोटे आइकॉन बेहतर दिखते हैं. आइकॉन, रंग में बदले जा सकने वाले वेक्टर ड्रॉबल होने चाहिए. यह संकेत, सिर्फ़ उन आइटम के लिए दिया जाएगा जिन्हें ब्राउज़ किया जा सकता है.
• DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_CATEGORY_GRID_ITEM: इसके हिसाब से, आइटम "कैटगरी" ग्रिड आइटम के तौर पर दिखाए जाते हैं. ये सामान्य ग्रिड आइटम की तरह होते हैं. हालांकि, आइटम के आइकॉन के आस-पास मार्जिन लगाए जाते हैं, क्योंकि आइकॉन छोटे होने पर बेहतर दिखते हैं. आइकॉन, रंग में बदले जा सकने वाले वेक्टर ड्रॉबल होने चाहिए. यह संकेत, सिर्फ़ उन आइटम के लिए दिया जाएगा जिन्हें ब्राउज़ किया जा सकता है.

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

import androidx.media.utils.MediaConstants

@Nullable
override fun onGetRoot(
    @NonNull clientPackageName: String,
    clientUid: Int,
    @Nullable rootHints: Bundle
): BrowserRoot {
    val extras = Bundle()
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_GRID_ITEM)
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_PLAYABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_LIST_ITEM)
    return BrowserRoot(ROOT_ID, extras)
}

import androidx.media.utils.MediaConstants;

@Nullable
@Override
public BrowserRoot onGetRoot(
    @NonNull String clientPackageName,
    int clientUid,
    @Nullable Bundle rootHints) {
    Bundle extras = new Bundle();
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_GRID_ITEM);
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_PLAYABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_LIST_ITEM);
    return new BrowserRoot(ROOT_ID, extras);
}

हर आइटम के लिए कॉन्टेंट स्टाइल सेट करना

Content Style API की मदद से, ब्राउज़ किए जा सकने वाले किसी भी मीडिया आइटम के चाइल्ड आइटम के साथ-साथ, किसी भी मीडिया आइटम के लिए डिफ़ॉल्ट कॉन्टेंट स्टाइल को बदला जा सकता है.

ब्राउज़ किए जा सकने वाले मीडिया आइटम के बच्चे के डिफ़ॉल्ट ट्रैक को बदलने के लिए, मीडिया आइटम के MediaDescription में एक अतिरिक्त बंडल बनाएं और पहले बताए गए उन ही संकेतों को जोड़ें. DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_PLAYABLE, उस आइटम के उन बच्चों पर लागू होता है जिन्हें चलाया जा सकता है. वहीं, DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE उस आइटम के उन बच्चों पर लागू होता है जिन्हें ब्राउज़ किया जा सकता है.

किसी मीडिया आइटम के लिए डिफ़ॉल्ट वैल्यू को बदलने के लिए, उसके चाइल्ड आइटम के बजाय, मीडिया आइटम के MediaDescription में एक्सट्रा बंडल बनाएं. साथ ही, उसमें DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_SINGLE_ITEM कीवर्ड के साथ एक हिंट जोड़ें. उस आइटम के प्रज़ेंटेशन को तय करने के लिए, ऊपर बताई गई उन्हीं वैल्यू का इस्तेमाल करें.

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

import androidx.media.utils.MediaConstants

private fun createBrowsableMediaItem(
    mediaId: String,
    folderName: String,
    iconUri: Uri
): MediaBrowser.MediaItem {
    val mediaDescriptionBuilder = MediaDescription.Builder()
    mediaDescriptionBuilder.setMediaId(mediaId)
    mediaDescriptionBuilder.setTitle(folderName)
    mediaDescriptionBuilder.setIconUri(iconUri)
    val extras = Bundle()
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_SINGLE_ITEM,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_CATEGORY_LIST_ITEM)
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_LIST_ITEM)
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_PLAYABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_GRID_ITEM)
    mediaDescriptionBuilder.setExtras(extras)
    return MediaBrowser.MediaItem(
        mediaDescriptionBuilder.build(), MediaBrowser.MediaItem.FLAG_BROWSABLE)
}

import androidx.media.utils.MediaConstants;

private MediaBrowser.MediaItem createBrowsableMediaItem(
    String mediaId,
    String folderName,
    Uri iconUri) {
    MediaDescription.Builder mediaDescriptionBuilder = new MediaDescription.Builder();
    mediaDescriptionBuilder.setMediaId(mediaId);
    mediaDescriptionBuilder.setTitle(folderName);
    mediaDescriptionBuilder.setIconUri(iconUri);
    Bundle extras = new Bundle();
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_SINGLE_ITEM,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_CATEGORY_LIST_ITEM);
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_LIST_ITEM);
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_PLAYABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_GRID_ITEM);
    mediaDescriptionBuilder.setExtras(extras);
    return new MediaBrowser.MediaItem(
        mediaDescriptionBuilder.build(), MediaBrowser.MediaItem.FLAG_BROWSABLE);
}

टाइटल के सुझावों का इस्तेमाल करके आइटम ग्रुप करना

मिलते-जुलते मीडिया आइटम को एक साथ ग्रुप करने के लिए, हर आइटम के लिए दिए गए हिंट का इस्तेमाल किया जाता है. किसी ग्रुप में मौजूद हर मीडिया आइटम को अपने MediaDescription में एक एक्सट्रा बंडल का एलान करना होगा. इसमें, एक जैसी स्ट्रिंग वैल्यू और बटन के DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE के साथ मैपिंग शामिल होनी चाहिए. इस स्ट्रिंग को स्थानीय भाषा में अनुवाद करें. इसका इस्तेमाल, ग्रुप के टाइटल के तौर पर किया जाता है.

नीचे दिया गया कोड स्निपेट, "Songs" के सबग्रुप हेडर के साथ MediaItem बनाने का तरीका बताता है:

import androidx.media.utils.MediaConstants

private fun createMediaItem(
    mediaId: String,
    folderName: String,
    iconUri: Uri
): MediaBrowser.MediaItem {
    val mediaDescriptionBuilder = MediaDescription.Builder()
    mediaDescriptionBuilder.setMediaId(mediaId)
    mediaDescriptionBuilder.setTitle(folderName)
    mediaDescriptionBuilder.setIconUri(iconUri)
    val extras = Bundle()
    extras.putString(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE,
        "Songs")
    mediaDescriptionBuilder.setExtras(extras)
    return MediaBrowser.MediaItem(
        mediaDescriptionBuilder.build(), /* playable or browsable flag*/)
}

import androidx.media.utils.MediaConstants;

private MediaBrowser.MediaItem createMediaItem(String mediaId, String folderName, Uri iconUri) {
   MediaDescription.Builder mediaDescriptionBuilder = new MediaDescription.Builder();
   mediaDescriptionBuilder.setMediaId(mediaId);
   mediaDescriptionBuilder.setTitle(folderName);
   mediaDescriptionBuilder.setIconUri(iconUri);
   Bundle extras = new Bundle();
   extras.putString(
       MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE,
       "Songs");
   mediaDescriptionBuilder.setExtras(extras);
   return new MediaBrowser.MediaItem(
       mediaDescriptionBuilder.build(), /* playable or browsable flag*/);
}

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

1. extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs") के साथ मीडिया आइटम A
2. extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Albums") वाला मीडिया आइटम B
3. extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs") वाला मीडिया आइटम C
4. extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs") वाला मीडिया आइटम D
5. extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Albums") वाला मीडिया आइटम E

"गाने" ग्रुप और "एल्बम" ग्रुप के मीडिया आइटम को एक साथ एक ही ब्लॉक में नहीं रखा जाता. इसलिए, Android Auto और Android Automotive OS इन चार ग्रुप के तौर पर इसका इस्तेमाल करते हैं:

• "गाने" नाम का पहला ग्रुप, जिसमें मीडिया आइटम A शामिल है
• दूसरा ग्रुप "एल्बम" है, जिसमें मीडिया आइटम B शामिल है
• ग्रुप 3 के "गाने" हैं, जिसमें मीडिया आइटम C और D हैं
• समूह 4 में मीडिया आइटम E वाला "एल्बम" है

इन आइटम को दो ग्रुप में दिखाने के लिए, आपके ऐप्लिकेशन को मीडिया आइटम को इस क्रम में पास करना होगा:

1. extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs") के साथ मीडिया आइटम A
2. extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs") के साथ मीडिया आइटम C
3. extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs") वाला मीडिया आइटम D
4. extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Albums") वाला मीडिया आइटम B
5. extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Albums") के साथ मीडिया आइटम E

अतिरिक्त मेटाडेटा इंडिकेटर दिखाएं

मीडिया ब्राउज़र ट्री और वीडियो चलाने के दौरान, कॉन्टेंट के बारे में एक नज़र में जानकारी देने के लिए, मेटाडेटा के अन्य इंडिकेटर शामिल किए जा सकते हैं. ब्राउज़ ट्री में, Android Auto और Android Automotive OS किसी आइटम से जुड़े अतिरिक्त एलिमेंट को पढ़ते हैं. साथ ही, यह तय करने के लिए कुछ कॉन्स्टेंट खोजते हैं कि कौनसे इंडिकेटर दिखाने हैं. मीडिया प्लेबैक के दौरान, Android Auto और Android Automotive OS, मीडिया सेशन का मेटाडेटा पढ़ते हैं. साथ ही, डिसप्ले किए जाने वाले इंडिकेटर को तय करने के लिए, कुछ खास तरह के स्थिरांक का भी पता लगाते हैं.

तीसरी इमेज. गाने और कलाकार की पहचान करने वाले मेटाडेटा के साथ-साथ, अश्लील कॉन्टेंट की जानकारी देने वाले आइकॉन वाला, वीडियो चलाने का व्यू.

चौथी इमेज. ब्राउज़ व्यू में, पहले आइटम पर न देखे गए कॉन्टेंट के लिए बिंदु और दूसरे आइटम पर कुछ हद तक देखे गए कॉन्टेंट के लिए प्रोग्रेस बार.

इन कॉन्सटेंट का इस्तेमाल MediaItem ब्यौरे वाली अतिरिक्त चीज़ों और MediaMetadata अतिरिक्त चीज़ों, दोनों में किया जा सकता है:

• EXTRA_DOWNLOAD_STATUS: यह किसी आइटम के डाउनलोड स्टेटस के बारे में बताता है. इस कॉन्स्टेंट का इस्तेमाल, कुंजी के तौर पर करें. ये लॉन्ग कॉन्स्टेंट, संभावित वैल्यू हैं:
  • STATUS_DOWNLOADED: आइटम पूरी तरह से डाउनलोड हो गया है.
  • STATUS_DOWNLOADING: आइटम डाउनलोड किया जा रहा है.
  • STATUS_NOT_DOWNLOADED: आइटम डाउनलोड नहीं किया गया है.
• METADATA_KEY_IS_EXPLICIT: बताता है कि क्या आइटम में अश्लील कॉन्टेंट है. किसी आइटम के अश्लील होने का पता लगाने के लिए, इस कॉन्स्टेंट को बतौर कुंजी और लंबी METADATA_VALUE_ATTRIBUTE_PRESENT को वैल्यू के तौर पर इस्तेमाल करें.

नीचे दी गई स्थिर वैल्यू का इस्तेमाल, MediaItem ब्यौरे के अतिरिक्त एलिमेंट में सिर्फ़ किया जा सकता है:

• DESCRIPTION_EXTRAS_KEY_COMPLETION_STATUS: इससे पता चलता है कि लंबी अवधि के कॉन्टेंट को पूरा किया गया है या नहीं. जैसे, पॉडकास्ट के एपिसोड या ऑडियो बुक. इस कॉन्स्टेंट का इस्तेमाल कुंजी के तौर पर करें. यहां दिए गए पूर्णांक कॉन्स्टेंट, संभावित वैल्यू हैं:
  • DESCRIPTION_EXTRAS_VALUE_COMPLETION_STATUS_NOT_PLAYED: आइटम को बिलकुल नहीं चलाया गया है.
  • DESCRIPTION_EXTRAS_VALUE_COMPLETION_STATUS_PARTIALLY_PLAYED: आइटम का कुछ हिस्सा चलाया गया है और मौजूदा पोज़िशन बीच में है.
  • DESCRIPTION_EXTRAS_VALUE_COMPLETION_STATUS_FULLY_PLAYED: आइटम पूरा हो गया है.
• DESCRIPTION_EXTRAS_KEY_COMPLETION_PERCENTAGE: इससे पता चलता है कि लंबी अवधि के वीडियो को कितने प्रतिशत तक देखा गया है. यह वैल्यू 0.0 से 1.0 के बीच होती है. इस अतिरिक्त एट्रिब्यूट से, PARTIALLY_PLAYING की स्थिति के बारे में ज़्यादा जानकारी मिलती है. इससे Android Auto या Android Automotive OS, प्रोग्रेस बार जैसे ज़्यादा काम के प्रोग्रेस इंडिकेटर दिखा पाता है. अगर इस एक्सट्रा का इस्तेमाल किया जाता है, तो इस गाइड में कॉन्टेंट चलने के दौरान, ब्राउज़ व्यू में प्रोग्रेस बार को अपडेट करने सेक्शन देखें. इससे, शुरुआती इंप्रेशन के बाद इस इंडिकेटर को अप-टू-डेट रखने का तरीका जानने में मदद मिलेगी.

जब उपयोगकर्ता मीडिया ब्राउज़ ट्री को ब्राउज़ कर रहा हो, तब दिखने वाले इंडिकेटर दिखाने के लिए, एक या उससे ज़्यादा कॉन्स्टेंट वाला एक एक्स्ट्रा बंडल बनाएं और उस बंडल को MediaDescription.Builder.setExtras() तरीके में पास करें.

यहां दिए गए कोड स्निपेट में, अश्लील कॉन्टेंट वाले ऐसे मीडिया आइटम के लिए इंडिकेटर दिखाने का तरीका बताया गया है जो 70% पूरा हो चुका है:

import androidx.media.utils.MediaConstants

val extras = Bundle()
extras.putLong(
    MediaConstants.METADATA_KEY_IS_EXPLICIT,
    MediaConstants.METADATA_VALUE_ATTRIBUTE_PRESENT)
extras.putInt(
    MediaConstants.DESCRIPTION_EXTRAS_KEY_COMPLETION_STATUS,
    MediaConstants.DESCRIPTION_EXTRAS_VALUE_COMPLETION_STATUS_PARTIALLY_PLAYED)
extras.putDouble(
    MediaConstants.DESCRIPTION_EXTRAS_KEY_COMPLETION_PERCENTAGE, 0.7)
val description =
    MediaDescriptionCompat.Builder()
        .setMediaId(/*...*/)
        .setTitle(resources.getString(/*...*/))
        .setExtras(extras)
        .build()
return MediaBrowserCompat.MediaItem(description, /* flags */)

import androidx.media.utils.MediaConstants;

Bundle extras = new Bundle();
extras.putLong(
    MediaConstants.METADATA_KEY_IS_EXPLICIT,
    MediaConstants.METADATA_VALUE_ATTRIBUTE_PRESENT);
extras.putInt(
    MediaConstants.DESCRIPTION_EXTRAS_KEY_COMPLETION_STATUS,
    MediaConstants.DESCRIPTION_EXTRAS_VALUE_COMPLETION_STATUS_PARTIALLY_PLAYED);
extras.putDouble(
    MediaConstants.DESCRIPTION_EXTRAS_KEY_COMPLETION_PERCENTAGE, 0.7);
MediaDescriptionCompat description =
    new MediaDescriptionCompat.Builder()
        .setMediaId(/*...*/)
        .setTitle(resources.getString(/*...*/))
        .setExtras(extras)
        .build();
return new MediaBrowserCompat.MediaItem(description, /* flags */);

फ़िलहाल चल रहे मीडिया आइटम के लिए इंडिकेटर दिखाने के लिए, अपने mediaSession के MediaMetadataCompat में METADATA_KEY_IS_EXPLICIT या EXTRA_DOWNLOAD_STATUS के लिए Long वैल्यू सबमिट की जा सकती हैं. वीडियो चलाने के दौरान दिखने वाले व्यू पर, DESCRIPTION_EXTRAS_KEY_COMPLETION_STATUS या DESCRIPTION_EXTRAS_KEY_COMPLETION_PERCENTAGE इंडिकेटर नहीं दिखाए जा सकते.

यहां दिए गए कोड स्निपेट में यह दिखाया गया है कि वीडियो चलाने के सेक्शन में मौजूद मौजूदा गाना अश्लील है और उसे डाउनलोड किया गया है, इसकी जानकारी कैसे दें:

import androidx.media.utils.MediaConstants

mediaSession.setMetadata(
    MediaMetadataCompat.Builder()
        .putString(
            MediaMetadataCompat.METADATA_KEY_DISPLAY_TITLE, "Song Name")
        .putString(
            MediaMetadataCompat.METADATA_KEY_DISPLAY_SUBTITLE, "Artist name")
        .putString(
            MediaMetadataCompat.METADATA_KEY_ALBUM_ART_URI,
            albumArtUri.toString())
        .putLong(
            MediaConstants.METADATA_KEY_IS_EXPLICIT,
            MediaConstants.METADATA_VALUE_ATTRIBUTE_PRESENT)
        .putLong(
            MediaDescriptionCompat.EXTRA_DOWNLOAD_STATUS,
            MediaDescriptionCompat.STATUS_DOWNLOADED)
        .build())

import androidx.media.utils.MediaConstants;

mediaSession.setMetadata(
    new MediaMetadataCompat.Builder()
        .putString(
            MediaMetadataCompat.METADATA_KEY_DISPLAY_TITLE, "Song Name")
        .putString(
            MediaMetadataCompat.METADATA_KEY_DISPLAY_SUBTITLE, "Artist name")
        .putString(
            MediaMetadataCompat.METADATA_KEY_ALBUM_ART_URI,
            albumArtUri.toString())
        .putLong(
            MediaConstants.METADATA_KEY_IS_EXPLICIT,
            MediaConstants.METADATA_VALUE_ATTRIBUTE_PRESENT)
        .putLong(
            MediaDescriptionCompat.EXTRA_DOWNLOAD_STATUS,
            MediaDescriptionCompat.STATUS_DOWNLOADED)
        .build());

वीडियो चलने के दौरान, ब्राउज़ व्यू में प्रोग्रेस बार अपडेट करना

जैसा कि पहले बताया गया है, ब्राउज़ व्यू में, कुछ हद तक चलाए गए कॉन्टेंट के लिए प्रोग्रेस बार दिखाने के लिए, DESCRIPTION_EXTRAS_KEY_COMPLETION_PERCENTAGE एक्सट्रा का इस्तेमाल किया जा सकता है. हालांकि, अगर कोई उपयोगकर्ता Android Auto या Android Automotive OS पर, आधा चलाया गया कॉन्टेंट चलाता रहता है, तो समय के साथ वह इंडिकेटर गलत हो जाता है.

Android Auto और Android Automotive OS के लिए, प्रोग्रेस बार को अप-टू-डेट रखने के लिए, MediaMetadataCompat और PlaybackStateCompat में ज़्यादा जानकारी दी जा सकती है. इससे, ब्राउज़ व्यू में मौजूद मीडिया आइटम से चल रहे कॉन्टेंट को लिंक किया जा सकता है. मीडिया आइटम के लिए, प्रोग्रेस बार अपने-आप अपडेट होने की सुविधा चालू करने के लिए, ये ज़रूरी शर्तें पूरी करनी होंगी:

• इसे बनाने के बाद, MediaItem को अपने एक्सट्रा में DESCRIPTION_EXTRAS_KEY_COMPLETION_PERCENTAGE भेजना होगा. इसकी वैल्यू 0.0 से 1.0 के बीच होनी चाहिए.
• MediaMetadataCompat को METADATA_KEY_MEDIA_ID, MediaItem को पास किए गए मीडिया आईडी के बराबर की स्ट्रिंग वैल्यू के साथ भेजना चाहिए.
• PlaybackStateCompat में, PLAYBACK_STATE_EXTRAS_KEY_MEDIA_ID कीवर्ड के साथ एक एक्सट्रा एलिमेंट होना चाहिए. यह एलिमेंट, MediaItem में पास की गई मीडिया आईडी की वैल्यू के बराबर की स्ट्रिंग वैल्यू पर मैप करता है.

नीचे दिया गया कोड स्निपेट यह बताने का तरीका बताता है कि अभी चल रहा आइटम, ब्राउज़ व्यू में किसी आइटम से लिंक है या नहीं:

import androidx.media.utils.MediaConstants

// When the MediaItem is constructed to show in the browse view.
// Suppose the item was 25% complete when the user launched the browse view.
val mediaItemExtras = Bundle()
mediaItemExtras.putDouble(
    MediaConstants.DESCRIPTION_EXTRAS_KEY_COMPLETION_PERCENTAGE, 0.25)
val description =
    MediaDescriptionCompat.Builder()
        .setMediaId("my-media-id")
        .setExtras(mediaItemExtras)
        // ...and any other setters.
        .build()
return MediaBrowserCompat.MediaItem(description, /* flags */)

// Elsewhere, when the user has selected MediaItem for playback.
mediaSession.setMetadata(
    MediaMetadataCompat.Builder()
        .putString(MediaMetadata.METADATA_KEY_MEDIA_ID, "my-media-id")
        // ...and any other setters.
        .build())

val playbackStateExtras = Bundle()
playbackStateExtras.putString(
    MediaConstants.PLAYBACK_STATE_EXTRAS_KEY_MEDIA_ID, "my-media-id")
mediaSession.setPlaybackState(
    PlaybackStateCompat.Builder()
        .setExtras(playbackStateExtras)
        // ...and any other setters.
        .build())

import androidx.media.utils.MediaConstants;

// When the MediaItem is constructed to show in the browse view.
// Suppose the item was 25% complete when the user launched the browse view.
Bundle mediaItemExtras = new Bundle();
mediaItemExtras.putDouble(
    MediaConstants.DESCRIPTION_EXTRAS_KEY_COMPLETION_PERCENTAGE, 0.25);
MediaDescriptionCompat description =
    new MediaDescriptionCompat.Builder()
        .setMediaId("my-media-id")
        .setExtras(mediaItemExtras)
        // ...and any other setters.
        .build();
return MediaBrowserCompat.MediaItem(description, /* flags */);

// Elsewhere, when the user has selected MediaItem for playback.
mediaSession.setMetadata(
    new MediaMetadataCompat.Builder()
        .putString(MediaMetadata.METADATA_KEY_MEDIA_ID, "my-media-id")
        // ...and any other setters.
        .build());

Bundle playbackStateExtras = new Bundle();
playbackStateExtras.putString(
    MediaConstants.PLAYBACK_STATE_EXTRAS_KEY_MEDIA_ID, "my-media-id");
mediaSession.setPlaybackState(
    new PlaybackStateCompat.Builder()
        .setExtras(playbackStateExtras)
        // ...and any other setters.
        .build());

ब्राउज़ किए जा सकने वाले खोज के नतीजे दिखाना

पांचवी इमेज. उपयोगकर्ता की वॉइस सर्च से जुड़े मीडिया आइटम देखने के लिए, “खोज के नतीजे” विकल्प वाला प्लेलिस्ट व्यू.

आपका ऐप्लिकेशन, संदर्भ के हिसाब से खोज के नतीजे दिखा सकता है. ये नतीजे, उपयोगकर्ताओं को खोज क्वेरी डालने पर दिखते हैं. Android Auto और Android Automotive OS, खोज क्वेरी इंटरफ़ेस या ऐसे फ़ंक्शन के ज़रिए ये नतीजे दिखाते हैं जो सेशन में पहले की गई क्वेरी पर आधारित होते हैं. ज़्यादा जानने के लिए, इस गाइड में बोलकर निर्देश देने की सुविधा के लिए सहायता सेक्शन देखें.

ब्राउज़ किए जा सकने वाले खोज नतीजे दिखाने के लिए, अपनी सेवा के onGetRoot() तरीके के एक्स्ट्रा बंडल में, बोलियन true पर मैप करते हुए, कॉन्स्टेंट बटन BROWSER_SERVICE_EXTRAS_KEY_SEARCH_SUPPORTED को शामिल करें.

नीचे दिए गए कोड स्निपेट में, onGetRoot() तरीके में सहायता चालू करने का तरीका बताया गया है:

import androidx.media.utils.MediaConstants

@Nullable
fun onGetRoot(
    @NonNull clientPackageName: String,
    clientUid: Int,
    @Nullable rootHints: Bundle
): BrowserRoot {
    val extras = Bundle()
    extras.putBoolean(
        MediaConstants.BROWSER_SERVICE_EXTRAS_KEY_SEARCH_SUPPORTED, true)
    return BrowserRoot(ROOT_ID, extras)
}

import androidx.media.utils.MediaConstants;

@Nullable
@Override
public BrowserRoot onGetRoot(
    @NonNull String clientPackageName,
    int clientUid,
    @Nullable Bundle rootHints) {
    Bundle extras = new Bundle();
    extras.putBoolean(
        MediaConstants.BROWSER_SERVICE_EXTRAS_KEY_SEARCH_SUPPORTED, true);
    return new BrowserRoot(ROOT_ID, extras);
}

खोज के नतीजे दिखाने की सुविधा शुरू करने के लिए, अपनी मीडिया ब्राउज़र सेवा में onSearch() का तरीका बदलें. जब भी कोई उपयोगकर्ता खोज क्वेरी इंटरफ़ेस या “खोज के नतीजे” सुविधा को चालू करता है, तो Android Auto और Android Automotive OS, उपयोगकर्ता के खोज के लिए इस्तेमाल हुए शब्दों को इस तरीके पर भेजते हैं.

अपनी सेवा के onSearch() तरीके से खोज के नतीजों को व्यवस्थित किया जा सकता है. इसके लिए, टाइटल आइटम का इस्तेमाल करके, उन्हें ज़्यादा ब्राउज़ किया जा सकता है. उदाहरण के लिए, अगर आपका ऐप्लिकेशन संगीत चलाता है, तो खोज के नतीजों को एल्बम, कलाकार, और गानों के हिसाब से व्यवस्थित किया जा सकता है.

नीचे दिया गया कोड स्निपेट, onSearch() तरीके को आसानी से लागू करने का तरीका दिखाता है:

fun onSearch(query: String, extras: Bundle) {
  // Detach from results to unblock the caller (if a search is expensive).
  result.detach()
  object:AsyncTask() {
    internal var searchResponse:ArrayList
    internal var succeeded = false
    protected fun doInBackground(vararg params:Void):Void {
      searchResponse = ArrayList()
      if (doSearch(query, extras, searchResponse))
      {
        succeeded = true
      }
      return null
    }
    protected fun onPostExecute(param:Void) {
      if (succeeded)
      {
        // Sending an empty List informs the caller that there were no results.
        result.sendResult(searchResponse)
      }
      else
      {
        // This invokes onError() on the search callback.
        result.sendResult(null)
      }
      return null
    }
  }.execute()
}
// Populates resultsToFill with search results. Returns true on success or false on error.
private fun doSearch(
    query: String,
    extras: Bundle,
    resultsToFill: ArrayList
): Boolean {
  // Implement this method.
}

@Override
public void onSearch(final String query, final Bundle extras,
                        Result<List<MediaItem>> result) {

  // Detach from results to unblock the caller (if a search is expensive).
  result.detach();

  new AsyncTask<Void, Void, Void>() {
    List<MediaItem> searchResponse;
    boolean succeeded = false;
    @Override
    protected Void doInBackground(Void... params) {
      searchResponse = new ArrayList<MediaItem>();
      if (doSearch(query, extras, searchResponse)) {
        succeeded = true;
      }
      return null;
    }

    @Override
    protected void onPostExecute(Void param) {
      if (succeeded) {
       // Sending an empty List informs the caller that there were no results.
       result.sendResult(searchResponse);
      } else {
        // This invokes onError() on the search callback.
        result.sendResult(null);
      }
    }
  }.execute()
}

/** Populates resultsToFill with search results. Returns true on success or false on error. */
private boolean doSearch(String query, Bundle extras, ArrayList<MediaItem> resultsToFill) {
    // Implement this method.
}

कस्टम ब्राउज़ ऐक्शन

छठी इमेज. पसंद के मुताबिक ब्राउज़ करने की एक कार्रवाई

पसंद के मुताबिक ब्राउज़ करने की कार्रवाइयों की मदद से, कार के मीडिया ऐप्लिकेशन में अपने ऐप्लिकेशन के MediaItem ऑब्जेक्ट में पसंद के मुताबिक आइकॉन और लेबल जोड़े जा सकते हैं. साथ ही, इन कार्रवाइयों के साथ उपयोगकर्ता के इंटरैक्शन को मैनेज किया जा सकता है. इसकी मदद से, मीडिया ऐप्लिकेशन की सुविधाओं को कई तरीकों से बढ़ाया जा सकता है. जैसे, "डाउनलोड करें", "सूची में जोड़ें", "रेडियो चलाएँ", "पसंदीदा" या "हटाएं" कार्रवाइयां.

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

अगर OEM की अनुमति से ज़्यादा कस्टम कार्रवाइयां हैं, तो उपयोगकर्ता को एक 'ओवरफ़्लो मेन्यू' दिखेगा.

ये कैसे काम करते हैं?

पसंद के मुताबिक ब्राउज़ करने की हर कार्रवाई इसके साथ परिभाषित की गई है:

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

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

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

आठवीं इमेज. पसंद के मुताबिक ब्राउज़ करने की कार्रवाई का टूलबार

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

कस्टम ब्राउज़ ऐक्शन लागू करने का तरीका

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

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: कार्रवाई के आइकॉन का यूआरआई * सभी कार्रवाई Bundle ऑब्जेक्ट को एक सूची में जोड़ें.
4. ग्लोबल सूची को अपने BrowseRoot में जोड़ें:
   • BrowseRoot अतिरिक्त Bundle में, BROWSER_SERVICE_EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ROOT_LIST कुंजी का इस्तेमाल करके Parcelable Arraylist के तौर पर कार्रवाइयों की सूची जोड़ें.
5. अपने MediaItem ऑब्जेक्ट में कार्रवाइयां जोड़ें:
   • MediaItem ऑब्जेक्ट में कार्रवाइयां जोड़ी जा सकती हैं. इसके लिए, DESCRIPTION_EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ID_LIST बटन का इस्तेमाल करके, MediaDescriptionCompat एक्सट्रा में ऐक्शन आईडी की सूची शामिल करें. यह सूची, BrowseRoot में तय की गई कार्रवाइयों की ग्लोबल सूची का सबसेट होनी चाहिए.
6. कार्रवाइयों को मैनेज करें और प्रोग्रेस या नतीजे दिखाएं:
   • onCustomAction में, कार्रवाई आईडी और ज़रूरी अन्य डेटा के आधार पर कार्रवाई को मैनेज करें. EXTRAS_KEY_CUSTOM_BROWSER_ACTION_MEDIA_ITEM_ID कुंजी का इस्तेमाल करके, एक्सट्रा से उस MediaItem का आईडी पाया जा सकता है जिसने ऐक्शन को ट्रिगर किया है.
   • प्रोग्रेस या नतीजे के बंडल में EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM बटन को शामिल करके, MediaItem के लिए कार्रवाइयों की सूची अपडेट की जा सकती है.

कस्टम ब्राउज़ ऐक्शन का इस्तेमाल शुरू करने के लिए, BrowserServiceCompat में ये बदलाव किए जा सकते हैं.

BrowserServiceCompat को बदलना

आपको 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>")

Parceable 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 में कार्रवाइयां जोड़ना

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 का नतीजा बनाएं

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

• एसिंक्रोनस नतीजों के लिए, नतीजे को अलग करें. result.detach()
• नतीजे का बंडल बनाना
  • उपयोगकर्ता को मैसेज

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

  • आइटम अपडेट करें(किसी आइटम में ऐक्शन अपडेट करने के लिए इस्तेमाल करें)

    mResultBundle.putString(EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM, mediaId);

  • प्लेबैक व्यू खोलना

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

  • ब्राउज़ नोड अपडेट करना

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

• अगर कोई गड़बड़ी हुई है, तो result.sendError(resultBundle). पर कॉल करें
• अगर प्रोग्रेस अपडेट है, तो result.sendProgressUpdate(resultBundle) को कॉल करें.
• अपनी पहचान की पुष्टि, result.sendResult(resultBundle) पर कॉल करके करें.

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

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

उदाहरण: डाउनलोड ऐक्शन

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

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

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

उदाहरण: पसंदीदा ऐक्शन

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

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

इस तरीके से, उपयोगकर्ताओं को अपने पसंदीदा आइटम मैनेज करने का एक साफ़ और आसान तरीका मिलता है.

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

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

प्लेबैक कंट्रोल चालू करना

Android Auto और Android Automotive OS, आपकी सेवा के MediaSessionCompat के ज़रिए, वीडियो चलाने या रोकने के निर्देश भेजते हैं. आपको एक सेशन रजिस्टर करना होगा और उससे जुड़े कॉलबैक के तरीके लागू करने होंगे.

मीडिया सेशन रजिस्टर करना

मीडिया ब्राउज़र सेवा के onCreate() तरीके में, MediaSessionCompat बनाएं. इसके बाद, setSessionToken() को कॉल करके मीडिया सेशन रजिस्टर करें.

यहां दिए गए कोड स्निपेट में, मीडिया सेशन बनाने और उसे रजिस्टर करने का तरीका बताया गया है:

override fun onCreate() {
    super.onCreate()
    ...
    // Start a new MediaSession.
    val session = MediaSessionCompat(this, "session tag").apply {
        // Set a callback object that implements MediaSession.Callback
        // to handle play control requests.
        setCallback(MyMediaSessionCallback())
    }
    sessionToken = session.sessionToken
    ...
}

public void onCreate() {
    super.onCreate();
    ...
    // Start a new MediaSession.
    MediaSessionCompat session = new MediaSessionCompat(this, "session tag");
    setSessionToken(session.getSessionToken());

    // Set a callback object that implements MediaSession.Callback
    // to handle play control requests.
    session.setCallback(new MyMediaSessionCallback());
    ...
}

मीडिया सेशन ऑब्जेक्ट बनाते समय, एक कॉलबैक ऑब्जेक्ट सेट किया जाता है. इसका इस्तेमाल, प्लेबैक कंट्रोल के अनुरोधों को मैनेज करने के लिए किया जाता है. इस कॉलबैक ऑब्जेक्ट को बनाने के लिए, अपने ऐप्लिकेशन के लिए MediaSessionCompat.Callback क्लास को लागू करें. अगले सेक्शन में, इस ऑब्जेक्ट को लागू करने का तरीका बताया गया है.

वीडियो चलाने के निर्देश लागू करना

जब कोई उपयोगकर्ता आपके ऐप्लिकेशन से किसी मीडिया आइटम को चलाने का अनुरोध करता है, तो Android Automotive OS और Android Auto, आपके ऐप्लिकेशन के MediaSessionCompat ऑब्जेक्ट से मिले MediaSessionCompat.Callback क्लास का इस्तेमाल करते हैं. यह ऑब्जेक्ट, आपके ऐप्लिकेशन की मीडिया ब्राउज़र सेवा से मिला होता है. जब कोई उपयोगकर्ता कॉन्टेंट प्लेबैक को कंट्रोल करना चाहता है, जैसे कि प्लेबैक को रोकना या अगले ट्रैक पर जाना तो Android Auto और Android Automotive OS, कॉलबैक ऑब्जेक्ट के किसी एक तरीके को शुरू करते हैं.

कॉन्टेंट को चलाने के लिए, आपके ऐप्लिकेशन को ऐब्स्ट्रैक्ट MediaSessionCompat.Callback क्लास को बढ़ाना होगा और उन तरीकों को लागू करना होगा जो आपके ऐप्लिकेशन पर काम करते हैं.

यहां दिए गए सभी कॉलबैक तरीके लागू करें, जो आपके ऐप्लिकेशन में मौजूद कॉन्टेंट के हिसाब से सही हों:

onPrepare()

मीडिया सोर्स बदलने पर ट्रिगर होता है. Android Automotive OS भी बूट करने के तुरंत बाद इस तरीके को शुरू कर देता है. आपके मीडिया ऐप्लिकेशन को यह तरीका लागू करना होगा.

onPlay()

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

ध्यान दें: Android Automotive OS या Android Auto को मीडिया ब्राउज़र सेवा से कनेक्ट करने पर, आपके ऐप्लिकेशन में संगीत अपने-आप चलना शुरू नहीं होना चाहिए. ज़्यादा जानकारी के लिए, वीडियो चलाने की शुरुआती स्थिति सेट करने के बारे में बताने वाला सेक्शन देखें.

onPlayFromMediaId()

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

onPlayFromSearch()

जब उपयोगकर्ता किसी खोज क्वेरी से चलाने का विकल्प चुनता है, तब यह ट्रिगर होता है. ऐप्लिकेशन को पास की गई खोज स्ट्रिंग के हिसाब से सही विकल्प चुनना चाहिए.

onPause()

जब उपयोगकर्ता वीडियो चलाने को रोकता है, तब ट्रिगर होता है.

onSkipToNext()

जब उपयोगकर्ता अगले आइटम पर जाने का विकल्प चुनता है, तब यह ट्रिगर होता है.

onSkipToPrevious()

जब उपयोगकर्ता पिछले आइटम पर जाने का विकल्प चुनता है, तब ट्रिगर होता है.

onStop()

जब उपयोगकर्ता वीडियो चलाना बंद करता है, तब ट्रिगर होता है.

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

आपके ऐप्लिकेशन को कार के स्पीकर से कॉन्टेंट चलाने के लिए, किसी खास लॉजिक की ज़रूरत नहीं है. जब आपके ऐप्लिकेशन को कॉन्टेंट चलाने का अनुरोध मिलता है, तो वह ऑडियो को उसी तरह चला सकता है जिस तरह वह उपयोगकर्ता के फ़ोन के स्पीकर या हेडफ़ोन से कॉन्टेंट चलाता है. Android Auto और Android Automotive OS, ऑडियो कॉन्टेंट को कार के सिस्टम पर अपने-आप भेजते हैं, ताकि उसे कार के स्पीकर पर चलाया जा सके.

ऑडियो कॉन्टेंट चलाने के बारे में ज़्यादा जानने के लिए, MediaPlayer की खास जानकारी, ऑडियो ऐप्लिकेशन की खास जानकारी, और ExoPlayer की खास जानकारी देखें.

प्लेबैक से जुड़ी स्टैंडर्ड कार्रवाइयां सेट करना

Android Auto और Android Automotive OS, PlaybackStateCompat ऑब्जेक्ट में चालू की गई कार्रवाइयों के आधार पर, वीडियो चलाने के कंट्रोल दिखाते हैं.

डिफ़ॉल्ट रूप से, आपके ऐप्लिकेशन में ये कार्रवाइयां की जानी चाहिए:

• ACTION_PLAY
• ACTION_PAUSE
• ACTION_STOP
• ACTION_PLAY_FROM_MEDIA
• ACTION_PLAY_FROM_SEARCH

अगर ये कार्रवाइयां आपके ऐप्लिकेशन के कॉन्टेंट के हिसाब से सही हैं, तो आपके ऐप्लिकेशन में ये कार्रवाइयां भी की जा सकती हैं:

• ACTION_SKIP_TO_PREVIOUS
• ACTION_SKIP_TO_NEXT

इसके अलावा, आपके पास एक प्लेलिस्ट बनाने का विकल्प भी होता है. इसे उपयोगकर्ता को दिखाया जा सकता है, लेकिन ऐसा करना ज़रूरी नहीं है. ऐसा करने के लिए, setQueue() और setQueueTitle() तरीकों को कॉल करें. इसके बाद, ACTION_SKIP_TO_QUEUE_ITEM ऐक्शन को चालू करें और कॉलबैक onSkipToQueueItem() तय करें.

साथ ही, अभी चल रहा है आइकॉन की सुविधा भी जोड़ें. यह आइकॉन, फ़िलहाल चल रहे वीडियो के बारे में बताता है. ऐसा करने के लिए, setActiveQueueItemId() तरीका कॉल करें और सूची में मौजूद, फ़िलहाल चल रहे आइटम का आईडी पास करें. सूची में कोई बदलाव होने पर, आपको setActiveQueueItemId() को अपडेट करना होगा.

Android Auto और Android Automotive OS, चालू की गई हर कार्रवाई के लिए बटन के साथ-साथ, वीडियो चलाने की सूची भी दिखाते हैं. बटन पर क्लिक करने पर, सिस्टम MediaSessionCompat.Callback से उनके संबंधित कॉलबैक को शुरू करता है.

इस्तेमाल नहीं किए गए स्टोरेज को रिज़र्व करना

Android Auto और Android Automotive OS, यूज़र इंटरफ़ेस (यूआई) में ACTION_SKIP_TO_PREVIOUS और ACTION_SKIP_TO_NEXT कार्रवाइयों के लिए जगह रिज़र्व करते हैं. अगर आपका ऐप्लिकेशन इनमें से किसी एक फ़ंक्शन के साथ काम नहीं करता है, तो Android Auto और Android Automotive OS, आपके बनाए गए कस्टम ऐक्शन दिखाने के लिए उस जगह का इस्तेमाल करते हैं.

अगर आपको उन जगहों को कस्टम ऐक्शन से नहीं भरना है, तो उन्हें रिज़र्व किया जा सकता है. इससे, Android Auto और Android Automotive OS को तब खाली छोड़ा जा सकता है, जब भी आपके ऐप्लिकेशन में इससे जुड़ा फ़ंक्शन काम न करता हो. ऐसा करने के लिए, setExtras() के साथ एक अतिरिक्त बंडल का इस्तेमाल करके, उस तरीके को कॉल करें जिसमें रिज़र्व किए गए फ़ंक्शन से जुड़े कॉन्सटेंट शामिल हों. SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_NEXT, ACTION_SKIP_TO_NEXT से और SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_PREV, ACTION_SKIP_TO_PREVIOUS से मेल खाता है. बंडल में इन कॉन्सटेंट को कुंजियों के तौर पर इस्तेमाल करें. साथ ही, उनकी वैल्यू के लिए बूलियन true का इस्तेमाल करें.

शुरुआती PlaybackState सेट करना

Android Auto और Android Automotive OS, आपके मीडिया ब्राउज़र की सेवा के साथ काम करते हैं. इसलिए, आपका मीडिया सेशन PlaybackStateCompat का इस्तेमाल करके, कॉन्टेंट चलाने की स्थिति की जानकारी देता है. जब Android Automotive OS या Android Auto, आपकी मीडिया ब्राउज़र सेवा से कनेक्ट हो, तो आपका ऐप्लिकेशन अपने-आप संगीत नहीं चलाना चाहिए. इसके बजाय, कार की स्थिति या उपयोगकर्ता की कार्रवाइयों के आधार पर, वीडियो चलाने या फिर से चलाने के लिए, Android Auto और Android Automotive OS का इस्तेमाल करें.

ऐसा करने के लिए, अपने मीडिया सेशन के शुरुआती PlaybackStateCompat को STATE_STOPPED, STATE_PAUSED, STATE_NONE या STATE_ERROR पर सेट करें.

Android Auto और Android Automotive OS में मीडिया सेशन, सिर्फ़ ड्राइव के दौरान चलते हैं. इसलिए, उपयोगकर्ता इन सेशन को बार-बार शुरू और बंद करते हैं. एक ड्राइव से दूसरी ड्राइव पर आसानी से जाने के लिए, उपयोगकर्ता के पिछले सेशन की स्थिति पर नज़र रखें. इससे, मीडिया ऐप्लिकेशन को फिर से शुरू करने का अनुरोध मिलने पर, उपयोगकर्ता अपने-आप उसी जगह से शुरू कर सकता है जहां से उसने आखिरी बार वीडियो चलाया था. उदाहरण के लिए, आखिरी बार चलाया गया मीडिया आइटम, PlaybackStateCompat, और सूची.

वीडियो चलाने के लिए कस्टम कार्रवाइयां जोड़ना

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

स्टैंडर्ड कार्रवाइयों से अलग व्यवहार देने के लिए, कस्टम कार्रवाइयों का इस्तेमाल करें. इनका इस्तेमाल, स्टैंडर्ड ऐक्शन को बदलने या डुप्लीकेट करने के लिए न करें.

PlaybackStateCompat.Builder क्लास में addCustomAction() तरीका इस्तेमाल करके, कस्टम ऐक्शन जोड़े जा सकते हैं.

नीचे दिए गए कोड स्निपेट में, “रेडियो चैनल चलाएं” कार्रवाई को कस्टमाइज़ करने का तरीका बताया गया है:

stateBuilder.addCustomAction(
    PlaybackStateCompat.CustomAction.Builder(
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA,
        resources.getString(R.string.start_radio_from_media),
        startRadioFromMediaIcon
    ).run {
        setExtras(customActionExtras)
        build()
    }
)

stateBuilder.addCustomAction(
    new PlaybackStateCompat.CustomAction.Builder(
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA,
        resources.getString(R.string.start_radio_from_media),
        startRadioFromMediaIcon)
    .setExtras(customActionExtras)
    .build());

इस तरीके के बारे में ज़्यादा जानकारी के लिए, GitHub पर Universal Android Music Player के सैंपल ऐप्लिकेशन में setCustomAction() तरीका देखें.

कस्टम ऐक्शन बनाने के बाद, आपका मीडिया सेशन onCustomAction() तरीके को बदलकर, ऐक्शन का जवाब दे सकता है.

नीचे दिए गए कोड स्निपेट से पता चलता है कि आपका ऐप्लिकेशन, “रेडियो चैनल चलाएं” ऐक्शन का जवाब कैसे दे सकता है:

override fun onCustomAction(action: String, extras: Bundle?) {
    when(action) {
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA -> {
            ...
        }
    }
}

@Override
public void onCustomAction(@NonNull String action, Bundle extras) {
    if (CUSTOM_ACTION_START_RADIO_FROM_MEDIA.equals(action)) {
        ...
    }
}

इस तरीके के बारे में ज़्यादा जानकारी के लिए, GitHub पर Universal Android Music Player के सैंपल ऐप्लिकेशन में onCustomAction तरीका देखें.

कस्टम ऐक्शन के लिए आइकॉन

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

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

बंद की गई कार्रवाइयों के लिए, आइकॉन के अन्य स्टाइल उपलब्ध कराना

जब मौजूदा संदर्भ के लिए कस्टम कार्रवाई उपलब्ध न हो, तो कस्टम कार्रवाई आइकॉन को किसी दूसरे आइकॉन से स्वैप करें जो दिखाता है कि कार्रवाई बंद है.

ऑडियो फ़ॉर्मैट की जानकारी देना

यह बताने के लिए कि फ़िलहाल चल रहा मीडिया किसी खास ऑडियो फ़ॉर्मैट का इस्तेमाल करता है, आपके पास ऐसे आइकॉन तय करने का विकल्प होता है जो इस सुविधा के साथ काम करने वाली कारों में रेंडर किए जाते हैं. फ़िलहाल चल रहे मीडिया आइटम के एक्सट्रा बंडल में, KEY_CONTENT_FORMAT_TINTABLE_LARGE_ICON_URI और KEY_CONTENT_FORMAT_TINTABLE_SMALL_ICON_URI को सेट किया जा सकता है. यह बंडल, MediaSession.setMetadata() को पास किया जाता है. अलग-अलग लेआउट के हिसाब से, दोनों एक्सट्रा को सेट करना न भूलें.

इसके अलावा, KEY_IMMERSIVE_AUDIO को अलग से सेट करके, कार के OEM को बताया जा सकता है कि यह इमर्सिव ऑडियो है. साथ ही, उन्हें इस बात का फ़ैसला बहुत सोच-समझकर करना चाहिए कि क्या आपको ऐसे ऑडियो इफ़ेक्ट इस्तेमाल करने हैं जो अन्य कॉन्टेंट में रुकावट डाल सकते हैं.

अभी चल रहे आइटम के लिंक जोड़ें

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

लिंक जोड़ने के लिए, KEY_SUBTITLE_LINK_MEDIA_ID मेटाडेटा (सबटाइटल से लिंक करने के लिए) या KEY_DESCRIPTION_LINK_MEDIA_ID (ब्यौरे से लिंक करने के लिए) को कॉन्फ़िगर करें. ज़्यादा जानकारी के लिए, उन मेटाडेटा फ़ील्ड से जुड़े रेफ़रंस दस्तावेज़ देखें.

बोलकर फ़ोन इस्तेमाल करने की सुविधा

आपका मीडिया ऐप्लिकेशन, बोलकर फ़ोन का तेज़ी से इस्तेमाल करने की सुविधा के साथ काम करना चाहिए. इससे ड्राइवरों को सुरक्षित और आसान अनुभव मिलता है. साथ ही, ड्राइविंग के दौरान उनका ध्यान भटकने से भी बचा रहता है. उदाहरण के लिए, अगर आपका ऐप्लिकेशन कोई मीडिया आइटम चला रहा है, तो उपयोगकर्ता आपके ऐप्लिकेशन को कोई दूसरा गाना चलाने के लिए, कार के डिसप्ले को देखे या छुए बिना “[गाने का टाइटल]चलाएं” कह सकता है. उपयोगकर्ता, अपने स्टीयरिंग व्हील पर मौजूद बटन पर क्लिक करके या "Ok Google" बोलकर क्वेरी शुरू कर सकते हैं.

जब Android Auto या Android Automotive OS किसी वॉइस ऐक्शन का पता लगाता है और उसे समझता है, तो उस वॉइस ऐक्शन को onPlayFromSearch() के ज़रिए ऐप्लिकेशन को भेजा जाता है. यह कॉलबैक मिलने पर, ऐप्लिकेशन query स्ट्रिंग से मैच होने वाला कॉन्टेंट ढूंढता है और उसे चलाना शुरू करता है.

उपयोगकर्ता अपनी क्वेरी में अलग-अलग कैटगरी के शब्दों का इस्तेमाल कर सकते हैं: शैली, कलाकार, एल्बम, गाने का नाम, रेडियो स्टेशन या प्लेलिस्ट वगैरह. खोज के लिए सहायता बनाते समय, उन सभी कैटगरी का ध्यान रखें जो आपके ऐप्लिकेशन के लिए काम की हैं. अगर Android Auto या Android Automotive OS को पता चलता है कि कोई क्वेरी कुछ कैटगरी में फ़िट होती है, तो वह extras पैरामीटर में अतिरिक्त जानकारी जोड़ता है. ये अतिरिक्त जानकारी भेजी जा सकती है:

• EXTRA_MEDIA_ALBUM
• EXTRA_MEDIA_ARTIST
• EXTRA_MEDIA_GENRE
• EXTRA_MEDIA_PLAYLIST
• EXTRA_MEDIA_TITLE

खाते के लिए खाली query स्ट्रिंग, जिसे Android Auto या Android Automotive OS भेज सकता है. ऐसा तब होता है, जब उपयोगकर्ता खोज के लिए कोई शब्द न डाले. उदाहरण के लिए, अगर उपयोगकर्ता कहता है कि "कोई संगीत चलाओ." ऐसे में, आपका ऐप्लिकेशन हाल ही में सुने गए या सुझाए गए किसी ट्रैक को चला सकता है.

अगर किसी खोज को तुरंत प्रोसेस नहीं किया जा सकता, तो उसे onPlayFromSearch() में ब्लॉक न करें. इसके बजाय, प्लेबैक की स्थिति को STATE_CONNECTING पर सेट करें और खोज को असाइन्क्रोनस थ्रेड पर करें.

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

Android Auto और Android Automotive OS, "चलाएं" क्वेरी के अलावा, "संगीत रोकें" और "अगला गाना" जैसी क्वेरी को कंट्रोल करने के लिए, बोली को पहचानते हैं. साथ ही, इन निर्देशों को onPause() और onSkipToNext() जैसे सही मीडिया सेशन कॉलबैक से मैच करते हैं.

अपने ऐप्लिकेशन में, बोलकर वीडियो चलाने की सुविधा को लागू करने का उदाहरण देखने के लिए, Google Assistant और मीडिया ऐप्लिकेशन देखें.

ध्यान भटकाने वाले सुरक्षा उपायों को लागू करना

Android Auto का इस्तेमाल करते समय, उपयोगकर्ता का फ़ोन उसकी कार के स्पीकर से कनेक्ट होता है. इसलिए, ड्राइवर का ध्यान भटकने से बचाने के लिए, आपको कुछ और सावधानियां बरतनी होंगी.

कार में अलार्म बंद करें

Android Auto के मीडिया ऐप्लिकेशन को कार के स्पीकर से ऑडियो तब तक नहीं चलाना चाहिए, जब तक कि उपयोगकर्ता ने उसे चलाने के लिए कोई कार्रवाई न की हो. जैसे, चलाने के बटन को दबाना. यहां तक कि आपके मीडिया ऐप्लिकेशन के उपयोगकर्ता के शेड्यूल किए गए अलार्म को भी कार के स्पीकर से संगीत चलाना शुरू नहीं करना चाहिए.

इस ज़रूरी शर्त को पूरा करने के लिए, आपका ऐप्लिकेशन कोई भी ऑडियो चलाने से पहले, सिग्नल के तौर पर CarConnection का इस्तेमाल कर सकता है. आपका ऐप्लिकेशन यह देख सकता है कि फ़ोन, कार की स्क्रीन पर प्रोजेक्ट कर रहा है या नहीं. इसके लिए, वह कार के कनेक्शन टाइप के लिए LiveData को देखता है और यह जांच करता है कि वह CONNECTION_TYPE_PROJECTION के बराबर है या नहीं.

अगर उपयोगकर्ता का फ़ोन प्रोजेक्ट हो रहा है, तो अलार्म का इस्तेमाल करने वाले मीडिया ऐप्लिकेशन को इनमें से कोई एक काम करना होगा:

• अलार्म बंद करें.
• STREAM_ALARM पर अलार्म चलाएं और अलार्म बंद करने के लिए, फ़ोन की स्क्रीन पर यूज़र इंटरफ़ेस (यूआई) दें.

मीडिया विज्ञापनों को मैनेज करना

डिफ़ॉल्ट रूप से, Android Auto किसी ऑडियो प्लेबैक सेशन के दौरान, मीडिया मेटाडेटा में बदलाव होने पर सूचना दिखाता है. जब कोई मीडिया ऐप्लिकेशन, संगीत चलाने से विज्ञापन चलाने पर स्विच करता है, तो उपयोगकर्ता को सूचना दिखाने से ध्यान भटकता है. इस मामले में, Android Auto को सूचना दिखाने से रोकने के लिए, आपको मीडिया मेटाडेटा बटन METADATA_KEY_IS_ADVERTISEMENT को METADATA_VALUE_ATTRIBUTE_PRESENT पर सेट करना होगा. इस बारे में यहां दिए गए कोड स्निपेट में बताया गया है:

import androidx.media.utils.MediaConstants

override fun onPlayFromMediaId(mediaId: String, extras: Bundle?) {
    MediaMetadataCompat.Builder().apply {
        if (isAd(mediaId)) {
            putLong(
                MediaConstants.METADATA_KEY_IS_ADVERTISEMENT,
                MediaConstants.METADATA_VALUE_ATTRIBUTE_PRESENT)
        }
        // ...add any other properties you normally would.
        mediaSession.setMetadata(build())
    }
}

import androidx.media.utils.MediaConstants;

@Override
public void onPlayFromMediaId(String mediaId, Bundle extras) {
    MediaMetadataCompat.Builder builder = new MediaMetadataCompat.Builder();
    if (isAd(mediaId)) {
        builder.putLong(
            MediaConstants.METADATA_KEY_IS_ADVERTISEMENT,
            MediaConstants.METADATA_VALUE_ATTRIBUTE_PRESENT);
    }
    // ...add any other properties you normally would.
    mediaSession.setMetadata(builder.build());
}

सामान्य गड़बड़ियां ठीक करना

जब ऐप्लिकेशन में कोई गड़बड़ी होती है, तो वीडियो चलाने की स्थिति को STATE_ERROR पर सेट करें और setErrorMessage() तरीके का इस्तेमाल करके, गड़बड़ी का मैसेज दें. गड़बड़ी के उन कोड की सूची के लिए PlaybackStateCompat देखें जिनका इस्तेमाल, गड़बड़ी का मैसेज सेट करते समय किया जा सकता है. गड़बड़ी के मैसेज, उपयोगकर्ता को दिखने चाहिए और उपयोगकर्ता के मौजूदा भाषा-देश के हिसाब से होने चाहिए. इसके बाद, Android Auto और Android Automotive OS, उपयोगकर्ता को गड़बड़ी का मैसेज दिखा सकते हैं.

उदाहरण के लिए, अगर कॉन्टेंट उपयोगकर्ता के मौजूदा इलाके में उपलब्ध नहीं है, तो गड़बड़ी का मैसेज सेट करते समय, ERROR_CODE_NOT_AVAILABLE_IN_REGION गड़बड़ी कोड का इस्तेमाल किया जा सकता है.

mediaSession.setPlaybackState(
    PlaybackStateCompat.Builder()
        .setState(PlaybackStateCompat.STATE_ERROR)
        .setErrorMessage(PlaybackStateCompat.ERROR_CODE_NOT_AVAILABLE_IN_REGION, getString(R.string.error_unsupported_region))
        // ...and any other setters.
        .build())

mediaSession.setPlaybackState(
    new PlaybackStateCompat.Builder()
        .setState(PlaybackStateCompat.STATE_ERROR)
        .setErrorMessage(PlaybackStateCompat.ERROR_CODE_NOT_AVAILABLE_IN_REGION, getString(R.string.error_unsupported_region))
        // ...and any other setters.
        .build());

गड़बड़ी की स्थितियों के बारे में ज़्यादा जानने के लिए, मीडिया सेशन का इस्तेमाल करना: स्थितियां और गड़बड़ियां लेख पढ़ें.

अगर Android Auto के किसी उपयोगकर्ता को गड़बड़ी को ठीक करने के लिए, आपके फ़ोन पर मौजूद ऐप्लिकेशन खोलना पड़ता है, तो मैसेज में उपयोगकर्ता को यह जानकारी दें. उदाहरण के लिए, गड़बड़ी के मैसेज में "कृपया साइन इन करें" के बजाय, "[आपके ऐप्लिकेशन का नाम] में साइन इन करें" लिखा हो सकता है.

अन्य संसाधन

• Universal Media Player का सैंपल
• ऑडियो ऐप्लिकेशन की खास जानकारी
• ExoPlayer के बारे में खास जानकारी