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

Utilize este guia para integrar rapidamente seu SDK ao aplicativo e começar a monetizar.

Os exemplos de código neste guia estão em C#, mas fornecemos arquivos de aplicativo de amostra em C#, C++, Visual Basic e DirectX+XAML de nosso repositório GitHub.

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

  • Este é o guia para o Vungle Windows SDK 5.3.2 e superior. O guia de integração para o Vungle Windows SDK versão 1.3.16 ou inferior está aqui: Introdução ao Vungle -SDK v.1.0 - v.1.3.16 para Windows.
  • A integração exige uma conta Vungle, portanto, crie uma conta Vungle se não tiver uma.
  • Se ainda não o fez, abra nosso painel e adicione seu aplicativo à sua conta. Veja Configuração e relatório sobre posicionamentos para saber como configurar posicionamentos no painel Vungle.
  • É necessário usar o Visual Studio 2015 para desenvolver para Windows 8.1 e Windows Phone 8.1 porque o Visual Studio 2017 não suporta mais essas versões.
  • O botão Back é suportado em dispositivos móveis, mas não em PCs (teclado). Isso pode provocar um comportamento e experiência do usuário diferentes, para compilações de UWP.
  • Alterne seu aplicativo para o modo Ativo se não forem retornados anúncios no modo de Teste.

Baixe o SDK e adicione o VungleSDK a seu projeto

Existem duas maneiras de adicionar o Vungle ao projeto Visual Studio: usando o NuGet ou por integração manual.

Opção 1. Integração NuGet

  1. No Visual Studio, clique com o botão direito do mouse em Project e selecione Manage NuGet Packages.
  2. Clique em Browse, digite 'Vungle', selecione Vungle SDK e clique em Install.

Opção 2. Integração manual

  1. Baixe o Vungle Windows SDK do painel Vungle.
  2. Extraia o arquivo.
  3. No Visual Studio, crie um novo projeto usando o modelo correto para seu aplicativo e linguagem de programação.
  4. Adicione uma referência para o seu projeto ao arquivo Vungle SDK para que você baixou.

O Vungle SDK tem dois arquivos VungleSDK.windmd para desenvolvimento em Windows 10 ou 8.1. Use o SDK correto do diretório extraído, Win10 ou Win81.

Recurso internetClient

Certifique-se de que seu projeto tem o recurso internetClient no arquivo package.appxmanifest.

Visual Studio

  1. Clique duas vezes em appxmanifest , em Solution Explorer.
  2. Selecione Capabilities
  3. Confirme se a opção Internet (Client) está marcada.

Edição manual

Abra o arquivo package.appxmanifeset e adicione internetClient à seção Capabilities.

<Capabilities>
...
<Capability Name="internetClient" />
...
</Capabilities>

Importação do VungleSDK Namespace

using VungleSDK;

Obter uma instância do VungleAd

A instância do VungleAd tem dois parâmetros: uma string para o ID do aplicativo Vungle e um array de strings para IDs de posicionamento. Só é possível utilizar IDs de posicionamento que você já incluiu quando for obter a instância. Se não incluir um posicionamento armazenado em cache automaticamente, o SDK atribuirá automaticamente um de seus posicionamentos não armazenados em cache automaticamente para serem armazenados automaticamente.

VungleAd sdkInstance; string appID = “app_id”; string[] placementArray = new string[] { “placement_id_1”, “placement_id_2”, “placement_id_3” };
sdkInstance = AdFactory.GetInstance(appID, placementArray);

No exemplo acima, substitua o app_id pelo ID do seu aplicativo Vungle e placement_id_# pelos IDs de posicionamento que serão utilizados em seu projeto. Recomendamos que você siga essas etapas de inicialização logo que seu aplicativo terminar de carregar os componentes críticos, para que o armazenamento automático em cache possa começar mais cedo.

Criar e registrar um gerenciador de eventos

Criar um gerenciador de eventos para o evento OnAdPlayableChanged. Esse gerenciador de eventos é chamado quando o estado da disponibilidade do anúncio muda. Para identificar qual posicionamento acionou o evento, verifique e.Placement.

// Event handler for OnAdPlayableChanged event private async void SdkInstance_OnAdPlayableChanged(object sender, AdPlayableEventArgs e) { // e.Placement - placement ID in string // Run asynchronously on the UI thread await CoreApplication.MainView.Dispatcher.RunAsync(CoreDispatcherPriority.Normal, new DispatchedHandler(() => methodToRun(e.Placement))); } 

