ApsaraVideo VOD:Envio de arquivos com o SDK para iOS

Método de integração

Opção 1: Integração via Pod

Adicione o seguinte conteúdo ao seu Podfile:

platform :ios, '12.0'
target 'YourApp' do
  pod 'VODUpload', '~> 2.0'
end

Execute os seguintes comandos:

pod repo update
pod install

O SDK baixa automaticamente a dependência subjacente AliyunOSSiOS.

Opção 2: Integração via Swift Package Manager (SPM)

1. No menu File do Xcode, selecione Add Package Dependencies e insira o endereço do repositório: https://github.com/aliyunvideo/VODUpload.git.

2. Selecione Up to Next Major Version como regra de versão e defina 2.0.1 como versão inicial.

3. Adicione o product VODUpload ao target do seu App.

Ou declare-o no Package.swift:

1.package(url: "https://github.com/aliyunvideo/VODUpload.git", from: "2.0.1")

As dependências subjacentes do OSS são analisadas automaticamente junto com o pacote principal. Não é necessário adicioná-las ou configurá-las manualmente. Após concluir a integração, basta importar o VODUpload. O uso da API é idêntico ao da integração via CocoaPods.

Configuração do projeto

O podspec declara as seguintes bibliotecas de sistema, vinculadas automaticamente quando você usa o CocoaPods para integração:

SystemConfiguration.framework
MobileCoreServices.framework
CoreMedia.framework
AVFoundation.framework
CoreTelephony.framework
libresolv.tbd

O SDK inclui um manifesto de privacidade PrivacyInfo.xcprivacy que é injetado automaticamente em VODUpload.bundle/PrivacyInfo.xcprivacy durante a integração via pod. Nenhuma configuração adicional é necessária.

Importe os arquivos de cabeçalho necessários:

#import <VODUpload/VODUploadV2Client.h>
#import <VODUpload/VODUploadConfig.h>
#import <VODUpload/VODAuthContext.h>
#import <VODUpload/VODGetAuthCallback.h>
#import <VODUpload/VODUploadOptions.h>
#import <VODUpload/VODUploadResult.h>
#import <VODUpload/VODUploadError.h>
#import <VODUpload/VODVideoMeta.h>
#import <VODUpload/VODImageMeta.h>
#import <VODUpload/VODUploadTask.h>

Inicializar uma instância de upload

O VODUploadConfig utiliza propriedades para configuração direta. Chame o método de fábrica +uploaderWithConfig: para criar uma instância:

VODUploadConfig *config = [[VODUploadConfig alloc] init];
config.getAuth = getAuth;                  // Required: authorization callback. For more information, see "Handle authorization callbacks".

VODUploadV2Client *uploader = [VODUploadV2Client uploaderWithConfig:config];

A instância uploader deve ser retida como uma propriedade. Se for uma variável local, o ARC a liberará, causando perda de callbacks. É possível reutilizar a mesma instância para enviar vários arquivos simultaneamente. Chame [uploader dispose] para liberar recursos quando o ciclo de vida terminar.

Enviar arquivos

Chame uploadFile:options:callback: para iniciar um upload. O método retorna um identificador VODUploadTask que pode ser usado para cancelamento:

VODVideoMeta *meta = [[VODVideoMeta alloc] init];
meta.title = @"My Video";
meta.tags = @"demo";
meta.cateId = @(1000);

VODUploadOptions *options = [[VODUploadOptions alloc] init];
options.videoMeta = meta;
options.onProgress = ^(float percent, int64_t uploaded, int64_t total) {
    NSLog(@"%.1f%%", percent * 100);
};

VODUploadTask *task = [uploader uploadFile:filePath
                                   options:options
                                  callback:^(VODUploadResult *r, VODUploadError *e) {
    if (e) {
        NSLog(@"%@: %@", e.errorCode, e.errorMessage);
        return;
    }
    NSLog(@"videoId=%@ uploadTaskId=%@ etag=%@ requestId=%@ durationMs=%lld",
          r.videoId, r.uploadTaskId, r.etag, r.requestId, r.durationMs);
}];

