Introdução ao Vungle (SDK v.1.0 - v.4.1) - Adobe Air

Este guia mostra como integrar nosso Vungle Adobe Air Plugin em um aplicativo básico de exemplo. O código-fonte mencionado aqui está disponível em nosso repositório GitHub público.

Conteúdo

Antes de começar
1. Incluir a biblioteca de extensão
2. Atualizar seu descritor do aplicativo
3. Integrar a API Vungle
Diagnóstico e perguntas frequentes

Antes de começar

  • A extensão Vungle exige o SDK Adobe AIR 4.0 ou superior. Para obter instruções sobre como atualizar o SDK AIR no Flash Builder ou Flash Professional, consulte "Como posso atualizar o SDK AIR?" no final deste guia.

  • Se você está trabalhando com Android, a extensão Vungle AIR requer JDK 6 ou JDK 7 (dependendo da versão de Flash que você está usando) a ser instalado no sistema de desenvolvimento. Android 3.0 (Honeycomb - API versão 11) ou superior é necessário para executar o aplicativo.

  • Você pode visualizar a ActionScript Documentação da classe 3.

  • Revise example/VungleExample.as para ver um exemplo de classe do aplicativo. (Se você for usuário do Flash Professional e não tiver certeza de como usar uma Classe de documentos, consulte "Como posso usar a classe de documentos VungleExample em Flash CS6?" no final deste guide.)

1. Incluir a biblioteca de extensão

Comece criando um novo AIR para projetos de dispositivos móveis e adicionando a extensão nativa.

Para Android: você pode também precisar adicionar a biblioteca Google Play Services ao seu projeto. Como muitas outras extensões já incluem essa biblioteca, você talvez não precise adicioná-la. Para adicionar a extensão, repita os passos abaixo, mas use com.vungle.extensions.android.GooglePlayServices.ane em vez de com.vungle.extensions.Vungle.ane.

Em Flash Professional CS6 ou superior:

  1. Crie um novo projeto AIR para Android ou AIR para iOS.
  2. Escolha Arquivo > Publicar Settings...
  3. Selecione o ícone de engrenagem ao lado de Script para 'Configurações ActionScript'.
  4. Na guia Caminho da biblioteca, clique em Procurar arquivo de extensão nativo (ANE) e selecione o arquivo com.vungle.extensions.Vungle.ane. Clique em OK.
  5. Selecione o ícone de engrenagem ao lado de Destino para 'Configurações de reprodutor'.
  6. Para Android: na guia Permissões, habilite 'INTERNET', 'WRITE_EXTERNAL_STORAGE' e 'ACCESS_NETWORK_STATE'.
  7. Selecione a opção Gerenciar manualmente permissões e adições de manifesto deste aplicativo e clique em OK.

Em Flash Builder 4.6 ou superior:

  1. Em Propriedades do projeto, em Caminho do build Actionscript, selecione Extensões nativas. 
  2. Escolha Adicionar ANE... e navegue até o arquivo com.vungle.extensions.Vungle.ane.
  3. Selecione Pacote de build Actionscript > Google Android.
  4. Na guia Extensões nativas, selecione a opção Pacote ao lado da extensão.
  5. Para iOS, repita as etapas 3 e 4 para o destino 'Apple iOS'.

2. Atualizar seu descritor do aplicativo

Para que o Vungle funcione, modificações são necessárias no arquivo XML do seu aplicativo. Modifique o arquivo XML criado pelo seu IDE com as seguintes modificações (se você for usuário do Flash Professional, lembre-se de seguir as etapas acima para 'Incluir a biblioteca no Flash Professional CS6 ou superior'; caso contrário, o Flash pode desfazer suas alterações à medida que você as faz):

  1. Defina o SDK AIR como 4.0 (ou superior) no arquivo do descritor do aplicativo:
    <application xmlns="http://ns.adobe.com/air/application/4.0">
  2. Inclua um link para a extensão no descritor:
    <extensions>
    <extensionID>com.vungle.extensions.Vungle</extensionID>
    </extensions>
  3. Para Android: você talvez precise incluir a extensão Google Play Services. Adicione seu ID de extensão aqui também.
    <extensions>
    <extensionID>com.vungle.extensions.Vungle</extensionID>
    <extensionID>com.vungle.extensions.android.GooglePlayServices</extensionID>
    </extensions>