Registrar esse gerenciador de eventos para o evento OnAdPlayableChanged.

sdkInstance.OnAdPlayableChanged += SdkInstance_OnAdPlayableChanged; 

Carregar um anúncio para um posicionamento

Para posicionamentos não armazenados em cache automaticamente, primeiro você deve chamar LoadAd, aguardar baixar os ativos do anúncio e esperar OnAdPlayableChanged ser chamado:

sdkInstance.LoadAd(“placement_id”); 

Nota: O posicionamento armazenado em cache automaticamente tentará baixar um novo ativo de anúncio logo após PlayAdAsync ser chamado, então não é necessário chamar LoadAd.

Exemplo de código:

private void OnLevelStart(Object sender, RoutedEventArgs e) { sdkInstance.LoadAd(“placement_id”); } 

Reproduzir um anúncio

Execute um anúncio com a configuração padrão:

sdkInstance.PlayAdAsync(new AdConfig(), “placement_id”); 

Exemplo de código:

private async void OnLevelComplete(Object sender, RoutedEventArgs e) { await sdkInstance.PlayAdAsync(new AdConfig(), “placement_id”); } 

É possível personalizar os anúncios reproduzidos fornecendo opções ao objeto AdConfig.

Exemplo de código:

private async void PlayCustomizedAd(Object sender, RoutedEventArgs e) { AdConfig adConfig = new AdConfig(); adConfig.Orientation = DisplayOrientations.Portrait; adConfig.SoundEnabled = false; await sdkInstance.PlayAdAsync(adConfig, placement2); } 

Opções de personalização

Estas são as propriedades disponíveis na instância do objeto AdConfig:

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

Opções

Valor padrão/
tipo

Descrição

Orientation

AutoRotate

DisplayOrientations

Orientation.AutoRotate (padrão) faz o anúncio acompanhar a orientação do dispositivo.

Orientation.Portrait faz o anúncio ser reproduzido apenas na orientação retrato.

Orientation.Landscape faz o anúncio ser reproduzido apenas na orientação paisagem.

Nota: esta opção aplica-se apenas a aplicativos para dispositivos móveis.

SoundEnabled

true

bool

Define o estado inicial do som do anúncio.

Se definida como true (padrão), o áudio terá o volume e as configurações de som do dispositivo.

Se definida como false, o vídeo começará mudo, mas o usuário poderá modificar essa opção.

BackButtonImmediatelyEnabled

false

bool

Se definida como true, permite que o usuário saia imediatamente do anúncio por meio do botão Voltar.

Se definida como false (padrão), o usuário não poderá usar o botão Voltar para sair do anúncio até o botão Fechar ser exibido na tela.

Nota: esta opção aplica-se apenas a aplicativos para dispositivos móveis.

UserId

null

string

Envia o ID de usuário exclusivo para seu aplicativo, que verifica se esse usuário deverá ser gratificado por assistir um anúncio com incentivo ao usar o callback servidor-a-servidor para verificação.

Nota: essa configuração aplica-se apenas a posicionamentos com recompensa.

IncentivizedDialogTitle

“Fechar esse anúncio?”

string

Define o título da caixa de diálogo de confirmação ao sair de um anúncio incentivado.

Nota: essa configuração aplica-se apenas a posicionamentos com recompensa.

IncentivizedDialogBody

“Deseja mesmo pular este anúncio? Para pedir sua recompensa é necessário assistir até o final.”

string

Define o corpo da caixa de diálogo de confirmação ao sair de um anúncio incentivado.

Nota: essa configuração aplica-se apenas a posicionamentos com recompensa.

IncentivizedDialogCloseButton

"Fechar"

 

string

Define o texto do botão 'Cancelar' na caixa de diálogo de confirmação, quando se pula um anúncio com incentivo.

Nota: essa configuração aplica-se apenas a posicionamentos com recompensa.

IncentivizedDialogContinueButton

"Continuar"

string

Define o texto do botão 'Continuar assistindo' na caixa de diálogo de confirmação, quando se pula um anúncio com incentivo.

Nota: essa configuração não é aplicável se um anúncio não for incentivado.

Incentivized

-

OBSOLETO

É possível definir a configuração da recompensa no nível do posicionamento, a partir do painel. Consulte Configuração e relatório de posicionamentos.


Observação:
are As opções de SoundEnabled e as caixas de diálogo incentivadas em anúncios Modelo dinâmico e Flex View estão disponíveis no painel para configuração. A configuração programática será aplicada apenas em anúncios do legado.

