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

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 para iOS v. 6 é compatível com iOS 8+.
  • O Vungle SDK para iOS v. 6 foi testado com iOS 11 beta/GM Seed.
  • O Vungle SDK para iOS v. 6 é compatível com aplicativos de 32 e 64 bits.
  • A integração requer que você tenha uma conta Vungle. Se ainda não tem uma conta, crie uma antes de continuar.
  • Nosso SDK do iOS é compatível com o Xcode 9.0 ou superior.

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.2.0"

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. Se estiver fazendo a atualização a partir de uma versão anterior do Vungle SDK, primeiro remova todo o diretório VungleSDK.framework antes de adicionar o novo SDK.

Localize os arquivos extraídos e arraste e solte o diretório VungleSDK.framework no Xcode em Frameworks. Certifique-se de adicionar a pasta VungleSDK.framework como um grupo (pasta amarela) e não como uma referência (pasta azul).

Adicione outros frameworks necessários

É obrigatório vincular alguns outros frameworks nativos ao seu projeto para usar o Vungle SDK. Para isso, clique no projeto em Project Navigator e acesse General → Linked Frameworks and Libraries.

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
  • libz.dylib or libz.tbd
  • MediaPlayer.framework
  • QuartzCore.framework
  • StoreKit.framework
  • SystemConfiguration.framework


Observação: O Vungle v.6 não é compatível com o iOS 7. Se o iOS 7 for o destino de implementação, use o Vungle iOS SDK v.4.1 ou inferior e inclua os seguintes frameworks:

  • UIKit.framework
  • WebKit.framework
  • Foundation.framework

Certifique-se de que o framework VungleSDK apareça em Linked Frameworks and Libraries.

Adicione a flag de vinculação “-ObjC”

Clique no seu projeto em Project Navigator e vá para Build Settings → Linking → Other Linker Flags. Adicione -ObjC em Other Linker Flags.

Etapa 2. Remover a barra de status do iOS

Embora esta etapa não seja necessário, 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 View controller-based status bar appearance e defina-a como No.

Etapa 3. Adicionar código

Inicialize o SDK

Inicialize o SDK assim que o seu aplicativo for iniciado. Se 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 error:(NSError **)error;

Exemplo de código:

#import <VungleSDK/VungleSDK.h>
...
NSError* error;
NSString* appID = @"Your_AppID_Here"; VungleSDK* sdk = [VungleSDK sharedSDK]; [sdk startWithAppId:appID error:&error];

