Introdução ao Vungle - SDK v.6 para iOS (Swift)

Conteúdo

RGPD: Implementação recomendada

O Regulamento Geral sobre a Proteção de Dados (RGPD) entrou em vigor na União Europeia em 25 de maio. Para entrar em conformidade com o RGPD, desenvolvedores têm duas opções.

  • Opção 1 (recomendado): O distribuidor controla o processo de consentimento do RGPD do usuário e comunica as escolhas do usuário à Vungle. Para isso, os desenvolvedores podem coletar o consentimento do usuário usando seus próprios mecanismos, usando a seguir as APIs da Vungle para atualizar ou enviar uma consulta do status de consentimento do usuário. Consulte a seção Instruções de implementação recomendadas para RGPD para obter detalhes.

  • Opção 2: A Vungle pode lidar com as exigências, exibindo uma caixa de diálogo de consentimento antes de exibir um anúncio para um usuário europeu, e lembrará o consentimento ou rejeição do usuário em anúncios subsequentes.

Antes de começar

  • O Vungle SDK v. 6.x para iOS suporte somente iOS 8+.
  • O Vungle SDK v. 6.x para iOS suporta aplicativos de 32 e 64 bits.
  • A integração requer que você tenha uma conta Vungle. Se você ainda não tem uma conta, crie uma antes de continuar.
  • Nosso SDK iOS (a partir da v. 4.0.8) mais recente foi lançado como suporte ao novo Xcode 8.0. Certifique-se de usar o Xcode 8.0 ou superior para garantir uma integração perfeita.
  • O código-fonte mencionado aqui está disponível em nosso repositório do GitHub público.

 

Etapa 1. Adicionar o framework Vungle ao projeto Xcode

Adicione o VungleSDK.framework ao seu projeto

Há duas maneiras de adicionar o Vungle a seu projeto do Xcode: usando Cocoapods ou integração manual.

Cocoapods

O Vungle SDK está disponível pelo Cocoapods. Adicione o Vungle ao seu projeto adicionando a seguinte linha ao podfile do projeto.

 pod "VungleSDK-iOS", "6.x"

Depois disso, uma execução rápida do pod install deve atualizar seu projeto com a versão mais recente de nosso SDK para iOS. Neste ponto, você pode ir para a “Etapa 2. Remover a barra de status do iOS”.

Integração manual

Faça download do Vungle SDK v6.x. Se estiver fazendo a atualização de uma versão anterior do Vungle SDK, primeiro remova o diretório VungleSDK.framework completamente antes de adicionar o novo SDK. Depois, localize os arquivos extraídos e arraste o diretório VungleSDK.framework para o Xcode em Frameworks. Certifique-se de que a pasta VungleSDK.framework foi adicionada como um grupo (pasta amarela), e não como uma referência (pasta azul).

Adicionar outros frameworks necessários

O Vungle SDK requer que você vincule alguns outros frameworks nativos ao seu projeto em Navegador do projeto e vá para Geral → Frameworks e bibliotecas vinculados. Muitos desses frameworks já estão inclusos, porque são padrão para a maioria dos projetos do Xcode, mas certifique-se de adicionar os que ainda não estão inclusos:

  • AdSupport.framework
  • AudioToolbox.framework
  • AVFoundation.framework
  • CFNetwork.framework
  • CoreGraphics.framework
  • CoreMedia.framework
  • Foundation.framework
  • libz.dylib ou libz.tbd
  • libsqlite3.dylib ou libsqlite3.tbd
  • MediaPlayer.framework
  • QuartzCore.framework
  • StoreKit.framework
  • SystemConfiguration.framework
  • UIKit.framework
  • WebKit.framework
    Nota: Defina o Status de WebKit.framework como 'Optional' se tiver iOS 7 como destino da implementação.

Certifique-se de que o framework VungleSDK apareça em Frameworks e bibliotecas vinculados.

Adicionar o flag de vinculação “-ObjC”

Clique no seu projeto em Navegador do projeto e vá para Configurações de build → Vinculação → Outras flags de vinculação . Adicione -ObjC em Outras flags de vinculação .

Etapa 2. Remover a barra de status do iOS

