Visão Geral do Motor

O motor Zego Avatar possibilita a gestão personalizada de representações virtuais de usuários. Através de modelos padrão ou gerados especificamente, o sistema permite interação em tempo real com indivíduos reais, utilizando rastreamento facial e驱动ação por voz. Esta tecnologia é aplicável em diversos contextos, como transmissões ao vivo com áudio, plataformas sociais e ambientes de treinamento online.

Configuração do Ambiente e SDK

Pré-requisitos

Antes de iniciar a integração do SDK ZegoAvatar, valide se o ambiente de desenvolvimento satisfaz os seguintes critérios:

• Android Studio versão 2.1 ou superior.
• Android SDK 25, Build-Tools 25.0.2 e Platform-Tools 25.x.x ou versões mais recentes.
• Dispositivo físico com Android 5.1 ou superior, com suporte a áudio e vídeo.
• Funcionalidade de câmera frontal e microfone operacionais no dispositivo.

Importação do SDK

As arquiteturas suportadas atualmente incluem armeabi-v7a e arm64-v8a.

1. Acesse a página de download oficial para obter a versão mais recente do SDK.
2. Extraia o arquivo compactado e copie o pacote ZegoAvatar.aar para o diretório do seu projeto, por exemplo, app/libs.
3. Adicione a referência ao SDK. No diretório app, edite o arquivo build.gradle e inclua a dependência no bloco dependencies.

implementation fileTree(dir: 'libs', include: ['*.aar']) // Importação específica

Configuração de Permissões

Defina as permissões necessárias conforme a demanda da aplicação. No diretório app/src/main, edite o arquivo AndroidManifest.xml e insira as seguintes permissões:

<!-- Permissões obrigatórias para o SDK -->
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />

<!-- Permissões adicionais para a Aplicação -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />

<uses-feature
    android:glEsVersion="0x00020000"
    android:required="true" />

<uses-feature android:name="android.hardware.camera" />
<uses-feature android:name="android.hardware.camera.autofocus" />

Observação: No Android 6.0 e superior, permissões críticas exigem solicitação dinâmica em tempo de execução, além da declaração estática no manifest. Utilize o seguinte trecho para solicitar permissão de câmera:

private static final String[] PERMISSIONS_REQUIRED = {
    "android.permission.CAMERA"
};

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
    if (ContextCompat.checkSelfPermission(this, "android.permission.CAMERA") != PackageManager.PERMISSION_GRANTED) {
        ActivityCompat.requestPermissions(this, PERMISSIONS_REQUIRED, 101);
    }
}

Prevenção de Ofuscação

No arquivo proguard-rules.pro, adicione a regra -keep para evitar que as classes públicas do SDK sejam ofuscadas:

-keep class **.zego.**{*;}

Gestão de Recursos

Antes de utilizar as funcionalidades de IA do Avatar, é necessário importar os pacotes de recursos adequados.

Download Dinâmico (Recomendado)

Adição Local

1. Baixe os pacotes de recursos na página oficial.
2. Extraia e copie a pasta assets para o diretório assets do seu projeto.
3. Em tempo de execução, copie os arquivos AIModel.bundle, base.bundle e Packages para o diretório privado do dispositivo. Note que a pasta assets no Android é somente leitura.

AssetsFileTransfer.copyAssetsDir2Phone(this.getApplication(),
            "AIModel.bundle", "assets");
AssetsFileTransfer.copyAssetsDir2Phone(this.getApplication(),
            "base.bundle", "assets");
AssetsFileTransfer.copyAssetsDir2Phone(this.getApplication(),
            "Packages", "assets");

O método auxiliar para cópia pode ser implementado da seguinte forma:

public static void copyAssetsDir2Phone(Context context, String filePath, String destPath) {
    try {
        String[] fileList = context.getAssets().list(filePath);
        if (fileList.length > 0) {
            File file = new File(context.getFilesDir().getAbsolutePath() + File.separator + destPath + File.separator + filePath);
            if (file.exists()) {
                deleteAllFiles(file);
            }
            file.mkdirs();
            for (String fileName : fileList) {
                filePath = filePath + File.separator + fileName;
                copyAssetsDir2Phone(context, filePath, destPath);
                filePath = filePath.substring(0, filePath.lastIndexOf(File.separator));
            }
        } else {
            InputStream inputStream = context.getAssets().open(filePath);
            File file = new File(context.getFilesDir().getAbsolutePath() + File.separator + destPath + File.separator + filePath);
            if (file.exists()) {
                file.delete();
            }
            if (!file.exists() || file.length() == 0) {
                FileOutputStream fos = new FileOutputStream(file);
                int len;
                byte[] buffer = new byte[1024];
                while ((len = inputStream.read(buffer)) != -1) {
                    fos.write(buffer, 0, len);
                }
                fos.flush();
                inputStream.close();
                fos.close();
            }
        }
    } catch (IOException e) {
        e.printStackTrace();
    }
}

Após a cópia, utilize o caminho absoluto do recurso nas interfaces correspondentes.

Fluxo de Implementação

A sequência de chamadas de API para processamento de imagem é detalhada abaixo.

1. Autenticação e Licença

O ZEGO Avatar utiliza atuenticação online para obter o arquivo de licença.

1.1 Configuração de Credenciais

1. Crie um projeto no console ZEGO e obtenha um AppID válido.
2. Contate o suporte comercial para obter o AppSign vinculado ao AppID e Bundle ID do seu projeto.

1.2 Configuração no Código

Utilize uma classe de configuração para armazenar as credenciais de forma segura.

public class AvatarAuthConfig {
    // Endpoint do servidor de licença
    private static final String LICENSE_URL = "https://aieffects-api.zego.im?Action=DescribeAvatarLicense";
    
    // AppID obtido no console
    private static final long CLIENT_APP_ID = YOUR_APP_ID;
    
    // AppSign obtido via suporte
    private static final String CLIENT_APP_SIGN = "YOUR_APP_SIGN";
}

1.3 Obtenção da Licença

Utilize o helper de licença para solicitar a string de autenticação via rede.

AvatarLicenseHelper.requestLicense(new LicenseCallback() {
    @Override
    public void onSuccess(String licenseToken) {
        if (licenseToken != null && !licenseToken.isEmpty()) {
            setupAvatarEngine(licenseToken);
        }
    }
});

2. Inicialização do Serviço

Importe os cabeçalhos necessários e configure o serviço antes de criar qualquer instância de avatar.

import com.zego.avatar.ZegoAvatarService;
import com.zego.avatar.ZegoServiceConfig;

Inicialize o serviço passando a licença e o caminho do modelo de IA.

private void setupAvatarEngine(String authToken) {
    ZegoServiceConfig avatarConfig = new ZegoServiceConfig();
    avatarConfig.setLicense(authToken);
    avatarConfig.setAIPath(getApplicationContext().getFilesDir() + "/assets/AIModel.bundle");
    
    ZegoAvatarService.getInstance().addServiceObserver(this);
    ZegoAvatarService.getInstance().initWithConfig(avatarConfig);
}

Registre o callback para monitorar o estado da inicialização.

@Override
public void onStateChange(ZegoAvatarServiceState state) {
    if (state == ZegoAvatarServiceState.InitSucceed) {
        initializeAvatarCharacter();
    }
}

3. Instanciação do Avatar

Utilize a classe auxiliar ZegoCharacterHelper para gerenciar a criação, serailização e cache do personagem virtual.

private void initializeAvatarCharacter() {
    String resourcePath = getApplicationContext().getFilesDir() + "/assets/base.bundle";
    mAvatarManager = new ZegoCharacterHelper(resourcePath);
    
    String packagesPath = getApplicationContext().getFilesDir() + "/assets/Packages";
    mAvatarManager.setExtendPackagesPath(packagesPath);
    
    // Definir avatar padrão (ex: modelo masculino)
    mAvatarManager.setDefaultAvatar(MODEL_ID_MALE);

    // Criar a view do avatar
    mAvatarView = ZegoAvatarService.getInstance().createAvatarView(new Rect(0, 0, 200, 200));
    findViewById(R.id.container).addView(mAvatarView);

    // Vincular o personagem à view
    mAvatarManager.setCharacterView(mAvatarView);
}