Uma vez que o SDK tenha sido inicializado com êxito, 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 tiver selecionado um posicionamento como Auto Cached 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 Auto Cached. (Consulte a seção "Verificação de disponibilidade do anúncio em um posicionamento” neste 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.

- (BOOL)loadPlacementWithID:(NSString *)placementID error:(NSError **)error;

Exemplo de código:

NSError* error;
VungleSDK* sdk = [VungleSDK sharedSDK]; [sdk loadPlacementWithID:"<Your_PlacementID>" error:&error];

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

Verifica a disponibilidade do anúncio para um posicionamento

Depois que o SDK finalizar o armazenamento em cache do anúncio em um posicionamento, o seguinte método de callback é chamado:

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

Exemplo de código:

- (void)vungleAdPlayabilityUpdate:(BOOL)isAdPlayable placementID:(NSString *)placementID error:(nullable NSError *)error {
    if([placementID isEqualToString:@""]) {         self.playButtonPlacement1.enabled = isAdPlayable;     }
}

Observação: No caso de posicionamentos armazenados em cache automaticamente, este método de callback só é chamado quando um anúncio fica disponível. O SDK continuará solicitando um anúncio para o posicionamento com cache automático. Nos outros casos de posicionamento, este método de callback é chamado se houver "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:

VungleSDK* sdk = [VungleSDK sharedSDK]; NSError *error; [self.sdk playAd:self options:nil placementID:@"<Your_PlacementID_1>" error:&error]; if (error) { NSLog(@"Error encountered playing ad: %@", error); }

Anúncios Flex Feed

A compatibilidade com anúncios Flex Feed é oferecida desde o SDK v.5.3 do Vungle. Este é o primeiro formato de anúncio que não requer tela cheia. Em vez disso, o distribuidor determina as dimensões e a localização exatas do contêiner de anúncios dentro do aplicativo.

Carregamento de um anúncio Flex Feed

Carregar um anúncio Flex Feed é o mesmo que carregar um anúncio de tela cheia. Contudo, o local deve ser configurado para suportar Flex Feed. Contate seu gerente de conta da Vungle para ativar o Flex Feed para um local.

Exibição de um anúncio Flex Feed

Exibir anúncios Flex Feed é diferente de exibir anúncios de tela cheia. Com os anúncios Flex Feed, você deve primeiro criar um contêiner para o anúncio. Esse contêiner é um UIView. Você pode colocar UIView em qualquer lugar na tela. O anúncio será dimensionado para qualquer tamanho de contêiner, mas tenha em mente que uma resolução muito baixa tornará o anúncio menos visível. Você deve chamar a função addAdViewToView para associar o contêiner ao anúncio Flex Feed.

Visão geral da função:

/** * Pass in an UIView which acts as a container for the ad experience. This view container may be placed in random positions. * @param publisherView container view in which an ad will be displayed * @param options A reference to an instance of NSDictionary with customized ad playback options * @param placementID The placement defined on the Vungle dashboard * @param error An optional double reference to an NSError. In case this method returns `NO` it will be non-nil * @return YES/NO in case of success/error while presenting an AdUnit */ - (BOOL)addAdViewToView:(UIView *)publisherView withOptions:(nullable NSDictionary *)options placementID:(nullable NSString *)placementID error:( NSError *__autoreleasing _Nullable *_Nullable)error; 

Exemplo de código:

NSError *error; NSDictionary *options = @{}; VungleSDK* sdk = [VungleSDK sharedSDK]; [sdk addAdViewToView:_FlexFeedViewArea withOptions:options placementID: error:&error]; if (error) { NSLog(@"Error encountered while playing an ad: %@", error); } 

Fechamento de um anúncio Flex Feed

Devido à natureza dos anúncios do Flex Feed, um usuário pode parar de visualizar o vídeo sem fechar o anúncio. Assim, você deve informar o SDK para dispensar o anúncio quando ele não estiver mais na tela. Para isso, chame a função finishedDisplayingAd. Esta função só funciona com os anúncios Flex Feed e Flex View. Observe que esta função não ocorre em um posicionamento; ela simplesmente fecha qualquer anúncio nativo que esteja em reprodução no momento.

Visão geral da função:

/** * This method must be called when the publisher is confident that they are finished displaying the ad unit. * This signals to the SDK that a new ad may be fetched or a different ad may be displayed. This will * be called in conjunction with `addViewToView:containedInViewController:withOptions:placementID:error:` */ - (void)finishedDisplayingAd; 

Exemplo de código:

//Ad is no longer on screen VungleSDK* sdk = [VungleSDK sharedSDK]; [sdk finishedDisplayingAd]; 

Delegação de callbacks

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:

// Attach [[VungleSDK sharedSDK] setDelegate:yourDelegateInstance]; // Detach [[VungleSDK sharedSDK] setDelegate: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:

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

VungleViewInfo inclui as seguintes propriedades a serem verificadas como resultado da reprodução do anúncio:

@interface VungleViewInfo : NSObject //Represents a BOOL whether or not the video can be considered a completed view. @property (nonatomic, readonly) NSNumber *completedView; //The time in seconds that the user watched the video. @property (nonatomic, readonly) NSNumber *playTime; //Represents a BOOL whether or not the user clicked the download button. @property (nonatomic, readonly) NSNumber *didDownload; @end 

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

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

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 NSNumber representando um bitmask 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 incentivado.

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 incentivado.

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 incentivado.

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 incentivado.

VunglePlayAdOptionKeyFlexViewAutoDismissSeconds

Int

Use esta opção para fazer com que os anúncios Flex Feed sejam desativados automaticamente após um determinado número de segundos.
Esta função só funciona com anúncios Flex View.

VunglePlayAdOptionKeyOrdinal

Int

Se você receber relatórios de dados ordinais do Vungle, use este campo para passar na mediação ordinal. Este é um número inteiro que indica a ordem em que este anúncio foi exibido na sessão do jogo (por exemplo, se dois anúncios já foram exibidos nesta sessão e este anúncio da Vungle foi exibido em terceiro lugar, aparece o número 3). Leia mais sobre dados ordinais aqui.


NSDictionary *options = @{VunglePlayAdOptionKeyOrientations: @(UIInterfaceOrientationMaskLandscape), VunglePlayAdOptionKeyUser: @"userGameID", 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!"}; // Pass in dict of options, play ad NSError *error; [self.sdk playAd:self options:options placementID: error:&error]; if (error) { NSLog(@"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 som desabilitado. Você pode definir a propriedade de silenciar como verdadeira antes de emitir um playAd().

Exemplo de código:

VungleSDK* sdk = [VungleSDK sharedSDK]; self.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.

Instruções para a implementação recomendada do 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 sets the consent status that will be recorded in Vungle SDK. Accepted values: 'VungleConsentAccepted' or 'VungleConsentDenied'.
// To set the user's consent status to opted in:
[[VungleSDK sharedSDK] updateConsentStatus:VungleConsentAccepted];

// To set the user's consent status to opted out:
[[VungleSDK sharedSDK] updateConsentStatus:VungleConsentDenied];

// To find out what the user's current consent status is:
// (Check against enum values: 'VungleConsentAccepted' or 'VungleConsentDenied'.) [[VungleSDK sharedSDK] getCurrentConsentStatus];

VungleConsentStatus é uma enumeração contendo dois estados:

  • VungleConsentAccepted
  • VungleConsentDenied

O SDK também tem um estado inicial 'desconhecido', que solicita o usuário a ativar ou desativar sua coleta de dados. Observe que esse prompt ocorre apenas em endereços IP originários da Europa.

Debug

Se precisar de informações do SDK, você pode obtê-las com esta propriedade:

- (NSDictionary *)debugInfo;

Se quiser que o SDK gere logs de saída, 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:

[sdk attachLogger:yourLoggerInstance];

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

[sdk detachLogger:yourLoggerInstance];

Protocolo assetLoader

@protocol VungleAssetLoader /** * deverá retornar um NSData válido, contendo os dados (brutos) de uma imagem para o caminho especificado ou nil. */ - (NSData*)vungleLoadAsset:(NSString*)path; /** * deverá retornar um UIImage válido para o caminho especificado ou nil. */ - (UIImage*)vungleLoadImage:(NSString*)path; @end
Tem mais dúvidas? Envie uma solicitação

Comentários