Para aplicativos AIR para Android

Para Android, atualize suas adições de manifesto Android no elemento XML Android para:

  • incluir as permissões INTERNET, WRITE_EXTERNAL_STORAGE e ACCESS_NETWORK_STATE
  • adicionar VideoFullScreenAdActivity e as definições de atividade MraidFullScreenAdActivity 
  • adicionar a tag de metadados da versão google-play-services:
<android> 
<manifestAdditions><![CDATA[
<manifest android:installLocation="auto">

 <uses-permission android:name="android.permission.INTERNET"/>
 <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
 <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

 <application>
   <meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version"/>

   <activity android:name="com.vungle.publisher.VideoFullScreenAdActivity"
     android:configChanges="keyboardHidden|orientation|screenSize"
     android:theme="@android:style/Theme.NoTitleBar.Fullscreen"/>
   <activity android:name="com.vungle.publisher.MraidFullScreenAdActivity"
     android:configChanges="keyboardHidden|orientation|screenSize"
     android:theme="@android:style/Theme.Translucent.NoTitleBar.Fullscreen"/>
 </application>
</manifest>
]]></manifestAdditions>
</android>

Para aplicativos AIR para iOS

Para iOS, recomendamos desabilitar App Transport Security (ATS) adicionando as seguintes linhas ao XML do descritor do aplicativo ao fazer o build com Adobe AIR 21+:

<iPhone>
    <InfoAdditions>
        <![CDATA[
            <key>NSAppTransportSecurity</key>
            <dict>
                <key>NSAllowsArbitraryLoads</key>
                <true />
            </dict>
        ]]>
    </InfoAdditions>
</iPhone>

Consulte Preparação dos seus aplicativos para iOS 9 para mais informações sobre segurança de transporte de aplicativo.

3. Integrar a API Vungle

A API Vungle pode ser adicionada ao seu aplicativo em apenas algumas linhas do ActionScript.

Inicialize a extensão Vungle

Inicialize a API quando o aplicativo iniciar.

  • Se usar ActionScript puro, faça o seguinte no construtor da sua classe de documento.
  • Se usar Flex, chame isso no evento initialize() da classe principal.
  • Se usar código de linha do tempo no Flash, faça isso no Quadro 1.
  1. Importe as classes da API:
    import com.vungle.extensions.*; 
    import com.vungle.extensions.events.*;
  2. Inicialize a API chamando Vungle.create() e passando na array que contém seu ID de aplicativo a partir do painel Vungle. Se você estiver usando iOS e Android no mesmo projeto, inclua os dois IDs na array - com o ID iOS primeiro e o ID Android em segundo.

    Você deve empacotar sua chamada para Vungle.create() em um try/catch uma vez que o Vungle pode emitir um erro durante o processo de criação (por exemplo, a extensão emite um erro se executado a partir do desktop):
    try
    {
     // inicialize com seu id do aplicativo
     Vungle.create(["seu_id_vungle"]);

     // -OU- inicialize incluindo os ids de ios e android para aplicativos multiplataforma
     // Vungle.create(["your_ios_vungle_id","your_android_vungle_id"]);
    } catch (error:Erro) {
     // falha ao criar a extensão. Você está executando em algo que não seja iOS/Android?
    }

Exibe um anúncio intersticial

Para exibir um anúncio intersticial, chame playAd(). É recomendável confirmar que o anúncio está disponível usando o método isAdAvailable():

if (Vungle.vungle.isAdAvailable())
{
    Vungle.vungle.playAd();
}

Exibe um anúncio de incentivo

