ऐसेट डिलीवरी को इंटिग्रेट करना (Kotlin और Java)

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

Kotlin और Java के लिए बनाना

अपने प्रोजेक्ट के Android ऐप्लिकेशन बंडल में Play एसेट डिलीवरी बनाने के लिए, यह तरीका अपनाएं. ये चरण पूरा करने के लिए, आपको Android Studio का इस्तेमाल करने की ज़रूरत नहीं है.

1. अपने प्रोजेक्ट की build.gradle फ़ाइल में, Android Gradle प्लग इन के वर्शन को 4.0.0 या उसके बाद के वर्शन पर अपडेट करें.

2. अपने प्रोजेक्ट की टॉप-लेवल डायरेक्ट्री में, एसेट पैक के लिए एक डायरेक्ट्री बनाएं. इस डायरेक्ट्री के नाम का इस्तेमाल, एसेट पैक के नाम के तौर पर किया जाता है. एसेट पैक के नाम किसी अक्षर से शुरू होने चाहिए. साथ ही, उनमें सिर्फ़ अक्षर, संख्याएं, और अंडरस्कोर हो सकते हैं.

3. ऐसेट पैक डायरेक्ट्री में, build.gradle फ़ाइल बनाएं और नीचे दिया गया कोड जोड़ें. एसेट पैक का नाम और डिलीवरी का सिर्फ़ एक टाइप डालना न भूलें:

   Groovy

   // In the asset pack's build.gradle file:
   plugins {
     id 'com.android.asset-pack'
   }
   
   assetPack {
       packName = "asset-pack-name" // Directory name for the asset pack
       dynamicDelivery {
           deliveryType = "[ install-time | fast-follow | on-demand ]"
       }
   }

   Kotlin

   // In the asset pack's build.gradle.kts file:
   plugins {
     id("com.android.asset-pack")
   }
   
   assetPack {
     packName.set("asset-pack-name") // Directory name for the asset pack
     dynamicDelivery {
       deliveryType.set("[ install-time | fast-follow | on-demand ]")
     }
   }

4. प्रोजेक्ट की ऐप्लिकेशन build.gradle फ़ाइल में, अपने प्रोजेक्ट के हर ऐसेट पैक का नाम जोड़ें, जैसा कि यहां दिखाया गया है:

   Groovy

   // In the app build.gradle file:
   android {
       ...
       assetPacks = [":asset-pack-name", ":asset-pack2-name"]
   }

   Kotlin

   // In the app build.gradle.kts file:
   android {
       ...
       assetPacks += listOf(":asset-pack-name", ":asset-pack2-name")
   }

5. प्रोजेक्ट की settings.gradle फ़ाइल में, अपने प्रोजेक्ट में सभी ऐसेट पैक शामिल करें, जैसा कि यहां दिखाया गया है:

   Groovy

   // In the settings.gradle file:
   include ':app'
   include ':asset-pack-name'
   include ':asset-pack2-name'

   Kotlin

   // In the settings.gradle.kts file:
   include(":app")
   include(":asset-pack-name")
   include(":asset-pack2-name")

6. ऐसेट पैक डायरेक्ट्री में, यह सबडायरेक्ट्री बनाएं: src/main/assets.

7. ऐसेट को src/main/assets डायरेक्ट्री में डालें. यहां भी सब-डायरेक्ट्री बनाई जा सकती हैं. आपके ऐप्लिकेशन का डायरेक्ट्री स्ट्रक्चर अब इस तरह दिखना चाहिए:

   • build.gradle
   • settings.gradle
   • app/
   • asset-pack-name/build.gradle
   • asset-pack-name/src/main/assets/your-asset-directories