Embora esta etapa não seja necessária, recomendamos que você remova a barra de status do iOS para garantir que a interação e apresentação de anúncios do Vungle funcione perfeitamente. Para remover a barra de status, abra seu Info.plist, adicione a chave Aparência de barra de status de visualização baseada em controle e defina-a como Não.

Etapa 3. Adicionar código

Crie um arquivo Bridging Header

  1. Crie um novo arquivo Objective C em seu projeto (Arquivo Novo Arquivo [Arquivo Objective-C]).
  2. O Xcode vai perguntar se você deseja criar um arquivo Bridging Header entre o Objective C e o Swift. Aceite esta solicitação.
  3. Exclua o novo arquivo Objective-C (${YOURPROJ}-Bridging-Header.m), mas retenha o arquivo Bridging Header ${YOURPROJ}-Bridging-Header.h.
  4. No arquivo Bridging Header, importe o Vungle SDK adicionando o seguinte:
    #import <VungleSDK/VungleSDK.h> 

Inicializar o SDK

Inicialize o SDK assim que o seu aplicativo for iniciado. Se você estiver usando um posicionamento com cache automático, essa ação dá tempo suficiente ao SDK para colocar um anúncio em cache em tal posicionamento. Você precisará que o ID do aplicativo inicialize o SDK. O ID do aplicativo pode ser encontrado no painel do Vungle.

- (BOOL)startWithAppId:(nonnull NSString *)appID placements:(nonnull NSArray *)placements error:(NSError **)error;

Exemplo de código:

let appID = "Your_AppID_Here";
var placementIDsArray:Array<String> = ["<Your_PlacementID_1>", "<Your_PlacementID_2>", "<Your_PlacementID_3>"];

var sdk:VungleSDK = VungleSDK.shared()
do {
try sdk.start(withAppId: appID, placements: placementIDsArray)
}
catch let error as NSError {
print("Error while starting VungleSDK : \(error.domain)")
return;
}

Uma vez que o SDK tenha sido inicializado com sucesso, o seguinte método de callback é chamado:

- (void)vungleSDKDidInitialize;

Consulte a seção “Delegar callbacks” neste artigo.

Você também pode verificar o status da inicialização do SDK com a seguinte propriedade:

@property (atomic, readonly, getter=isInitialized) BOOL initialized;

Depois que o SDK é inicializado, se você tiver selecionado um posicionamento como Armazenado automaticamente em cache no painel do Vungle, o SDK armazenará um anúncio automaticamente em cache para esse posicionamento. Se você usar esse recurso, recomendamos selecionar o canal mais visualizado para o armazenamento automático em cache.

Assim que o anúncio é armazenado em cache, o método de callback vungleAdPlayabilityUpdate é chamado com o ID de referência de posicionamento correspondente ao seu posicionamento Armazenado automaticamente em cache. (Consulte a seção “Verificar a disponibilidade de anúncio para um posicionamento” deste artigo.)

Carregar um anúncio para um posicionamento

Para outros posicionamentos além do posicionamento armazenado automaticamente em cache, chame o método loadPlacementWithID para carregar um anúncio.

var sdk:VungleSDK = VungleSDK.shared()
do {
try sdk.loadPlacement(withID: <Your_PlacementID>)
}
catch let error as NSError {
print("Unable to load placement with reference ID :\(<Your_PlacementID>), Error: \(error)")

return
}

Consulte a seção “Verificar a disponibilidade de anúncio para um posicionamento” deste artigo.

Verifica a disponibilidade de anúncio para um posicionamento

Uma vez que o SDK finalize o armazenamento em cache de um anúncio para um posicionamento, o seguinte método de callback é chamado:

- (void)vungleAdPlayabilityUpdate:(BOOL)isAdPlayable placementID:(nullable NSString *)placementID; 

Exemplo de código:

func vungleAdPlayabilityUpdate(_ isAdPlayable: Bool, placementID: String?) {
if (placementID == <Your_PlacementID>) {
self.playButtonPlacement1.enabled = isAdPlayable;
}
}

