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

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

GitHub पर इंटिग्रेशन का सैंपल कोड उपलब्ध है.

नेटिव ऐप्लिकेशन के लिए बिल्ड करना

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

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

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

3. ऐसेट पैक की डायरेक्ट्री में, build.gradle फ़ाइल बनाएं और उसमें यह कोड जोड़ें. पक्का करें कि आपने ऐसेट पैक का नाम और सिर्फ़ एक डिलीवरी टाइप तय किया हो:

   // 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 ]"
       }
   }

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

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

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

   // In the settings.gradle 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 ऐसेट डिलीवरी लाइब्रेरी के साथ इंटिग्रेट करना

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

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

Play Core नेटिव एसडीके, ऐसेट पैक का अनुरोध करने, डाउनलोड मैनेज करने, और ऐसेट ऐक्सेस करने के लिए, C हेडर फ़ाइल play/asset_pack.h उपलब्ध कराता है.

Play Core नेटिव एसडीके के लिए, अपना डेवलपमेंट एनवायरमेंट सेट अप करना

1. इनमें से कोई एक विकल्प चुनें:

   • Android Studio का 4.0 या इसके बाद का वर्शन इंस्टॉल करें. एसडीके मैनेजर के यूज़र इंटरफ़ेस (यूआई) का इस्तेमाल करके, Android SDK प्लैटफ़ॉर्म के 10.0 वर्शन (एपीआई लेवल 29) को इंस्टॉल करें.
   • Android SDK कमांड-लाइन टूल इंस्टॉल करें और sdkmanager का इस्तेमाल करके, Android SDK प्लैटफ़ॉर्म के 10.0 वर्शन (एपीआई लेवल 29) को इंस्टॉल करें.

2. Android Studio को नेटिव डेवलपमेंट के लिए तैयार करें. इसके लिए, एसडीके मैनेजर का इस्तेमाल करके, CMake और Android नेटिव डेवलपमेंट किट (एनडीके) का नया वर्शन इंस्टॉल करें. नेटिव प्रोजेक्ट बनाने या इंपोर्ट करने के बारे में ज़्यादा जानने के लिए, एनडीके का इस्तेमाल शुरू करना लेख पढ़ें.

3. ZIP फ़ाइल डाउनलोड करें और उसे अपने प्रोजेक्ट के साथ एक्सट्रैक्ट करें.

   डाउनलोड करने का लिंक	साइज़	SHA-256 चेकसम
   play-core-native-sdk-1.16.0.zip	54.8 MiB	008b8fedc6179a6dc6ccc21af75591afc7036f78f3d5559d844f1b923934fef0

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

   शानदार

       // App build.gradle
   
       plugins {
         id 'com.android.application'
       }
   
       // Define a path to the extracted Play Core SDK files.
       // If using a relative path, wrap it with file() since CMake requires absolute paths.
       def playcoreDir = file('../path/to/playcore-native-sdk')
   
       android {
           defaultConfig {
               ...
               externalNativeBuild {
                   cmake {
                       // Define the PLAYCORE_LOCATION directive.
                       arguments "-DANDROID_STL=c++_static",
                                 "-DPLAYCORE_LOCATION=$playcoreDir"
                   }
               }
               ndk {
                   // Skip deprecated ABIs. Only required when using NDK 16 or earlier.
                   abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
               }
           }
           buildTypes {
               release {
                   // Include Play Core Library proguard config files to strip unused code while retaining the Java symbols needed for JNI.
                   proguardFile '$playcoreDir/proguard/common.pgcfg'
                   proguardFile '$playcoreDir/proguard/gms_task.pgcfg'
                   proguardFile '$playcoreDir/proguard/per-feature-proguard-files'
                   ...
               }
               debug {
                   ...
               }
           }
           externalNativeBuild {
               cmake {
                   path 'src/main/CMakeLists.txt'
               }
           }
       }
   
       dependencies {
           // Import these feature-specific AARs for each Google Play Core library.
           implementation 'com.google.android.play:app-update:2.1.0'
           implementation 'com.google.android.play:asset-delivery:2.3.0'
           implementation 'com.google.android.play:integrity:1.6.0'
           implementation 'com.google.android.play:review:2.0.2'
   
           // Import these common dependencies.
           implementation 'com.google.android.gms:play-services-tasks:18.0.2'
           implementation files("$playcoreDir/playcore-native-metadata.jar")
           ...
       }
       

   Kotlin

   // App build.gradle
   
   plugins {
       id("com.android.application")
   }
   
   // Define a path to the extracted Play Core SDK files.
   // If using a relative path, wrap it with file() since CMake requires absolute paths.
   val playcoreDir = file("../path/to/playcore-native-sdk")
   
   android {
       defaultConfig {
           ...
           externalNativeBuild {
               cmake {
                   // Define the PLAYCORE_LOCATION directive.
                   arguments += listOf("-DANDROID_STL=c++_static", "-DPLAYCORE_LOCATION=$playcoreDir")
               }
           }
           ndk {
               // Skip deprecated ABIs. Only required when using NDK 16 or earlier.
               abiFilters.clear()
               abiFilters += listOf("armeabi-v7a", "arm64-v8a", "x86", "x86_64")
           }
       }
       buildTypes {
           release {
               // Include Play Core Library proguard config files to strip unused code while retaining the Java symbols needed for JNI.
               proguardFile("$playcoreDir/proguard/common.pgcfg")
               proguardFile("$playcoreDir/proguard/gms_task.pgcfg")
               proguardFile("$playcoreDir/proguard/per-feature-proguard-files")
               ...
           }
           debug {
               ...
           }
       }
       externalNativeBuild {
           cmake {
               path = "src/main/CMakeLists.txt"
           }
       }
   }
   
   dependencies {
       // Import these feature-specific AARs for each Google Play Core library.
       implementation("com.google.android.play:app-update:2.1.0")
       implementation("com.google.android.play:asset-delivery:2.3.0")
       implementation("com.google.android.play:integrity:1.6.0")
       implementation("com.google.android.play:review:2.0.2")
   
       // Import these common dependencies.
       implementation("com.google.android.gms:play-services-tasks:18.0.2")
       implementation(files("$playcoreDir/playcore-native-metadata.jar"))
       ...
   }

