Tích hợp phân phối thành phần (Unity)

Hãy làm theo các bước trong hướng dẫn này để truy cập vào gói tài sản của ứng dụng từ mã Unity C#.

Tạo Unity

Các tệp AssetBundle chứa tài sản nối tiếp được tải bằng công cụ Unity khi ứng dụng đang chạy. Các tệp này dành riêng cho nền tảng (ví dụ: được tạo dành cho Android) và có thể sử dụng kết hợp với gói tài sản. Trường hợp phổ biến nhất là một tệp AssetBundle được đóng thành gói tài sản duy nhất, đồng thời cũng lấy tên là AssetBundle. Nếu muốn linh hoạt hơn trong việc tạo gói tài sản, hãy định cấu hình gói tài sản đó bằng cách sử dụng API.

Khi chạy, sử dụng lớp Play Asset Delivery for Unity để truy xuất gói AssetBundle đã đóng trong gói tài sản.

Điều kiện tiên quyết

  1. Tải bản phát hành mới nhất của Play Asset Delivery Unity Plugin từ các gói Google dành cho Unity.

  2. Tạo AssetBundles trong Unity.

Sử dụng giao diện người dùng để định cấu hình AssetBundle

  1. Định cấu hình từng AssetBundle trong gói tài sản:

    1. Chọn Google > Android App Bundle > Cài đặt phân phối nội dung.
    2. Để chọn thư mục chứa trực tiếp tệp AssetBundle, nhấp vào Thêm thư mục.

  2. Đối với mỗi gói, hãy thay đổi Chế độ phân phối thành Thời gian cài đặt, Theo dõi nhanh hoặc Theo yêu cầu. Giải quyết lỗi hoặc phần phụ thuộc và đóng cửa sổ.

  3. Chọn Google > Tạo Android App Bundle để tạo gói ứng dụng.

  4. (Không bắt buộc) Định cấu hình gói ứng dụng để hỗ trợ nhiều định dạng nén kết cấu.

Định cấu hình gói tài sản bằng API

Có thể định cấu hình phân phối nội dung qua tập lệnh trình chỉnh sửa. Tập lệnh này chạy như một phần của hệ thống xây dựng tự động.

Sử dụng lớp AssetPackConfig để xác định những tài sản cần đưa vào bản dựng Android App Bundle cũng như chế độ phân phối của tài sản đó. Các gói tài sản này không cần chứa AssetBundle.

public void ConfigureAssetPacks {
   // Creates an AssetPackConfig with a single asset pack, named
   // examplePackName, containing all the files in path/to/exampleFolder.
   var assetPackConfig = new AssetPackConfig();
   assetPackConfig.AddAssetsFolder("examplePackName",
                                   "path/to/exampleFolder",
                                   AssetPackDeliveryMode.OnDemand);

   // Configures the build system to use the newly created assetPackConfig when
   // calling Google > Build and Run or Google > Build Android App Bundle.
   AssetPackConfigSerializer.SaveConfig(assetPackConfig);

   // Alternatively, use BundleTool.BuildBundle to build an App Bundle from script.
   BuildBundle(new buildPlayerOptions(), assetPackConfig);
}

Ngoài ra còn có thể sử dụng phương thức tĩnh BuildBundle trong lớp Bundletool để tạo Android App Bundle với gói tài sản, BuildPlayerOptionsAssetPackConfig.

Để tham khảo hướng dẫn từng bước, hãy xem nội dung Sử dụng Play Asset Delivery trong Lớp học lập trình trò chơi Unity.

Tích hợp với API Unity Asset Delivery Unity

API Unity Play Asset Delivery cung cấp chức năng yêu cầu gói tài sản, quản lý tài nguyên tải xuống và truy cập tài sản. Trước tiên, hãy nhớ Thêm trình bổ trợ Unity vào dự án.

Hàm sử dụng trong API phụ thuộc vào cách bạn tạo các gói tài sản.

Nếu bạn đã sử dụng trình bổ trợ giao diện người dùng tạo gói tài sản, hãy chọn Gói tài sản được định cấu hình trình bổ trợ.

Nếu bạn đã dùng API (hoặc trình bổ trợ giao diện người dùng) để tạo gói tài sản, hãy chọn Gói tài sản được định cấu hình API.

API tương tự nhau bất kể bạn muốn truy cập loại phân phối nào của gói tài sản. Các bước này hiển thị ở lưu đồ sau đây.

Sơ đồ quy trình gói tài sản cho API

Hình 1. Sơ đồ quy trình truy cập gói tài sản

Truy xuất gói tài sản