Como exibir o botão Fechar

Para determinar se o usuário tem a opção de fechar um anúncio, utilize as opções de visualização forçada nas configurações avançadas do seu aplicativo no Painel de controle do Vungle.

Instruções para a implementação recomendada do RGPD

// To set the user’s consent status as opted in: sdkInstance.UpdateConsentStatus(VungleConsentStatus.VungleConsentAccepted); // To set the user’s consent status as opted out: sdkInstance.UpdateConsentStatus(VungleConsentStatus.VungleConsentDenied); // To find out what the user’s current consent status is: // This will return null if the GDPR Consent status has not been set // Otherwise, it will return VungleConsentStatus.VungleConsentAccepted or // VungleConsentStatus.VungleConsentDenied UpdateConsentStatus? currentStatus = sdkInstance.GetCurrentConsentStatus(); 

Inscrição para gerenciadores de evento

O Windows SDK abre diversos eventos que você pode programar. É possível utilizar esses gerenciadores de eventos para controlar recursos do aplicativo, como pausa/retomar a música de fundo.

Observação sobre threads de IU

Os ouvintes de evento são executados em um thread de fundo, portanto, qualquer interação IU ou atualizações decorrentes de um ouvinte de evento devem ser passadas para o segmento principal da IU antes de executar. Aqui está uma maneira de fazer isso:

await this.Dispatcher.RunAsync(CoreDispatcherPriority.Normal,
new DispatchedHandler(() =>
{ // This block will be executed in the UI thread
} );

Gerenciadores de evento do VungleAd

Gerenciadores de evento

Descrição

OnInitCompleted

Chamado logo após a inicialização do SDK ser concluída. É possível verificar se há um anúncio baixado de uma sessão anterior ou carregar um anúncio para posicionamentos.

OnAdPlayableChanged

Notifica da mudança da disponibilidade de anúncio para o posicionamento. Aguarda esse gerenciador de eventos agir quando um anúncio fica disponível após carregar um anúncio para posicionamento.

OnAdStart

Chamado antes de reproduzir um anúncio. É possível realizar ações como pausa da música de fundo.

OnAdEnd

Chamado quando o usuário fecha o cartão final e o controle volta para o seu aplicativo. Se IsCompletedView ou CallToActionClicked for true, o usuário assistiu o anúncio ou clicou no botão download no anúncio. Nesse caso, se for um anúncio com recompensa, o usuário deve ser recompensado. É possível realizar ações como retomar os recursos do aplicativo.

Diagnostic

Chamado quando o SDK quer imprimir logs de diagnóstico.

Exemplo de código:

//Register event handlers sdkInstance.OnInitCompleted += SdkInstance_OnInitCompleted; sdkInstance.OnAdPlayableChanged += SdkInstance_OnAdPlayableChanged; sdkInstance.OnAdStart += SdkInstance_OnAdStart; sdkInstance.OnAdEnd += SdkInstance_OnAdEnd; sdkInstance.Diagnostic += SdkInstance_Diagnostic; ... // OnInitCompleted // e.Initialized - true if initialization succeeded, false if failed // e.ErrorMessage - reason for failure when e.Initialized is false private async void SdkInstance_OnInitCompleted(object sender, ConfigEventArgs e) { var placementsInfo = "OnInitCompleted: " + e.Initialized; // Initilization was success if (e.Initialized == true) { // Print out list of placements for (var i = 0; i < e.Placements.Length; i++) { placementsInfo += "\n\tPlacement" + (i + 1) + ": " + e.Placements[i].ReferenceId; if (e.Placements[i].IsAutoCached == true) placementsInfo += " (Auto-Cached)"; } } // Initilization failed else { placementsInfo += "\n\t" + e.ErrorMessage; } System.Diagnostics.Debug.WriteLine(placementsInfo); await this.Dispatcher.RunAsync(CoreDispatcherPriority.Normal, new DispatchedHandler(() => NotifyInitialization(e.Initialized))); } // OnAdPlayableAdPlayable // e.AdPlayable - true if an ad is available to play, false otherwise // e.Placement - placement ID in string private async void SdkInstance_OnAdPlayableChanged(object sender, AdPlayableEventArgs e) { System.Diagnostics.Debug.WriteLine("OnAdPlayable(" + e.Placement + ") - " + e.AdPlayable); await this.Dispatcher.RunAsync(CoreDispatcherPriority.Normal, new DispatchedHandler(() => NotifyWatcher(e.AdPlayable, e.Placement))); } // OnAdStart // e.Id - Vungle app ID in string // e.Placement - placement ID in string private void SdkInstance_OnAdStart(object sender, AdEventArgs e) { System.Diagnostics.Debug.WriteLine("OnAdStart(" + e.Id + "): " + e.Placement); } // OnAdEnd // e.Id - Vungle app ID in string // e.Placement - placement ID in string // e.IsCompletedView- true when 80% or more of the video was watched // e.CallToActionClicked - true when the user has clicked download button on end card // e.WatchedDuration - DEPRECATED private void SdkInstance_OnAdEnd(object sender, AdEndEventArgs e) { System.Diagnostics.Debug.WriteLine("OnVideoEnd(" + e.Id + "): " + "\n\tPlacement: " + e.Placement + "\n\tIsCompletedView: " + e.IsCompletedView + "\n\tCallToActionClicked: " + e.CallToActionClicked + "\n\tWatchedDuration: " + e.WatchedDuration); } // Event handler called when SDK wants to print diagnostic logs private void SdkInstance_Diagnostic(object sender, DiagnosticLogEvent e) { System.Diagnostics.Debug.WriteLine("Diagnostic - "
+ e.Level + " "
+ e.Type + " "
+ e.Exception + " "
+ e.Message); } // DEPRECATED - Use SdkInstance_OnAdEnd() instead private void SdkInstance_OnVideoView(object sender, AdViewEventArgs e) { }