8. Gradle की मदद से Android ऐप्लिकेशन बंडल बनाएं. जनरेट किए गए ऐप्लिकेशन बंडल में, रूट-लेवल डायरेक्ट्री में अब ये शामिल हैं:

   • asset-pack-name/manifest/AndroidManifest.xml: ऐसेट पैक के आइडेंटिफ़ायर और डिलीवरी मोड को कॉन्फ़िगर करता है
   • asset-pack-name/assets/your-asset-directories: ऐसेट पैक के हिस्से के तौर पर डिलीवर की गई सभी एसेट वाली डायरेक्ट्री

   Gradle हर ऐसेट पैक के लिए मेनिफ़ेस्ट जनरेट करता है और आपके लिए assets/ डायरेक्ट्री को आउटपुट करता है.

9. (ज़रूरी नहीं) अगर आपको फ़ास्ट-फ़ॉलो और ऑन-डिमांड डिलीवरी का इस्तेमाल करना है, तो Play की ऐसेट डिलीवरी लाइब्रेरी शामिल करें

   Groovy

   implementation "com.google.android.play:asset-delivery:2.2.2"
   // For Kotlin use asset-delivery-ktx
   implementation "com.google.android.play:asset-delivery-ktx:2.2.2"

   Kotlin

   implementation("com.google.android.play:asset-delivery:2.2.2")
   // For Kotlin use core-ktx
   implementation("com.google.android.play:asset-delivery-ktx:2.2.2")

10. (ज़रूरी नहीं) अपने ऐप्लिकेशन बंडल को अलग-अलग टेक्स्चर के कम्प्रेशन फ़ॉर्मैट के साथ काम करने के लिए कॉन्फ़िगर करें.

Play Asset Delivery API के साथ इंटिग्रेट करना

Play ऐसेट डिलीवरी Java API, ऐसेट पैक का अनुरोध करने, डाउनलोड मैनेज करने, और ऐसेट ऐक्सेस करने के लिए, AssetPackManager क्लास उपलब्ध कराता है. सबसे पहले, अपने प्रोजेक्ट में Play की एसेट डिलीवरी लाइब्रेरी जोड़ें.

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

पहली इमेज. ऐसेट पैक को ऐक्सेस करने के लिए फ़्लो डायग्राम

ऐप्लिकेशन इंस्टॉल करते समय डिलीवरी

install-time के तौर पर कॉन्फ़िगर किए गए ऐसेट पैक, ऐप्लिकेशन के लॉन्च होने के साथ ही उपलब्ध हो जाते हैं. इस मोड में दिखाई गई ऐसेट को ऐक्सेस करने के लिए, Java AssetManager API का इस्तेमाल करें:

import android.content.res.AssetManager
...
val context: Context = createPackageContext("com.example.app", 0)
val assetManager: AssetManager = context.assets
val stream: InputStream = assetManager.open("asset-name")

import android.content.res.AssetManager;
...
Context context = createPackageContext("com.example.app", 0);
AssetManager assetManager = context.getAssets();
InputStream is = assetManager.open("asset-name");

फ़ास्ट-फ़ॉलो और मांग पर डिलीवरी

यहां दिए गए सेक्शन में, एसेट पैक को डाउनलोड करने से पहले उनके बारे में जानकारी पाने का तरीका बताया गया है. साथ ही, डाउनलोड शुरू करने के लिए एपीआई को कॉल करने और डाउनलोड किए गए पैक को ऐक्सेस करने का तरीका भी बताया गया है. ये सेक्शन, fast-follow और on-demand एसेट पैक पर लागू होते हैं.

स्थिति देखें

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

ऐसेट पैक डाउनलोड करने के बारे में जानकारी पाना

ऐप्लिकेशन को एसेट पैक फ़ेच करने से पहले, डाउनलोड के साइज़ के बारे में जानकारी देनी होगी. डाउनलोड के साइज़ और पैक के पहले से डाउनलोड हो रहे होने का पता लगाने के लिए, requestPackStates() या getPackStates() का इस्तेमाल करें.

suspend fun requestPackStates(packNames: List<String>): AssetPackStates

Task<AssetPackStates> getPackStates(List<String> packNames)