5. अपने ऐप्लिकेशन की CMakeLists.txt फ़ाइलों को यहां दिखाए गए तरीके से अपडेट करें:

   cmake_minimum_required(VERSION 3.6)
   
   ...
   
   # Add a static library called “playcore” built with the c++_static STL.
   include(${PLAYCORE_LOCATION}/playcore.cmake)
   add_playcore_static_library()
   
   // In this example “main” is your native code library, i.e. libmain.so.
   add_library(main SHARED
           ...)
   
   target_include_directories(main PRIVATE
           ${PLAYCORE_LOCATION}/include
           ...)
   
   target_link_libraries(main
           android
           playcore
           ...)
   

डेटा कलेक्शन

Play Core नेटिव एसडीके, वर्शन से जुड़ा डेटा इकट्ठा कर सकता है. इससे Google को प्रॉडक्ट को बेहतर बनाने में मदद मिलती है. इसमें यह डेटा शामिल है:

• ऐप्लिकेशन के पैकेज का नाम
• ऐप्लिकेशन के पैकेज का वर्शन
• Play Core नेटिव एसडीके का वर्शन

यह डेटा तब इकट्ठा किया जाएगा, जब Play Console पर आपका ऐप्लिकेशन पैकेज अपलोड किया जाएगा. डेटा इकट्ठा करने की इस प्रोसेस से बाहर निकलने के लिए, build.gradle फ़ाइल से $playcoreDir/playcore-native-metadata.jar इंपोर्ट को हटाएं.

ध्यान दें कि Play Core नेटिव एसडीके के आपके इस्तेमाल से जुड़ा यह डेटा कलेक्शन और Google के ज़रिए इकट्ठा किए गए डेटा का इस्तेमाल, Google के उस डेटा कलेक्शन से अलग है जो Gradle में लाइब्रेरी डिपेंडेंसी के तौर पर बताया जाता है. यह डेटा तब इकट्ठा किया जाता है, जब Play Console पर अपना ऐप्लिकेशन पैकेज अपलोड किया जाता है.

इंस्टॉल-टाइम डिलीवरी

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