Nota: para o posicionamento armazenado em cache automaticamente, este método de callback é chamado apenas quando um anúncio fica disponível. O SDK ficará solicitando um anúncio para o posicionamento armazenado em cache automaticamente. Para todos os outros posicionamentos, este método de callback é chamado em caso de “Falha de carregamento” (isAdPlayable retorna ‘NÃO’ neste caso). Você também pode verificar a disponibilidade de anúncio para um posicionamento com a seguinte propriedade:

- (BOOL)isAdCachedForPlacementID:(nonnull NSString *)placementID;

Reproduzir um anúncio

Depois que você tiver se certificar que um anúncio esteja pronto para um posicionamento, você pode reproduzir o anúncio com o seguinte método:

- (BOOL)playAd:(UIViewController *)controller options:(nullable NSDictionary *)options placementID:(nullable NSString *)placementID error:( NSError *__autoreleasing _Nullable *_Nullable)error;

Exemplo de código:

var sdk:VungleSDK = VungleSDK.shared()
do {
try sdk.playAd(self, options: nil, placementID: kVungleTestPlacementID01)
}
catch let error as NSError {
print("Error encountered playing ad: + \(error)");
}

Delegar callback

Você pode receber callbacks do SDK com VungleSDKDelegate. Existem quatro métodos de callback na delegação nos quais você recebe notificação em eventos do SDK.

Você pode anexar e desanexar sua delegação com:

var sdk:VungleSDK = VungleSDK.shared()
// Attach
sdk.delegate = <yourDelegateInstance> as VungleSDKDelegate
// Detach
sdk.delegate = nil

Nota: Para evitar vazamentos de memória, lembre-se de limpar a delegação registrada quando esta não é mais necessária.

O seguinte método é chamado quando o SDK está prestes a reproduzir um anúncio de vídeo. Isto é ideal para pausar jogos, efeitos sonoros, animações etc.

- (void)vungleWillShowAdForPlacementID:(nullable NSString *)placementID; 

O seguinte método é chamado quando o SDK está prestes a fechar um anúncio. Isso é ideal para recompensar seu usuário e retomar jogos, efeitos sonoros, animações, etc.

- (void)vungleWillCloseAdWithViewInfo:(VungleViewInfo *)info placementID:(NSString *)placementID;

O método a seguir é chamado após o SDK fechar um anúncio:

- func vungleDidCloseAd(with info: VungleViewInfo, placementID: String);

VungleViewInfo inclui as seguintes propriedades a verificar como resultado de uma reprodução de anúncio:

@interface VungleViewInfo : NSObject //Representa um BOOL independentemente de o vídeo poder ou não ser considerado uma visualização completa. @property (nonatomic, readonly) NSNumber *completedView; //O tempo em segundos que o usuário assistiu ao vídeo. @property (nonatomic, readonly) NSNumber *playTime; //Representa um BOOL independente de se o usuário clicou ou não o botão para baixar. @property (nonatomic, readonly) NSNumber *didDownload; @end 

O seguinte método é chamado quando o SDK alterou o status de disponibilidade do anúncio. O booliano isAdPlayable denota a nova habilidade de reproduzir um placementID específico.

- (void)vungleAdPlayabilityUpdate:(BOOL)isAdPlayable placementID:(NSString *)placementID;

Consulte a seção “Verificar a disponibilidade de anúncio para um posicionamento” deste artigo.

O seguinte método é chamado quando o SDK é inicializado com sucesso:

- (void)vungleSDKDidInitialize;

Opções de personalização

Use essas opções para personalizar a experiência de reprodução de anúncio.

Observação: Anúncios com recompensa são, às vezes, chamados de anúncios incentivados; ambos os termos sempre referem-se ao mesmo tipo de anúncio. No código do SDK e em nossa API de relatórios, usamos o termo "incentivado".

Chaves de opção

Valor/tipo padrão

Descrição

VunglePlayAdOptionKeyOrientations

autorotate

UIInterfaceOrientationMaskAll

Um NSString representando uma máscara de bit com orientações

Define a orientação do anúncio. Recomendamos que você permita que os anúncios girem automaticamente, mesmo se o aplicativo estiver em modo de retrato. Assim, o usuário terá a opção de assistir a vídeos em tela cheia, resultando em uma melhor experiência. Você pode obter isso definindo a orientação em um nível de controlador de visualização (em vez de um nível de projeto).