// Cancel during upload. Resumable upload is enabled by default. The next uploadFile call with the same file automatically resumes the upload.
[task cancel];
// task.uploadTaskId can be used to correlate logs and integrate with tracking.

Upload de imagens: O SDK utiliza automaticamente o processo de upload de imagens com base na extensão do arquivo (jpg / jpeg / png / gif / bmp / webp / heic) ou se options.imageMeta != nil estiver definido explicitamente. No callback de sucesso, imageId e imageUrl terão valores preenchidos:

VODImageMeta *imgMeta = [[VODImageMeta alloc] init];
imgMeta.imageType = @"cover";
imgMeta.title = @"Cover";

VODUploadOptions *opts = [[VODUploadOptions alloc] init];
opts.imageMeta = imgMeta;

[uploader uploadFile:imagePath options:opts callback:cb];

Tratar callbacks de autorização

Na versão 2, o bloco VODGetAuthCallback solicita credenciais de upload ao seu aplicativo. O SDK chama getAuth em pontos específicos e usa VODAuthContext.kind para indicar o tipo de credencial necessário:

Sua aplicação passa a resposta JSON bruta da chamada OpenAPI do backend diretamente para completion. O SDK lê as seguintes chaves da resposta da OpenAPI pelo nome do campo (diferencia maiúsculas de minúsculas):

Os nomes dos campos diferenciam maiúsculas de minúsculas. Repasse a resposta da OpenAPI diretamente. Renomear manualmente os campos para videoId, imageUrl ou image_url fará com que o SDK os interprete como nil.

VODGetAuthCallback getAuth = ^(VODAuthContext *ctx,
                               void (^completion)(NSDictionary *result, NSError *error)) {
    switch (ctx.kind) {
        case VODAuthKindCreateVideo:
            [YourBackend createUploadVideo:ctx.fileName
                                  fileSize:ctx.fileSize
                                completion:^(NSDictionary *json, NSError *err) {
                completion(json, err);
            }];
            break;
        case VODAuthKindRefreshVideo:
            [YourBackend refreshUploadVideo:ctx.videoId
                                 completion:^(NSDictionary *json, NSError *err) {
                completion(json, err);
            }];
            break;
        case VODAuthKindCreateImage:
            [YourBackend createUploadImage:ctx.fileName
                                completion:^(NSDictionary *json, NSError *err) {
                completion(json, err);
            }];
            break;
    }
};

Aceleração de upload

Defina VODVideoMeta.userData com o seguinte JSON. O servidor VOD retorna automaticamente o endpoint de aceleração de transferência global do OSS (oss-accelerate.aliyuncs.com) ao emitir o UploadAddress. Em seguida, o SDK envia diretamente para o endpoint de aceleração:

VODVideoMeta *meta = [[VODVideoMeta alloc] init];
meta.title = @"My Video";
meta.userData = @"{\"Type\":\"oss\",\"Domain\":\"oss-accelerate.aliyuncs.com\"}";

A aceleração de upload depende da aceleração de transferência global do OSS. É necessário ativar a aceleração de transferência para o bucket no console do OSS. Para mais informações, consulte Access OSS using transfer acceleration.

Upload e transcodificação

Especifique um grupo de modelos de transcodificação ou workflow usando VODVideoMeta:

VODVideoMeta *meta = [[VODVideoMeta alloc] init];
meta.title = @"My Video";
meta.desc = @"Video description";                     // Note: use desc, not description
meta.coverUrl = @"https://example.com/cover.jpg";
meta.cateId = @(1000);
meta.tags = @"tag1,tag2";
meta.storageLocation = @"<Optional: custom storage region>";
meta.templateGroupId = @"<Your template group ID>";    // Transcoding template group
meta.workflowId = @"<Your workflow ID>";          // Workflow (optional)
meta.appId = @"<Optional: application ID>";

Campos suportados pelo VODVideoMeta: title, desc, coverUrl, cateId, tags, userData, storageLocation, templateGroupId, workflowId e appId. Todos os campos são opcionais e repassados para CreateUploadVideo.