Nhập thư viện Play Asset Delivery và gọi phương thức RetrieveAssetPackAsync() để tải gói tài sản xuống nếu phiên bản mới nhất chưa có sẵn trên đĩa.

using Google.Play.AssetDelivery;

// After download, the assets and/or AssetBundles contained in the asset pack
// are not loaded into memory.
PlayAssetPackRequest request = PlayAssetDelivery.RetrieveAssetPackAsync(assetPackName);

Phân phối khi cài đặt

Một gói tài sản được định cấu hình install-time sẽ có sẵn ngay khi khởi chạy ứng dụng, nhưng cần tải tài sản của gói đó vào bộ nhớ. Xem Tải tài sản vào bộ nhớ.

Phân phối tiếp nối nhanh và theo yêu cầu

Phần này áp dụng cho các gói tài sản fast-followon-demand.

Kiểm tra trạng thái

Mỗi gói tài sản được lưu trữ trong một thư mục riêng ở bộ nhớ trong của ứng dụng. Sử dụng phương thức isDone() để xác định xem gói nội dung đã được tải xuống và có sẵn chưa hay đã xảy ra lỗi.

Theo dõi việc tải xuống

Truy vấn đối tượng PlayAssetPackRequest để theo dõi trạng thái của yêu cầu:

// Download progress of request, between 0.0f and 1.0f. The value will always be
// 1.0 for assets delivered as install-time.
// NOTE: A value of 1.0 does not mean that the request has completed, only that
// the DOWNLOADING stage is finished.
float progress = request.DownloadProgress;

// Returns the status of the retrieval request.
// If the request completed successfully, this value should be AssetDeliveryStatus.Available.
// If an error occurred, this value should be AssetDeliveryStatus.Failed.

AssetDelivery status = request.Status;
switch(status) {
    case AssetDeliveryStatus.Pending:
        // Asset pack download is pending - N/A for install-time assets.
    case AssetDeliveryStatus.Retrieving:
        // Asset pack is being downloaded and transferred to app storage.
        // N/A for install-time assets.
    case AssetDeliveryStatus.Available:
        // Asset pack is downloaded on disk but NOT loaded into memory.
        // For PlayAssetPackRequest(), this indicates that the request is complete.
    case AssetDeliveryStatus.Failed:
        // Asset pack retrieval failed.
    case AssetDeliveryStatus.WaitingForWifi:
        // Asset pack retrieval paused until either the device connects via Wi-Fi,
        // or the user accepts the PlayAssetDelivery.ShowCellularDataConfirmation dialog.
    default:
        break;
}

// Returns true if status is AssetDeliveryStatus.Available or AssetDeliveryStatus.Failed.
bool done = request.IsDone;

// If AssetDeliveryStatus.Failed, find more info about the error.
AssetDeliveryErrorCode error = request.Error;

Tải xuống kích thước lớn

Các gói tài sản lớn hơn 150 MB có thể tự động tải xuống, nhưng chỉ khi thiết bị được kết nối với Wi-Fi. Nếu người dùng không sử dụng Wi-Fi, trạng thái PlayAssetPackRequest được đặt là AssetDeliveryStatus.WaitingForWifi và tệp tải xuống sẽ bị tạm dừng. Trong trường hợp đó, hãy đợi đến khi thiết bị kết nối với Wi-Fi, tiếp tục tải xuống hoặc nhắc người dùng chấp thuận để tải gói xuống qua một kết nối di động.

if(request.Status == AssetDeliveryStatus.WaitingForWifi) {
    var userConfirmationOperation = PlayAssetDelivery.ShowCellularDataConfirmation();
    yield return userConfirmationOperation;

    switch(userConfirmationOperation.GetResult()) {
        case ConfirmationDialogResult.Unknown:
            // userConfirmationOperation finished with an error. Something went
            // wrong when displaying the prompt to the user, and they weren't
            // able to interact with the dialog. In this case, we recommend
            // developers wait for Wi-Fi before attempting to download again.
            // You can get more info by calling GetError() on the operation.
        case ConfirmationDialogResult.Accepted:
            // User accepted the confirmation dialog - download will start
            // automatically (no action needed).
        case ConfirmationDialogResult.Declined:
            // User canceled or declined the dialog. Await Wi-Fi connection, or
            // re-prompt the user.
        default:
            break;
    }
}

Hủy yêu cầu (chỉ theo yêu cầu)

Nếu bạn cần hủy yêu cầu trước khi tải các gói tài sản xuống, hãy gọi phương thức AttemptCancel() trên đối tượng PlayAssetPackRequest:

// Will only attempt if the status is Pending, Retrieving, or Available - otherwise
// it will be a no-op.
request.AttemptCancel();