requestPackStates() एक सस्पेंड फ़ंक्शन है, जो AssetPackStates ऑब्जेक्ट दिखाता है. वहीं, getPackStates() एक असाइनोक्रोनस तरीका है, जो Task<AssetPackStates> दिखाता है. AssetPackStates ऑब्जेक्ट का packStates() तरीका, Map<String, AssetPackState> दिखाता है. इस मैप में, अनुरोध किए गए हर एसेट पैक की स्थिति दिखती है. इसकी जानकारी, उसके नाम के हिसाब से दी जाती है:

AssetPackStates#packStates(): Map<String, AssetPackState>

Map<String, AssetPackState> AssetPackStates#packStates()

फ़ाइनल अनुरोध इनके हिसाब से दिखाया जाता है:

const val assetPackName = "assetPackName"
coroutineScope.launch {
  try {
    val assetPackStates: AssetPackStates =
      manager.requestPackStates(listOf(assetPackName))
    val assetPackState: AssetPackState =
      assetPackStates.packStates()[assetPackName]
  } catch (e: RuntimeExecutionException) {
    Log.d("MainActivity", e.message)
  }
}

final String assetPackName = "myasset";

assetPackManager
    .getPackStates(Collections.singletonList(assetPackName))
    .addOnCompleteListener(new OnCompleteListener<AssetPackStates>() {
        @Override
        public void onComplete(Task<AssetPackStates> task) {
            AssetPackStates assetPackStates;
            try {
                assetPackStates = task.getResult();
                AssetPackState assetPackState =
                    assetPackStates.packStates().get(assetPackName);
            } catch (RuntimeExecutionException e) {
                Log.d("MainActivity", e.getMessage());
                return;
            })

यहां दिए गए AssetPackState तरीकों से, ऐसेट पैक का साइज़, अब तक डाउनलोड किए गए डेटा का साइज़ (अगर अनुरोध किया गया हो), और ऐप्लिकेशन में पहले से ट्रांसफ़र किए गए डेटा का साइज़ पता चलता है:

• totalBytesToDownload()
• bytesDownloaded()
• transferProgressPercentage()

किसी ऐसेट पैक की स्थिति जानने के लिए, status() वाले तरीके का इस्तेमाल करें. यह तरीका, स्थिति को पूर्णांक के तौर पर दिखाता है, जो AssetPackStatus क्लास में मौजूद एक कॉन्स्टेंट फ़ील्ड से मेल खाता है. ऐसेट पैक के इंस्टॉल न होने पर, उसका स्टेटस AssetPackStatus.NOT_INSTALLED होता है.

अगर अनुरोध पूरा नहीं होता है, तो errorCode() वाले तरीके का इस्तेमाल करें. इस तरीके से मिलने वाली वैल्यू, AssetPackErrorCode क्लास में मौजूद किसी कॉन्स्टेंट फ़ील्ड से मेल खाती है.

इंस्टॉल करें

पहली बार ऐसेट पैक डाउनलोड करने या ऐसेट पैक को अपडेट करने के लिए, requestFetch() या fetch() तरीकों का इस्तेमाल करें:

suspend fun AssetPackManager.requestFetch(packs: List<String>): AssetPackStates

Task<AssetPackStates> fetch(List<String> packNames)

यह तरीका एक AssetPackStates ऑब्जेक्ट दिखाता है. इसमें पैक की सूची के साथ-साथ, डाउनलोड की शुरुआती स्थिति और साइज़ की जानकारी होती है. अगर requestFetch() या fetch() के ज़रिए अनुरोध किया गया कोई ऐसेट पैक पहले से डाउनलोड हो रहा है, तो डाउनलोड की स्थिति दिखती है और कोई और डाउनलोड शुरू नहीं होता.

डाउनलोड की स्थिति मॉनिटर करना

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

fun registerListener(listener: AssetPackStateUpdatedListener)
fun unregisterListener(listener: AssetPackStateUpdatedListener)

void registerListener(AssetPackStateUpdatedListener listener)
void unregisterListener(AssetPackStateUpdatedListener listener)

बड़ी फ़ाइलें डाउनलोड करना

अगर डाउनलोड का साइज़ 200 एमबी से ज़्यादा है और उपयोगकर्ता वाई-फ़ाई से कनेक्ट नहीं है, तो डाउनलोड तब तक शुरू नहीं होता, जब तक उपयोगकर्ता मोबाइल डेटा कनेक्शन का इस्तेमाल करके डाउनलोड जारी रखने के लिए साफ़ तौर पर अपनी सहमति नहीं देता. इसी तरह, अगर डाउनलोड का साइज़ बड़ा है और उपयोगकर्ता का वाई-फ़ाई कनेक्शन बंद हो जाता है, तो डाउनलोड रुक जाता है. साथ ही, मोबाइल डेटा कनेक्शन का इस्तेमाल जारी रखने के लिए, उपयोगकर्ता की साफ़ तौर पर सहमति लेनी पड़ती है. रोके गए पैक का स्टेटस WAITING_FOR_WIFI होता है. उपयोगकर्ता से सहमति लेने के लिए यूज़र इंटरफ़ेस (यूआई) फ़्लो को ट्रिगर करने के लिए, showConfirmationDialog() तरीका इस्तेमाल करें.

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

उपयोगकर्ता की पुष्टि करना ज़रूरी है

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

यहां किसी लिसनर को लागू करने का उदाहरण दिया गया है:

private val activityResultLauncher = registerForActivityResult(
    ActivityResultContracts.StartIntentSenderForResult()
) { result ->
    if (result.resultCode == RESULT_OK) {
        Log.d(TAG, "Confirmation dialog has been accepted.")
    } else if (result.resultCode == RESULT_CANCELED) {
        Log.d(TAG, "Confirmation dialog has been denied by the user.")
    }
}

assetPackManager.registerListener { assetPackState ->
  when(assetPackState.status()) {
    AssetPackStatus.PENDING -> {
      Log.i(TAG, "Pending")
    }
    AssetPackStatus.DOWNLOADING -> {
      val downloaded = assetPackState.bytesDownloaded()
      val totalSize = assetPackState.totalBytesToDownload()
      val percent = 100.0 * downloaded / totalSize

      Log.i(TAG, "PercentDone=" + String.format("%.2f", percent))
    }
    AssetPackStatus.TRANSFERRING -> {
      // 100% downloaded and assets are being transferred.
      // Notify user to wait until transfer is complete.
    }
    AssetPackStatus.COMPLETED -> {
      // Asset pack is ready to use. Start the game.
    }
    AssetPackStatus.FAILED -> {
      // Request failed. Notify user.
      Log.e(TAG, assetPackState.errorCode())
    }
    AssetPackStatus.CANCELED -> {
      // Request canceled. Notify user.
    }
    AssetPackStatus.WAITING_FOR_WIFI,
    AssetPackStatus.REQUIRES_USER_CONFIRMATION -> {
      if (!confirmationDialogShown) {
        assetPackManager.showConfirmationDialog(activityResultLauncher);
        confirmationDialogShown = true
      }
    }
    AssetPackStatus.NOT_INSTALLED -> {
      // Asset pack is not downloaded yet.
    }
    AssetPackStatus.UNKNOWN -> {
      Log.wtf(TAG, "Asset pack status unknown")
    }
  }
}

assetPackStateUpdateListener = new AssetPackStateUpdateListener() {
    private final ActivityResultLauncher<IntentSenderRequest> activityResultLauncher =
      registerForActivityResult(
          new ActivityResultContracts.StartIntentSenderForResult(),
          new ActivityResultCallback<ActivityResult>() {
            @Override
            public void onActivityResult(ActivityResult result) {
              if (result.getResultCode() == RESULT_OK) {
                Log.d(TAG, "Confirmation dialog has been accepted.");
              } else if (result.getResultCode() == RESULT_CANCELED) {
                Log.d(TAG, "Confirmation dialog has been denied by the user.");
              }
            }
          });

    @Override
    public void onStateUpdate(AssetPackState assetPackState) {
      switch (assetPackState.status()) {
        case AssetPackStatus.PENDING:
          Log.i(TAG, "Pending");
          break;

        case AssetPackStatus.DOWNLOADING:
          long downloaded = assetPackState.bytesDownloaded();
          long totalSize = assetPackState.totalBytesToDownload();
          double percent = 100.0 * downloaded / totalSize;

          Log.i(TAG, "PercentDone=" + String.format("%.2f", percent));
          break;

        case AssetPackStatus.TRANSFERRING:
          // 100% downloaded and assets are being transferred.
          // Notify user to wait until transfer is complete.
          break;

        case AssetPackStatus.COMPLETED:
          // Asset pack is ready to use. Start the game.
          break;

        case AssetPackStatus.FAILED:
          // Request failed. Notify user.
          Log.e(TAG, assetPackState.errorCode());
          break;

        case AssetPackStatus.CANCELED:
          // Request canceled. Notify user.
          break;

        case AssetPackStatus.WAITING_FOR_WIFI:
        case AssetPackStatus.REQUIRES_USER_CONFIRMATION:
          if (!confirmationDialogShown) {
            assetPackManager.showConfirmationDialog(activityResultLauncher);
            confirmationDialogShown = true;
          }
          break;

        case AssetPackStatus.NOT_INSTALLED:
          // Asset pack is not downloaded yet.
          break;
        case AssetPackStatus.UNKNOWN:
          Log.wtf(TAG, "Asset pack status unknown")
          break;
      }
    }
}

इसके अलावा, getPackStates() के तरीके का इस्तेमाल करके, मौजूदा डाउनलोड की स्थिति देखी जा सकती है. AssetPackStates में, डाउनलोड की प्रोग्रेस, डाउनलोड की स्थिति, और गड़बड़ी के कोड शामिल होते हैं.

ऐसेट पैक ऐक्सेस करना

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

ऐसेट, ऐसेट पैक की रूट डायरेक्ट्री में assets डायरेक्ट्री में सेव की जाती हैं. assets डायरेक्ट्री का पाथ पाने के लिए, assetsPath() के लिए उपलब्ध आसान तरीके का इस्तेमाल करें. किसी खास ऐसेट का पाथ पाने के लिए, यह तरीका अपनाएं:

private fun getAbsoluteAssetPath(assetPack: String, relativeAssetPath: String): String? {
    val assetPackPath: AssetPackLocation =
      assetPackManager.getPackLocation(assetPack)
      // asset pack is not ready
      ?: return null

    val assetsFolderPath = assetPackPath.assetsPath()
    // equivalent to: FilenameUtils.concat(assetPackPath.path(), "assets")
    return FilenameUtils.concat(assetsFolderPath, relativeAssetPath)
}

private String getAbsoluteAssetPath(String assetPack, String relativeAssetPath) {
    AssetPackLocation assetPackPath = assetPackManager.getPackLocation(assetPack);

    if (assetPackPath == null) {
        // asset pack is not ready
        return null;
    }

    String assetsFolderPath = assetPackPath.assetsPath();
    // equivalent to: FilenameUtils.concat(assetPackPath.path(), "assets");
    String assetPath = FilenameUtils.concat(assetsFolderPath, relativeAssetPath);
    return assetPath;
}

Play ऐसेट डिलीवरी एपीआई के अन्य तरीके

यहां एपीआई के कुछ अन्य तरीके दिए गए हैं. इनका इस्तेमाल, अपने ऐप्लिकेशन में किया जा सकता है.

अनुरोध रद्द करें

किसी चालू एसेट पैक के अनुरोध को रद्द करने के लिए, cancel() का इस्तेमाल करें. ध्यान दें कि इस अनुरोध को पूरा करने के लिए, हम पूरी कोशिश करेंगे.

ऐसेट पैक हटाना

किसी ऐसेट पैक को हटाने के लिए, requestRemovePack() या removePack() का इस्तेमाल करें.

एक से ज़्यादा ऐसेट पैक की जगहें पाना

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

अगला चरण

स्थानीय तौर पर और Google Play से, Play एसेट डिलीवरी की सुविधा को टेस्ट करें.