#include <android/asset_manager.h>
#include <android_native_app_glue.h>
...
AAssetManager* assetManager = app->activity->assetManager;
AAsset* asset = AAssetManager_open(assetManager, "asset-name", AASSET_MODE_BUFFER);
size_t assetLength = AAsset_getLength(asset);
char* buffer = (char*) malloc(assetLength + 1);
AAsset_read(asset, buffer, assetLength);

Fast-follow और on-demand डिलीवरी

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

ऐप्लिकेशन लॉन्च करना

किसी अन्य फ़ंक्शन को कॉल करने से पहले, ऐसेट पैक एपीआई को शुरू करने के लिए हमेशा AssetPackManager_init() को कॉल करें. ऐसेट पैक के किसी भी गड़बड़ी कोड की जांच करें.

#include "play/asset_pack.h"
...
AssetPackErrorCode AssetPackManager_init(JavaVM* jvm, jobject android_context);

साथ ही, onPause() और onResume() के ANativeActivityCallbacks में, इन फ़ंक्शन को कॉल करना न भूलें:

• AssetPackErrorCode AssetPackManager_onPause()
• AssetPackErrorCode AssetPackManager_onResume()

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

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

AssetPackErrorCode AssetPackManager_requestInfo();      // Call once
AssetPackErrorCode AssetPackManager_getDownloadState(); // Call once per frame in your game loop

The AssetPackManager_getDownloadState() फ़ंक्शन, अपारदर्शी टाइप AssetPackDownloadState को आउटपुट पॉइंटर के तौर पर दिखाता है. इन फ़ंक्शन को कॉल करने के लिए, इस पॉइंटर का इस्तेमाल करें:

AssetPackDownloadState* state;
AssetPackErrorCode error_code = AssetPackManager_getDownloadState(asset-pack-name, &state);
AssetPackDownloadStatus status = AssetPackDownloadState_getStatus(state);
uint64_t downloadedBytes = AssetPackDownloadState_getBytesDownloaded(state);
uint64_t totalBytes = AssetPackDownloadState_getTotalBytesToDownload(state));
AssetPackDownloadState_destroy(state);

इंस्टॉल करें

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

AssetPackErrorCode AssetPackManager_requestDownload();  // Call once
AssetPackErrorCode AssetPackManager_getDownloadState(); // Call once per frame in your game loop

AssetPackManager_getDownloadState() फ़ंक्शन, अपारदर्शी टाइप AssetPackDownloadState दिखाता है. इस टाइप का इस्तेमाल करने के बारे में जानकारी पाने के लिए, डाउनलोड की जानकारी पाना देखें.

बड़े डाउनलोड

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

• AssetPackManager_showConfirmationDialog()
• AssetPackManager_getShowConfirmationDialogStatus()

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

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

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

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

• ASSET_PACK_STORAGE_APK: ऐसेट पैक, APK के तौर पर इंस्टॉल किया जाता है. इन ऐसेट को ऐक्सेस करने के लिए, इंस्टॉल-टाइम डिलीवरी देखें.
• ASSET_PACK_STORAGE_FILES: ऐसेट वाली डायरेक्ट्री का फ़ाइल पाथ पाने के लिए, AssetPackLocation_getAssetsPath() का इस्तेमाल करें. अगर ऐसेट डाउनलोड नहीं की गई हैं, तो यह फ़ंक्शन null दिखाता है. इस फ़ाइल पाथ में डाउनलोड की गई फ़ाइलों में बदलाव न करें.

AssetPackLocation* location;

AssetPackErrorCode error_code = AssetPackManager_getAssetPackLocation(asset-pack-name, &location);

if (error_code == ASSET_PACK_NO_ERROR) {
    AssetPackStorageMethod storage_method = AssetPackLocation_getStorageMethod(location);
    const char* assets_path = AssetPackLocation_getAssetsPath(location);
    AssetPackLocation_destroy(location);
}

ऐसेट की जगह पता चलने के बाद, फ़ाइलों को ऐक्सेस करने के लिए, fopen या ifstream जैसे फ़ंक्शन का इस्तेमाल करें.

Play Core API के अन्य तरीके

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

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

चालू ऐसेट पैक के अनुरोध को रद्द करने के लिए, AssetPackManager_cancelDownload() का इस्तेमाल करें. ध्यान दें कि यह अनुरोध, बेहतर कोशिश के तौर पर किया जाता है.

हटाने का अनुरोध करें

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

अगले चरण

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