// Check to see if the request was successful by checking if the error code is Canceled.
if(request.Error == AssetDeliveryErrorCode.Canceled) {
    // Request was successfully canceled.
}

Tải tài sản vào bộ nhớ

Sau khi yêu cầu hoàn tất, sử dụng một trong các hàm sau để tải nội dung vào bộ nhớ:

Yêu cầu gói tài sản không đồng bộ

Trong hầu hết các trường hợp, bạn nên sử dụng Coroutine để yêu cầu gói tài sản không đồng bộ và theo dõi tiến trình như bên dưới:

private IEnumerator LoadAssetPackCoroutine(string assetPackName) {

    PlayAssetPackRequest request =
        PlayAssetDelivery.RetrieveAssetPackAsync(assetPackName);

    while (!request.IsDone) {
        if(request.Status == AssetDeliveryStatus.WaitingForWifi) {
            var userConfirmationOperation = PlayAssetDelivery.ShowCellularDataConfirmation();

            // Wait for confirmation dialog action.
            yield return userConfirmationOperation;

            if((userConfirmationOperation.Error != AssetDeliveryErrorCode.NoError) ||
               (userConfirmationOperation.GetResult() != ConfirmationDialogResult.Accepted)) {
                // The user did not accept the confirmation - handle as needed.
            }

            // Wait for Wi-Fi connection OR confirmation dialog acceptance before moving on.
            yield return new WaitUntil(() => request.Status != AssetDeliveryStatus.WaitingForWifi);
        }

        // Use request.DownloadProgress to track download progress.
        // Use request.Status to track the status of request.

        yield return null;
    }

    if (request.Error != AssetDeliveryErrorCode.NoError) {
        // There was an error retrieving the pack. For error codes NetworkError
        // and InsufficientStorage, you may prompt the user to check their
        // connection settings or check their storage space, respectively, then
        // try again.
        yield return null;
    }

    // Request was successful. Load the asset pack into memory.
    AssetBundleCreateRequest assetBundleCreateRequest = request.LoadAssetBundleAsync(path/to/exampleBundle);
    yield return assetBundleCreateRequest;
    AssetBundle assetBundle = assetBundleCreateRequest.assetBundle;

Để biết thêm thông tin về cách xử lý lỗi, hãy xem danh sách mã lỗi.

Các phương thức API Play Core khác

Sau đây là một số phương thức API khác mà có thể bạn muốn sử dụng trong ứng dụng.

Truy xuất nhiều gói tài sản

Để truy xuất nhiều gói tài sản cùng lúc, hãy sử dụng chức năng sau:

// assetPackNames is an array of strings corresponding to asset packs.
PlayAssetPackBatchRequest batchRequest = PlayAssetDelivery.RetrieveAssetPackBatchAsync(<IListstring> assetPackNames);

Theo dõi trạng thái của từng yêu cầu bằng cách kiểm tra Dictionary tiểu bang:

// Dictionary of AssetPackStates, with the asset pack name as the key.
Dictionary<string, PlayAssetPackRequest> requests = batchRequest.Requests;

// Returns true if all requests are complete.
bool requestComplete = batchRequest.IsDone;

Kiểm tra kích thước tải xuống

Kiểm tra kích thước một gói tài sản bằng cách thực hiện lệnh gọi không đồng bộ đến Google Play và đặt phương thức gọi lại khi thao tác này hoàn tất:

public IEnumerator GetDownloadSize() {
   PlayAsyncOperation<long> getSizeOperation =
   PlayAssetDelivery.GetDownloadSize(assetPackName);

   yield return getSizeOperation;
   if(operation.Error != AssetDeliveryErrorCode.NoError) {
       // Error while retrieving download size.
    } else {
        // Download size is given in bytes.
        long downloadSize = operation.GetResult();
    }
}

Xóa AssetBundle

Bạn có thể xóa gói tài sản theo dõi nhanh và theo yêu cầu hiện chưa tải vào bộ nhớ. Hãy thực hiện lệnh gọi không đồng bộ sau và đặt phương thức gọi lại khi hoàn tất:

PlayAsyncOperation<string> removeOperation = PlayAssetDelivery.RemoveAssetPack(assetBundleName);

removeOperation.Completed += (operation) =>
            {
                if(operation.Error != AssetDeliveryErrorCode.NoError) {
                    // Error while attempting to remove AssetBundles.
                } else {
                    // Files were deleted OR files did not exist to begin with.
                }
            };

Bước tiếp theo

Thử nghiệm phân phối tài sản trên thiết bị và trên Google Play.