Para exibir um anúncio de incentivo, chame playAd() com um objeto de configuração e defina a opção incentivo como verdadeira. É recomendável confirmar que o anúncio está disponível usando o método isAdAvailable().

if (Vungle.vungle.isAdAvailable())
{
   var config:VungleAdConfig = new VungleAdConfig();
   config.incentivized = true;
   Vungle.vungle.playAd(config);
}

Para recompensar o usuário por completar uma visualização com incentivo, é recomendável implementar o listener de evento AD_FINISHED como descrito abaixo.

Adicionar listeners de evento

A extensão Vungle emite quatro eventos: VungleEvent.AD_PLAYABLE, VungleEvent.AD_STARTED, VungleEvent.AD_FINISHED, e VungleEvent.AD_LOG.

  1. O AD_PLAYABLE é emitido quando um anúncio está pronto para ser reproduzido
    Vungle.vungle.addEventListener(VungleEvent.AD_PLAYABLE, onAdPlayable);

    function onAdPlayable(e:VungleEvent):void
    {
       trace("ad playable");
    }
  2. Os eventos AD_STARTED e AD_FINISHED são emitidos quando um anúncio é exibido e descartado, respectivamente:
    Vungle.vungle.addEventListener(VungleEvent.AD_STARTED, onAdStarted); 
    Vungle.vungle.addEventListener(VungleEvent.AD_FINISHED, onAdFinished);

    function onAdStarted(e:VungleEvent):void
    {
     trace("ad displayed");
    }

    function onAdFinished(e:VungleEvent):void
    {
     trace("ad dismissed, CTA = " + e.wasCallToActionClicked);
     if (e.wasSuccessfulView)
     {
       trace("counts a completed view - present reward.");
     }
    }
  3. O AD_LOG é emitido quando uma mensagem de log é enviada pelo SDK Vungle. Você pode usá-la para depuração. O log é implementado somente no SDK Vungle para iOS, de modo que este evento é específico por plataforma.
    
    Vungle.vungle.setLoggingEnabled(true);
    Vungle.vungle.addEventListener(VungleEvent.AD_LOG, onAdLog);

    private function onAdLog(e:VungleEvent):void
    {
       log("ad log: " + e.message);
    }

Mais opções

Como você já viu antes, é possível passar um objeto com as opções de configuração ao chamar o método playAd(). Estas são as propriedades disponíveis em VungleAdConfig:

orientação

Com esta propriedade, você pode especificar a orientação do anúncio. Há diferentes conjuntos de sinalizadores para Android e iOS. Consulte a classe VungleOrientation para obter detalhes. Os sinalizadores podem ser combinados com um operador OU:

config.orientação = VungleOrientation.ANDROID_AUTOROTATE | VungleOrientation.IOS_PORTRAIT;

soundEnabled

Você pode usar essa propriedade para definir se os anúncios reproduzem som ou se são silenciados.

backButtonImmediatelyEnabled

Essa opção é específica do Android. Se definida como true, permite que o usuário saia imediatamente do anúncio por meio do botão Voltar. Se definida como false, o usuário não poderá usar o botão Voltar para sair do anúncio enquanto o botão Fechar for exibido na tela.

immersiveMode

Essa opção é específica do Android. Ativa ou desativa o modo imersivo em + dispositivos KitKat+.

incentivo

Define o modo com incentivo. Se verdadeiro, aparece uma caixa de diálogo de confirmação quando o usuário tentar pular o anúncio.

incentivizedUserId

O ID de usuário exclusivo, que será transmitido a seu aplicativo, para verificar se esse usuário deve ser premiado por assistir a um anúncio com incentivo.

incentivizedCancelDialogTitle, incentivizedCancelDialogBodyText, incentivizedCancelDialogCloseButtonText, incentivizedCancelDialogKeepWatchingButtonText

Essas opções lhe permitem personalizar a caixa de diálogo de confirmação que aparece ao pular um anúncio com incentivo.

extra1 … extra8

EM BREVE - Você pode usar isto para acompanhamento de métricas tais como grupo etário, sexo, etc.