VunglePlayAdOptionKeyUser

nil

NSString

Defina seu ID de usuário. O valor é passado ao servidor Vungle e então enviado para o seu servidor através do sistema de callback servidor-a-servidor se um posicionamento é definido como “Com recompensa”.

VunglePlayAdOptionKeyIncentivizedAlertTitleText

nil

NSString

String usada como título da caixa de diálogo de alerta, apresentada quando um usuário fecha prematuramente um anúncio com incentivo.

VunglePlayAdOptionKeyIncentivizedAlertBodyText

“Deseja mesmo pular este anúncio? Se pular, pode não ganhar sua recompensa”

NSString

String usada como texto da caixa de diálogo de alerta, apresentada quando um usuário fecha prematuramente um anúncio com incentivo.

VunglePlayAdOptionKeyIncentivizedAlertCloseButtonText

“Fechar”

NSString

String de título para o texto do botão de fechar da caixa de diálogo de alerta, apresentada quando um usuário fecha prematuramente um anúncio com incentivo.

VunglePlayAdOptionKeyIncentivizedAlertContinueButtonText

“Continuar”

NSString

String de título para o texto do botão de fechar da caixa de diálogo de alerta, apresentada quando um usuário fecha prematuramente um anúncio com incentivo.

Exemplo de código:

let options: NSDictionary = NSDictionary(dictionary: [VunglePlayAdOptionKeyUser: "test_user_id",
VunglePlayAdOptionKeyIncentivizedAlertBodyText: "If the video isn't completed you won't get your reward! Are you sure you want to close early?",
VunglePlayAdOptionKeyIncentivizedAlertCloseButtonText: "Close",
VunglePlayAdOptionKeyIncentivizedAlertContinueButtonText: "Keep Watching",
VunglePlayAdOptionKeyIncentivizedAlertTitleText: "Careful!"])
do {
try self.sdk.playAd(self, options: (options as! [AnyHashable : Any]), placementID: PlacementID)
}
catch let error as NSError {
print("Error encountered playing ad: + \(error)");
}

Opção de silenciar

A instância do Vungle SDK oferece a opção de reproduzir anúncios com o sim desabilitado. Você pode definir a propriedade de silenciar como verdadeira antes de emitir um playAd().

Exemplo de código:

var sdk:VungleSDK = VungleSDK.shared()
sdk.muted = true

Nota: Esta opção aplica-se apenas ao tipo padrão de anúncio. A opção silenciado para anúncios de modelo dinâmico está disponível no painel para configuração.

Debug

Se você precisa de informações sobre o SDK, você pode obtê-las usando esta propriedade:

- (NSDictionary *)debugInfo;

Se você deseja que o SDK gere logs, use o seguinte método:

- (void)setLoggingEnabled:(BOOL)enable;

Protocolo VungleSDKLogger

@protocol VungleSDKLogger - (void)vungleSDKLog:(NSString*)message; @end

O singleton VungleSDK envia eventos de criação de log para qualquer classe anexa, seguindo o protocolo VungleSDKLogger. O evento de log contém o valor de NSString, que também é exibido no console (se a criação de logs estiver ativada). Para anexar o seu gerador de logs, use:

- (void)attachLogger:(id<VungleSDKLogger>)logger;

Como mencionado acima, é importante limpar os geradores de logs anexos do Vungle SDK. Os geradores de logs podem ser desanexados com:

- (void)detachLogger:(id<VungleSDKLogger>)logger;

Instruções de implementação recomendada pelo RGPD

Para usar as APIs da Vungle para atualizar ou consultar o status de consentimento do usuário (como recomendado na Opção 1 do RGPD: Implementação recomendada da Vungle), use as funções a seguir:

//This function returns the current consent status recorded in SDK. If status is not known return 0. sdk = VungleSDK.shared() sdk?.getCurrentConsentStatus() //This function sets the current consent status recorded in the SDK sdk = VungleSDK.shared() sdk?.update(status: VungleConsentStatus) 

VungleConsentStatus é uma enumeração contendo dois estados:

  • aceito (VungleConsentStatus.accepted)
  • rejeitado (VungleConsentStatus.denied)
Tem mais dúvidas? Envie uma solicitação

Comentários