--- metadata: - name: generator content: Diplodoc Platform v5.50.6 alternate: - https://ads.yandex.com/helpcenter/en/dev/android/app-open-ad.md - https://ads.yandex.com/helpcenter/pt/dev/android/app-open-ad.md - https://ads.yandex.com/helpcenter/ru/dev/android/app-open-ad.md - https://ads.yandex.com/helpcenter/zh/dev/android/app-open-ad.md --- > **Documentation Index:** Fetch the complete configuration index at https://ads.yandex.com/helpcenter/pt/llms.txt # Anúncios App Open Os anúncios de abertura de aplicativos são um formato de anúncio especial para monetizar as telas de carregamento do seu app. Esses anúncios podem ser fechados a qualquer momento e são projetados para serem veiculados quando os usuários colocam seu aplicativo em primeiro plano, seja na inicialização ou quando retornam a ele do segundo plano. Este guia mostrará como integrar anúncios exibidos ao abrir um aplicativo Android. Além de exemplos de código e instruções, contém recomendações específicas aos formatos e links para recursos adicionais. {% note alert %} Os anúncios de abertura de aplicativos só podem ser colocados em aplicativos com orientação vertical. Os anúncios não serão exibidos em orientação horizontal. {% endnote %} ## Layout Os anúncios App Open incluem um botão **Go to the app** para que os usuários saibam que estão no seu aplicativo e possam fechar o anúncio. Veja um exemplo de como um anúncio se parece: ## Pré-requisito {#pre} 1. Siga os passos de integração do SDK descritos em [Início rápido](../../../en/dev/android/quick-start.md). 2. [Inicialize](../../../en/dev/android/quick-start.md#init) seu SDK de anúncios com antecedência. 3. Confirme se você está utilizando a última versão do [Yandex Mobile Ads SDK](../../../en/dev/android/changelog-android.md). Se você estiver usando mediação, confirme se também está utilizando a última versão da [compilação unificada](../../../en/dev/android/changelog-android.md). ### Termos e definições * **Inicialização a frio** é a inicialização de um aplicativo que não está na RAM, criando uma nova sessão de aplicativo. * **Inicialização a quente** é a alternação do aplicativo do modo de segundo plano, quando o aplicativo está pausado na RAM, para o modo de primeiro plano. ## Implementação {#implement} 1. Inicializar o SDK ao inicializar o aplicativo. 2. Criar e configurar o objeto carregador de anúncios `AppOpenAdLoader`. 3. Definir o listener do método de callback `AppOpenAdLoadListener` para enviar notificações quando os anúncios são carregados com êxito ou não. 4. Carregar o anúncio usando o método `loadAd(AdRequestConfiguration)`. 5. Usar [LifecycleEventObserver](https://developer.android.com/reference/androidx/lifecycle/LifecycleEventObserver) para lidar com mudanças de status do aplicativo e exibir anúncios App Open. 6. Antes de renderizar o anúncio, definir o listener do método de callback do anúncio `AppOpenAdEventListener`. 7. Renderizar o anúncio usando o método `show(Activity)`. 8. Liberar os recursos. ### Principais etapas 1. Inicialize o SDK ao inicializar o aplicativo. {% list tabs %} - Kotlin ```kotlin MobileAds.initialize(this) { // Now you can use ads } ``` - Java ```java MobileAds.initialize(this, () -> { // Now you can use ads }); ``` {% endlist %} 2. Crie e configure o objeto carregador de anúncios `AppOpenAdLoader`. Você vai precisar da ID de unidade de anúncio da interface do Yandex Advertising Network (`AD_UNIT_ID`). Você pode expandir os parâmetros de solicitação de anúncio através de `AdRequestConfiguration.Builder()` passando interesses do usuário, dados contextuais do aplicativo, detalhes de localização ou outros dados. Fornecer dados contextuais adicionais na solicitação pode melhorar consideravelmente a qualidade do anúncio. Saiba mais na seção [Segmentação de anúncios](../../../en/dev/android/target.md). {% list tabs %} - Kotlin ```kotlin val appOpenAdLoader: AppOpenAdLoader = AppOpenAdLoader(application) val AD_UNIT_ID = "R-M-XXXXXX-Y" // for debugging, you can use "demo-appopenad-yandex" val adRequestConfiguration = AdRequestConfiguration.Builder(AD_UNIT_ID).build() ``` - Java ```java final AppOpenAdLoader appOpenAdLoader = AppOpenAdLoader(application); final String AD_UNIT_ID = "R-M-XXXXXX-Y"; // for debugging, you can use "demo-appopenad-yandex" final AdRequestConfiguration adRequestConfiguration = new AdRequestConfiguration.Builder(AD_UNIT_ID).build(); ``` {% endlist %} 3. Defina o listener do método de callback `AppOpenAdLoadListener` para enviar notificações quando os anúncios são carregados com êxito ou não. {% list tabs %} - Kotlin ```kotlin val appOpenAdLoadListener = object : AppOpenAdLoadListener { override fun onAdLoaded(appOpenAd: AppOpenAd) { // The ad was loaded successfully. You can now show the ad. this@Activity.appOpenAd = appOpenAd } override fun onAdFailedToLoad(adRequestError: AdRequestError) { // Ad failed to load with AdRequestError. // Attempting to load a new ad from the onAdFailedToLoad() method is strongly discouraged. } } appOpenAdLoader.setAdLoadListener(appOpenAdLoadListener) ``` - Java ```java AppOpenAdLoadListener appOpenAdLoadListener = new AppOpenAdLoadListener() { @Override public void onAdLoaded(@NonNull final AppOpenAd appOpenAd) { // The ad was loaded successfully. You can now show the ad. mAppOpenAd = appOpenAd; } @Override public void onAdFailedToLoad(@NonNull final AdRequestError adRequestError) { // Ad failed to load with AdRequestError. // Attempting to load a new ad from the onAdFailedToLoad() method is strongly discouraged. } }; appOpenAdLoader.setAdLoadListener(appOpenAdLoadListener); ``` {% endlist %} 4. Carregue o anúncio usando o método `loadAd(AdRequestConfiguration)`. {% list tabs %} - Kotlin ```kotlin appOpenAdLoader.loadAd(adRequestConfiguration) ``` - Java ```java appOpenAdLoader.loadAd(adRequestConfiguration); ``` {% endlist %} 5. Use `LifecycleEventObserver` para lidar com mudanças de status do aplicativo e exibir anúncios App Open. {% list tabs %} - Kotlin ```kotlin val processLifecycleObserver = DefaultProcessLifecycleObserver( onProcessCameForeground = ::showAppOpenAd ) ProcessLifecycleOwner.get().lifecycle.addObserver(processLifecycleObserver) ``` - Java ```java final DefaultProcessLifecycleObserver processLifecycleObserver = new DefaultProcessLifecycleObserver() { @Override public void onProcessCameForeground() { showAppOpenAd(); } } ProcessLifecycleOwner.get().getLifecycle().addObserver(processLifecycleObserver); ``` {% endlist %} 6. Antes de renderizar o anúncio, defina o listener do método de callback do anúncio `AppOpenAdEventListener`. {% list tabs %} - Kotlin ```kotlin private inner class AdEventListener : AppOpenAdEventListener { override fun onAdShown() { // Called when ad is shown. } override fun onAdFailedToShow(adError: AdError) { // Called when ad failed to show. } override fun onAdDismissed() { // Called when ad is dismissed. // Clean resources after dismiss and preload new ad. clearAppOpenAd() loadAppOpenAd() } override fun onAdClicked() { // Called when a click is recorded for an ad. } override fun onAdImpression(impressionData: ImpressionData?) { // Called when an impression is recorded for an ad. // Get Impression Level Revenue Data in argument. } } private val appOpenAdEventListener = AdEventListener() appOpenAd?.setAdEventListener(appOpenAdEventListener) ``` - Java ```java AppOpenAdEventListener appOpenAdEventListener = new AppOpenAdEventListener() { @Override public void onAdShown() { // Called when ad is shown. } @Override public void onAdFailedToShow(@NonNull final AdError adError) { // Called when ad failed to show. } @Override public void onAdDismissed() { // Called when ad is dismissed. // Clean resources after dismiss and preload new ad. clearAppOpenAd(); loadAppOpenAd(); } @Override public void onAdClicked() { // Called when a click is recorded for an ad. } @Override public void onAdImpression(@Nullable final ImpressionData impressionData) { // Called when an impression is recorded for an ad. } }; if (mAppOpenAd != null) { mAppOpenAd.setAdEventListener(appOpenAdEventListener); } ``` {% endlist %} 7. Renderize o anúncio usando o método `show`. {% list tabs %} - Kotlin ```kotlin private fun showAppOpenAd() { appOpenAd?.show(activity) } ``` - Java ```java private void showAppOpenAd() { if (mAppOpenAd != null) { mAppOpenAd.show(activity); } } ``` {% endlist %} {% note info %} Se o anúncio já tiver sido veiculado, a chamada do método `show(Activity)` (mostrar atividade) retornará um erro de exibição em `AppOpenAdEventListener.onAdFailedToShow(AdError)` (falha na exibição, erro no anúncio). {% endnote %} 8. Libere os recursos. Isso previne vazamentos de memória. {% list tabs %} - Kotlin ```kotlin private fun clearAppOpenAd() { appOpenAd?.setAdEventListener(null) appOpenAd = null } ``` - Java ```java private void clearAppOpenAd() { if (mAppOpenAd != null) { mAppOpenAd.setAdEventListener(null); mAppOpenAd = null; } } ``` {% endlist %} ## Funcionalidades da integração de anúncios App Open {#features} 1. Todas as chamadas para métodos do Yandex Mobile Ads SDK devem ser feitas a partir do thread principal. 2. O carregamento pode demorar, então não aumente o tempo de inicialização a frio se o anúncio não tiver carregado. 3. Pré-carregue o anúncio para exibição subsequente durante inicializações a quente. 4. Desencorajamos o carregamento de anúncios App Open e outros formatos de anúncio em paralelo durante a inicialização do aplicativo, pois o aplicativo pode estar baixando dados operacionais nesse momento. Isso pode sobrecarregar o dispositivo e a conexão com a internet, fazendo com que o carregamento do anúncio demore mais. 5. Se houve um erro no callback `onAdFailedToLoad()`, não tente carregar um novo anúncio novamente. Se precisar fazer isso, limite o número de tentativas de recarregamento de anúncios. Isso ajudará a evitar solicitações constantes malsucedidas e problemas de conexão quando surgirem limitações. ## Teste da integração de anúncios na inicialização {#test} ### Uso de blocos de anúncios de demonstração para teste de anúncios {#demo-blocks} Recomendamos usar anúncios de teste para testar sua integração para anúncios App Open e seu próprio aplicativo. Para garantir que anúncios de teste sejam retornados para cada solicitação de anúncio, criamos um ID especial de posicionamento de anúncios de demonstração. Use-o para verificar sua integração de anúncios. adUnitId de demonstração: `demo-appopenad-yandex`. {% note warning %} Antes de publicar seu app na loja, lembre-se de substituir a ID de inserção demonstrativa por uma ID real obtida na interface do Yandex Advertising Network. {% endnote %} Confira a lista de IDs de posicionamento de anúncios de demonstração disponíveis na seção [Blocos de anúncio de demonstração para teste](../../../en/dev/android/demo-blocks.md). ### Teste da integração de anúncios {#test-int} Você pode verificar sua integração de anúncios App Open usando o analisador integrado do SDK. A ferramenta garante que seus anúncios App Open estejam integrados corretamente e gera um relatório detalhado no log. Para ver o relatório, procure a palavra-chave "YandexAds" na ferramenta [Logcat](https://developer.android.com/studio/command-line/logcat) usada para depuração de aplicativos Android. ```bash adb logcat -v brief '*:S YandexAds' ``` Se a integração for bem-sucedida, você verá esta mensagem: ```bash adb logcat -v brief '*:S YandexAds' mobileads$ adb logcat -v brief '*:S YandexAds' I/YandexAds(13719): [Integration] Ad type App Open Ad was integrated successfully ``` Se você estiver tendo problemas para integrar anúncios, receberá um relatório detalhado sobre os problemas e recomendações de como corrigi-los. ## Recomendações 1. Não renderize seu anúncio de abertura do aplicativo antes da tela de carregamento inicial. Ao exibir a tela de carregamento inicial, você melhora a experiência do usuário no aplicativo, deixando-a mais fluida e agradável. Isso evitará que o usuário fique surpreso ou confuso, e ele terá a certeza de que abriu o aplicativo correto. Na mesma tela, você pode avisar os usuários sobre o próximo anúncio. Use um indicador de carregamento ou simplesmente uma mensagem de texto informando ao usuário que ele retomará a visualização do conteúdo do aplicativo após o anúncio. 2. Se houver um atraso entre a solicitação e a renderização do anúncio, o usuário poderá abrir brevemente seu aplicativo e, em seguida, ver inesperadamente um anúncio não relacionado ao conteúdo. Isso pode impactar negativamente a experiência do usuário, então vale a pena evitar. Uma solução é usar a tela de carregamento inicial antes de exibir o conteúdo principal do aplicativo e iniciar a renderização do anúncio a partir dessa tela. Se o aplicativo abrir algum conteúdo após a tela de carregamento inicial, é melhor não renderizar o anúncio. 3. Espere até que novos usuários abram o aplicativo e o usem algumas vezes antes de renderizar um anúncio de abertura do aplicativo. Renderize o anúncio apenas para usuários que atenderam a certos critérios no aplicativo (por exemplo, passaram de um certo nível, abriram o aplicativo um certo número de vezes ou não estão participando de ofertas premiadas). Não renderize o anúncio imediatamente após a instalação do aplicativo. 4. Altere a frequência de renderização de anúncios com base no comportamento do usuário do aplicativo. Não renderize o anúncio a cada inicialização a frio/quente do aplicativo. 5. Renderize o anúncio apenas se o seu aplicativo estiver em segundo plano por um certo período de tempo (por exemplo, 30 segundos, dois minutos, 15 minutos). 6. Você deve realizar testes completos, já que cada aplicativo é único e requer uma estratégia especial para maximizar a receita sem reduzir a retenção ou o tempo gasto no aplicativo. O comportamento e o engajamento dos usuários podem mudar ao longo do tempo, então recomendamos testar periodicamente as estratégias que você usa para seus anúncios App Open. ## Recursos adicionais {#resources} * Link para [GitHub](https://github.com/yandexmobile/yandex-ads-sdk-android).