posicionamento

EM BREVE - Um nome opcional de posicionamento de anúncio para categorização de dados aprimorada ao solicitar dados através da API de relatório Vungle.

largeButtons

Essa opção é específica do iOS. Se definido como verdadeiro, os botões na tela que são exibidos durante o vídeo ficam maiores.

Padrões globais

Você pode usar o objeto de configuração global para definir valores padrão para estas opções:


// defina qualquer configuração desejada
VungleAdConfig.globalConfig.orientação = VungleOrientation.ANDROID_MATCH_VIDEO;
VungleAdConfig.globalConfig.soundEnabled = falso;

Depois, cada novo objeto VungleAdConfig é criado com esses valores definidos por padrão. playAd() sem opções sempre usa a configuração global.

Métodos obsoletos

Desde a versão v2.4.0, os seguintes métodos ficaram obsoletos:


Vungle.vungle.displayAd(showCloseButton:Boolean, orientationHint:int):void;
Vungle.vungle.displayIncentivizedAd(name:String, showCloseButton:Boolean, orientationHint:int):void;
Vungle.vungle.setSoundEnabled(enabled:Boolean):void;
Vungle.vungle.setBackButtonEnabled(backEnabled:Boolean):void;
Vungle.vungle.setIncentivizedBackButtonEnabled(backEnabled:Boolean):void;

Esses métodos foram mantidos para manter a compatibilidade com versões anteriores. Não é recomendável usá-los em novos aplicativos ou misturá-los com a chamada do método playAd().

NOTA: Com seu aplicativo em modo Test, não é possível baixar nenhum dos apps anunciados. Além disso, o Painel de Controle não informará o número de impressões. Isso acontece porque os anúncios de texto são usados somente para verificar se você integrou o SDK corretamente. Esta funcionalidade se torna disponível assim que seu aplicativo seja publicado no modo ativo.

Diagnóstico de problemas e perguntas frequentes

“Como uso a VungleExample.as Classe de documento no Flash Professional CS6?”

  1. Primeiro, crie o aplicativo e adicione a extensão seguindo este guia, das Seções 1 a 3.
  2. Copie e cole VungleExample.as na mesma pasta do seu .fla. Não copie e cole o conteúdo na linha do tempo. Isso não funcionará.
  3. Altere os ids do aplicativo na linha 51 para serem os seus próprios Ids de aplicativo Vungle.
  4. Nas propriedades Flash, em 'Classe de documento', digite 'VungleExample' (sem aspas) e pressione OK.
  5. Faça o build e instale o aplicativo.

"Como posso instalar uma versão mais recente do SDK AIR (4.0 ou superior) no Flash Professional CS6?"

Siga este link para encontrar o último SDK AIR. Se você já instalou o AIR 4.0 ou superior, pode pular essa etapa. Caso contrário, siga as instruções abaixo:

  1. Descompacte o pacote SDK AIR 4.0, ou superior, em um local do seu disco rígido.
  2. Inicie o Flash Professional CS6.
  3. Selecione Ajuda > Gerenciar AIR SDK...
  4. Pressione o botão Mais (+) e vá até o local do SDK AIR descompactado
  5. Pressione OK
  6. Selecione Arquivo > Configurações de publicação
  7. Selecione o SDK AIR para iOS mais recente no menu suspenso 'Destino'

"Como posso instalar uma versão mais recente do SDK AIR (4.0 ou superior) no Flash Builder?"

Siga este link para encontrar o último SDK AIR. Se você já instalou o AIR 4.0 ou superior, pode pular essa etapa. Você pode também usar as últimas instruções da Adobe para atualização de SDKs do Flash Builder AIR.

"Estou recebendo um erro 'Entrada inválida do Adobe Animate'. O que faço?”

Se você está recebendo um erro como o que aparece na imagem abaixo, consulte este artigo.error_message_at_publish.png

Tem mais dúvidas? Envie uma solicitação

Comentários