Reproduzindo Anúncios do Native Flex

O Vungle Windows SDK 5.1.0 ou posterior suporta o nosso novo recurso de anúncio Native Flex. VungleAdControl alcança anúncios de vídeo em formatos nativos passando um contêiner personalizado para o Vungle SDK através da propriedade AdConfig.AdContainer e gerenciando o conteúdo de Container.Content do aplicativo host.

Requisitos para Anúncios do Native Flex

  • Windows SDK 5.1.0 ou posterior
  • Windows 10 UWP

Consulte o gerente da sua conta ou entre em contato com tech-support@vungle.com para configurar posicionamentos de Anúncios do Native Flex.

Configuração de IU para Anúncios do Native Flex - XAML

VungleAdControl deve ser declarado com a ID do aplicativo Vungle, todas as IDs de posicionamento usadas no aplicativo e a ID de posicionamento para a exibição particular do Anúncio do Native Flex ou o posicionamento de feed. Você também pode definir a UserId que é usada para posicionamentos recompensados aqui.

Exemplo de código:

<Grid
<UI:VungleAdControl x:Name="vungleEmbedded"
Height="200"
Width="300"
AppID="vungle_app_id"
Placements="placement_id_1,placement_id_2,native_flex_id"
Placement = "native_flex_id"
UserId="vungle_test_user">
<TextBlock x:Name="Vungle Native Flex Ad"/>
</UI:VungleAdControl>
</Grid>

Carregar um Anúncio do Native Flex

Carregar um anúncio usando o posicionamento do Native Flex é semelhante a carregar um anúncio em tela cheia.

Exemplo de código:

sdkInstance.LoadAd(“native_flex_id”); 

Reproduzir um Anúncio do Native Flex

A reprodução de um anúncio com o posicionamento do Native Flex é semelhante à reprodução de anúncios em tela cheia, mas qualquer personalização deve ser configurada no .xaml ou no Painel, inclusive iniciar o anúncio com o som desativado.

Exemplo de código:

await vungleEmbedded.PlayAdAsync();

Como fechar um anúncio do Native Flex

Devido à natureza dos anúncios do Native Flex, 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, introduzimos dois métodos para fechar anúncios Native Flex:

  • Use CloseFlexViewAd(String placementId) para fechar imediatamente o anúncio com o ID de posicionamento fornecido.

  • Use SetFlexViewCloseTimeInSec(String placementId, int seconds) para fechar o posicionamento após determinado número de segundos.

Gerenciador de Eventos para Anúncios do Native Flex

Considere registrar gerenciadores de eventos separados para gerenciar os diferentes comportamentos de anúncios em tela cheia e nativos, para uma experiência de usuário mais agradável.

Exemplo de código:

vungleEmbedded.OnAdStart += (sender, arg) => { ... } vungleEmbedded.OnAdEnd += (sender, arg) => { ... } await vungleEmbedded.PlayAdAsync(); 
Tem mais dúvidas? Envie uma solicitação

Comentários