Integrar a entrega de recursos (nativo)

Use as etapas deste guia para acessar os pacotes de recursos do app a partir do código C e C++.

Há um código de integração de amostra disponível no GitHub.

Criar para nativo

Use as etapas a seguir para criar o Play Asset Delivery no Android App Bundle do seu projeto. Não é necessário usar o Android Studio para executar estas etapas.

  1. Atualize a versão do Plug-in do Android para Gradle no arquivo build.gradle do projeto para 4.0.0 ou mais recente.

  2. No diretório de nível superior do projeto, crie um diretório para o pacote de recursos. O nome do diretório é usado como nome do pacote de recursos. Os nomes de pacotes de recursos precisam começar com uma letra e só podem conter letras, números e sublinhados.

  3. No diretório do pacote de recursos, crie um arquivo build.gradle e adicione o seguinte código. Especifique o nome do pacote de recursos e apenas um tipo de entrega:

    // In the asset pack’s build.gradle file:
    apply plugin: 'com.android.asset-pack'
    
    assetPack {
        packName = "asset-pack-name" // Directory name for the asset pack
        dynamicDelivery {
            deliveryType = "[ install-time | fast-follow | on-demand ]"
        }
    }
    
  4. No arquivo build.gradle do app do projeto, adicione o nome de cada pacote de recursos, conforme mostrado abaixo:

    // In the app build.gradle file:
    android {
        ...
        assetPacks = [":asset-pack-name", ":asset-pack2-name"]
    }
    
  5. No arquivo settings.gradle do projeto, inclua todos os pacotes de recursos, conforme mostrado abaixo:

    // In the settings.gradle file:
    include ':app'
    include ':asset-pack-name'
    include ':asset-pack2-name'
    
  6. No diretório do pacote de recursos, crie o seguinte subdiretório: src/main/assets.

  7. Coloque recursos no diretório src/main/assets. Você também pode criar subdiretórios nesse local. A estrutura de diretórios do seu app agora terá a seguinte aparência:

    • build.gradle
    • settings.gradle
    • app/
    • asset-pack-name/build.gradle
    • asset-pack-name/src/main/assets/your-asset-directories
  8. Crie o Android App Bundle com o Gradle. No pacote de apps gerado, o diretório de nível raiz agora inclui o seguinte:

    • asset-pack-name/manifest/AndroidManifest.xml: configura o identificador e o modo de entrega do pacote de recursos
    • asset-pack-name/assets/your-asset-directories: diretório que contém todos os recursos entregues como parte do pacote de recursos

    O Gradle gera o manifesto para cada pacote de recursos e gera o diretório assets/ para você.

  9. (Opcional) Configure seu pacote de apps para que ele seja compatível com diferentes formatos de compactação de textura.

Integrar com o SDK Play Core

O SDK nativo do Play Core fornece o arquivo de cabeçalho C play/asset_pack.h para solicitar pacotes de recursos, gerenciar downloads e acessar os recursos. Primeiro, adicione a Biblioteca Play Core ao seu projeto.

Implemente essa API de acordo com o tipo de entrega do pacote de recursos que você quer acessar. Essas etapas são mostradas no fluxograma a seguir.

Diagrama de fluxo de pacotes de recursos para código nativo

Figura 1. Diagrama de fluxo para acessar pacotes de recursos

Entrega no momento da instalação

Os pacotes de recursos configurados como install-time estão imediatamente disponíveis no lançamento do app. Use a API NDK AAssetManager para acessar os recursos disponibilizados neste modo:

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

Envio rápido e sob demanda

As seções a seguir mostram como inicializar a API, receber informações sobre pacotes de recursos antes de fazer o download deles, como chamar a API para iniciar o download e como acessar os pacotes baixados. Essas seções se aplicam aos pacotes de recursos fast-follow e on-demand.

Lançamento do app

Sempre chame AssetPackManager_init() para inicializar a API do pacote de recursos antes de chamar qualquer outra função. Verifique se há códigos de erro de pacote de recursos.

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

Além disso, chame as seguintes funções em onPause() e onResume() de ANativeActivityCallbacks:

Receber informações de download sobre pacotes de recursos

Os apps precisam divulgar o tamanho do download antes de buscar o pacote de recursos. Use a função AssetPackManager_requestInfo() para iniciar uma solicitação assíncrona para o tamanho do download e se o pacote já está sendo baixado. Em seguida, use AssetPackManager_getDownloadState() para pesquisar o estado do download. Por exemplo, chame essa função uma vez por frame no loop de jogo. Se uma solicitação falhar, verifique os códigos de erro do pacote de recursos.

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

A função AssetPackManager_getDownloadState() retorna o tipo opaco AssetPackDownloadState como um ponteiro de saída. Use este ponteiro para chamar as seguintes funções:

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

Instalar

Use AssetPackManager_requestDownload() para começar a fazer o download de um pacote de recursos pela primeira vez ou para solicitar a atualização:

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

A função AssetPackManager_getDownloadState() retorna o tipo opaco AssetPackDownloadState. Para informações sobre como usar esse tipo, consulte Receber informações de download.

Downloads grandes

Se o download for maior que 150 MB e o usuário não estiver conectado ao Wi-Fi, o download não será iniciado até que o usuário conceda explicitamente o consentimento para prosseguir com o download usando uma conexão de dados móveis. Da mesma forma, se o download for grande e o usuário perder o Wi-Fi, o download será pausado e o consentimento explícito será necessário para continuar usando uma conexão de dados móveis. Um pacote pausado tem o estado WAITING_FOR_WIFI. Para acionar o fluxo da IU para solicitar o consentimento do usuário, use o seguinte:

Acessar pacotes de recursos

É possível acessar um pacote de recursos usando chamadas do sistema de arquivos após a solicitação de download chegar ao estado COMPLETED. Cada pacote de recursos é armazenado em um diretório separado no armazenamento interno do app. Use AssetPackManager_getAssetPackLocation() para receber um AssetPackLocation para o pacote de recursos especificado. Use AssetPackLocation_getStorageMethod() nesse local para determinar o método de armazenamento:

  • ASSET_PACK_STORAGE_APK: o pacote de recursos está instalado como um APK. Consulte Envio no momento da instalação para acessar esses recursos.
  • ASSET_PACK_STORAGE_FILES: use AssetPackLocation_getAssetsPath() para ver um caminho de arquivo para o diretório que contém os recursos ou retorna nulo se os recursos não foram transferidos por download. Não modifique arquivos transferidos por download nesse caminho.
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);
}

Depois de localizar os recursos, use funções como fopen ou ifstream para acessar os arquivos.

Outros métodos da API Play Core

Veja a seguir alguns métodos adicionais de API que podem ser usados no seu app.

Cancelar solicitação

Use AssetPackManager_cancelDownload() para cancelar uma solicitação ativa de pacote de recursos. Observe que essa solicitação é uma operação de melhor esforço.

Solicitar remoção

Use AssetPackManager_requestRemoval() para programar a remoção de um pacote de recursos.

Próxima etapa

Teste o Play Asset Delivery localmente e no Google Play.