Após a conclusão do upload, o servidor VOD transcodifica o vídeo original com base no grupo de modelos. Caso não deseje acionar a transcodificação, passe um grupo de modelos "sem transcodificação" ao chamar CreateUploadVideo no seu backend.

Timeout e nova tentativa

VODUploadConfig *config = [[VODUploadConfig alloc] init];
config.getAuth = getAuth;
config.timeout = 60;            // Unit: seconds. Default value: 60
config.maxRetryCount = 2;       // Default value: 2

O parâmetro timeout controla o tempo limite de conexão e leitura/escrita (NSTimeInterval, em segundos) para uma única solicitação ao OSS. Já o maxRetryCount define o número de novas tentativas para solicitações ao OSS em caso de erros de rede.

Versão da assinatura

config.signature = @"v4";        // Default value: @"v4". Valid values: @"v1"

A assinatura V4 do OSS é a versão recomendada. A partir de 1º de setembro de 2025, a assinatura V4 será obrigatória para buckets recém-criados. Recomenda-se também que clientes existentes migrem o quanto antes. Defina @"v1" explicitamente apenas se o bucket utilizado pela sua aplicação ainda suportar exclusivamente assinaturas V1.

Upload retomável

O upload retomável vem ativado por padrão. O SDK usa a tríade (lastModified, fileName, fileSize) como chave de retomada e a persiste automaticamente no diretório local Caches:

Para desativar o upload retomável:

config.checkpoint = NO;

Upload multipart

Utilize partSize para controlar o tamanho das partes e parallel para definir o número de partes simultâneas:

// Global configuration
config.partSize = 1024 * 1024;     // Default value: 1 MB
config.parallel = 4;               // Default value: 4

// Per-task override
VODUploadOptions *options = [[VODUploadOptions alloc] init];
options.videoMeta = meta;
options.partSize = 2 * 1024 * 1024;
options.parallel = 6;

Definir a região do service VOD

config.region = @"cn-shanghai";    // Default value: cn-shanghai

Para consultar a lista de regiões suportadas, veja ApsaraVideo VOD region IDs.

Relatório de dados

O SDK ativa o rastreamento de link de upload por padrão para monitoramento da qualidade do product. Apenas métricas de tempo de execução do processo de upload são coletadas, sem inclusão do conteúdo dos arquivos. Para desativar o relatório de dados:

config.reportEnabled = NO;       // Default value: YES

if ([error.errorCode hasPrefix:@"UPLOAD.AUTH."]) {
    // Prompt the user to check the backend authorization
} else if ([error.errorCode isEqualToString:VODErrorCodeOssUploadFailed]) {
    // Retry or prompt the user to check the network
}
NSLog(@"%@ : %@ (cause=%@, suggestion=%@)",
      error.errorCode, error.errorMessage, error.cause, error.suggestion);

Posso iniciar várias chamadas uploadFile simultaneamente?

Sim. Cada task é independente. Controle o número de uploads simultâneos conforme as condições da rede para evitar pressão excessiva na largura de banda de upstream causada pela combinação com parallel.

O upload retomável não funciona após cancelamento e novo envio

Solucione o problema executando as etapas abaixo:

• Verifique se o caminho do arquivo é o mesmo.

• Confira se o lastModified ou o tamanho do arquivo foi alterado.

• Certifique-se de que config.checkpoint esteja definido como YES.

• Valide se o uploadId expirou. Ao receber a resposta NoSuchUpload, o SDK reverte automaticamente para um novo upload. Esse comportamento é esperado.

Revisão do App Store Connect rejeitada com "missing privacy manifest"

O SDK inclui um arquivo PrivacyInfo.xcprivacy que é injetado automaticamente durante a integração via pod. Certifique-se de que seu app também declare a Required Reason API que ele utiliza.

Callbacks não são acionados após criar o uploader

Garanta que uploader não seja uma variável local. A instância VODUploadV2Client deve ser retida como propriedade de self. Caso contrário, o ARC a liberará prematuramente.