--- metadata: - name: generator content: Diplodoc Platform v5.52.0 alternate: - https://ads.yandex.com/helpcenter/en/dev/unity/app-open-ad.md - https://ads.yandex.com/helpcenter/pt/dev/unity/app-open-ad.md - https://ads.yandex.com/helpcenter/ru/dev/unity/app-open-ad.md - https://ads.yandex.com/helpcenter/zh/dev/unity/app-open-ad.md - href: pt/dev/unity/app-open-ad.md type: text/markdown title: Markdown version - href: llms.txt type: text/markdown title: llms.txt --- > **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 App Open em aplicativos Unity. 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 o processo em [Início rápido](../../../en/dev/unity/quick-start.md) para integrar o plugin Yandex Mobile Ads Unity. 2. Confirme se você está utilizando a última versão do [plugin Yandex Mobile Ads Unity](../../../en/dev/platforms.md). Se você estiver usando mediação, confirme se também está utilizando a última versão da [compilação unificada](../../../en/dev/platforms.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. Criar um carregador de anúncios `AppOpenAdLoader` e registrar listeners para eventos de carregamento de anúncios. 2. Configurar os parâmetros de carregamento de anúncios em `AdRequestConfiguration`. 3. Carregar o anúncio usando o método `AppOpenAdLoader.LoadAd(AdRequestConfiguration)`. 4. Registrar listeners para eventos em que os usuários interagem com seu anúncio. 5. Usar `AppStateObserver` para lidar com mudanças de status do aplicativo e exibir anúncios App Open. 6. Mostrar o anúncio chamando o método `AppOpenAd.Show()`. 7. Liberar os recursos. ### Principais etapas 1. Crie um carregador de anúncios `AppOpenAdLoader` e registre listeners para eventos de carregamento de anúncios. ```c# using UnityEngine; using YandexMobileAds; using YandexMobileAds.Base; public class YandexMobileAdsAppOpenAdDemoScript : MonoBehaviour { private AppOpenAdLoader appOpenAdLoader; private AppOpenAd appOpenAd; private void SetupLoader() { appOpenAdLoader = new AppOpenAdLoader(); appOpenAdLoader.OnAdLoaded += HandleAdLoaded; appOpenAdLoader.OnAdFailedToLoad += HandleAdFailedToLoad; // ... } public void HandleAdLoaded(object sender, AppOpenAdLoadedEventArgs args) { // The ad was loaded successfully. Now you can handle it. appOpenAd = args.AppOpenAd; } public void HandleAdFailedToLoad(object sender, AdFailedToLoadEventArgs args) { // Ad {args.AdUnitId} failed for to load with {args.Message} // Attempting to load a new ad from the OnAdFailedToLoad event is strongly discouraged. } } ``` 2. Configure os parâmetros de carregamento de anúncios em `AdRequestConfiguration`. ```c# string adUnitId = "demo-appopenad-yandex"; // replace with "R-M-XXXXXX-Y" AdRequestConfiguration adRequestConfiguration = new AdRequestConfiguration.Builder(adUnitId).Build(); ``` `AdUnitId`: identificador único emitido na interface do Yandex Advertising Network, com o seguinte aspecto: R-M-XXXXXX-Y. {% note tip %} Para fins de teste, você pode usar o ID do bloco de anúncios de demonstração: "demo-appopenad-yandex". Antes de publicar o anúncio, você precisa substituir o ID do bloco de demonstração por um ID de bloco de anúncios real. 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. {% endnote %} 3. Carregue o anúncio com o método `LoadAd`, passando `AdRequestConfiguration` como argumento. ```c# appOpenAdLoader.LoadAd(adRequestConfiguration); ``` 4. Registre listeners para eventos em que os usuários interagem com seu anúncio. ```c# using System; // ... appOpenAd.OnAdClicked += HandleAdClicked; appOpenAd.OnAdShown += HandleAdShown; appOpenAd.OnAdFailedToShow += HandleAdFailedToShow; appOpenAd.OnAdDismissed += HandleAdDismissed; appOpenAd.OnAdImpression += HandleImpression; // ... public void HandleAdClicked(object sender, EventArgs args) { // Called when a click is recorded for an ad. } public void HandleAdShown(object sender, EventArgs args) { // Called when ad is shown. } public void HandleAdFailedToShow(object sender, AdFailureEventArgs args) { // Called when an ad failed to show. } public void HandleAdDismissed(object sender, EventArgs args) { // Called when an ad is dismissed. } public void HandleImpression(object sender, ImpressionData impressionData) { // Called when an impression is recorded for an ad. } ``` 5. Use `AppStateObserver` para lidar com mudanças de status do aplicativo e exibir anúncios App Open. ```c# using YandexMobileAds; public class YandexMobileAdsAppOpenAdDemoScript : MonoBehaviour { public void Awake() { // Use the AppStateObserver to listen to application open/close events. AppStateObserver.OnAppStateChanged += HandleAppStateChanged; } public void OnDestroy() { // Unsubscribe from the event to avoid memory leaks. AppStateObserver.OnAppStateChanged -= HandleAppStateChanged; } } ``` 6. Mostre o anúncio chamando o método `AppOpenAd.Show()`. ```c# private void HandleAppStateChanged(object sender, AppStateChangedEventArgs args) { if (!args.IsInBackground) { ShowAppOpenAd(); } } private void ShowAppOpenAd() { if (appOpenAd != null) { appOpenAd.Show(); } } ``` {% note info %} Se o anúncio já tiver sido veiculado, a chamada do método `AppOpenAd.Show()` (abrir anúncio, exibir) method retornará um erro de exibição em `HandleAdFailedToShow`(falha na exibição). {% endnote %} 7. Chame `Destroy()` para os anúncios que são exibidos e elimine links que não são mais usados na cena atual. Isso libera os recursos e evita vazamentos de memória. ```c# public void DestroyAppOpenAd() { if (appOpenAd != null) { appOpenAd.Destroy(); appOpenAd = null; } } ``` ### Exemplo de código completo ```c# using System; using UnityEngine; using UnityEngine.UI; using YandexMobileAds; using YandexMobileAds.Base; public class YandexMobileAdsAppOpenAdDemoScript : MonoBehaviour { private AppOpenAdLoader appOpenAdLoader; private AppOpenAd appOpenAd; private var isColdStartAdShown = false; private void Awake() { DontDestroyOnLoad(gameObject); SetupLoader(); AppStateObserver.OnAppStateChanged += HandleAppStateChanged; RequestAppOpenAd(); } private void OnDestroy() { AppStateObserver.OnAppStateChanged -= HandleAppStateChanged; } private void SetupLoader() { appOpenAdLoader = new AppOpenAdLoader(); appOpenAdLoader.OnAdLoaded += HandleAdLoaded; appOpenAdLoader.OnAdFailedToLoad += HandleAdFailedToLoad; } private void HandleAppStateChanged(object sender, AppStateChangedEventArgs args) { if (!args.IsInBackground) { ShowAppOpenAd(); } } private void ShowAppOpenAd() { if (appOpenAd != null) { appOpenAd.Show(); } } private void RequestAppOpenAd() { string adUnitId = "demo-appopenad-yandex"; // replace with "R-M-XXXXXX-Y" AdRequestConfiguration adRequestConfiguration = new AdRequestConfiguration.Builder(adUnitId).Build(); appOpenAdLoader.LoadAd(adRequestConfiguration); } public void HandleAdLoaded(object sender, AppOpenAdLoadedEventArgs args) { // The ad was loaded successfully. Now you can handle it. appOpenAd = args.AppOpenAd; // Add events handlers for ad actions appOpenAd.OnAdClicked += HandleAdClicked; appOpenAd.OnAdShown += HandleAdShown; appOpenAd.OnAdFailedToShow += HandleAdFailedToShow; appOpenAd.OnAdDismissed += HandleAdDismissed; appOpenAd.OnAdImpression += HandleImpression; if (!isColdStartAdShown) { ShowAppOpenAd(); isColdStartAdShown = true; } } public void HandleAdFailedToLoad(object sender, AdFailedToLoadEventArgs args) { // Ad {args.AdUnitId} failed for to load with {args.Message} // Attempting to load a new ad from the OnAdFailedToLoad event is strongly discouraged. } public void HandleAdDismissed(object sender, EventArgs args) { // Called when ad is dismissed. // Clear resources after Ad dismissed. DestroyAppOpenAd(); // Now you can preload the next ad. RequestAppOpenAd(); } public void HandleAdFailedToShow(object sender, AdFailureEventArgs args) { // Called when an ad failed to show. // Clear resources. DestroyAppOpenAd(); // Now you can preload the next ad. RequestAppOpenAd(); } public void HandleAdClicked(object sender, EventArgs args) { // Called when a click is recorded for an ad. } public void HandleAdShown(object sender, EventArgs args) { // Called when ad is shown. } public void HandleImpression(object sender, ImpressionData impressionData) { // Called when an impression is recorded for an ad. } public void DestroyAppOpenAd() { if (appOpenAd != null) { appOpenAd.Destroy(); appOpenAd = null; } } } ``` ## Funcionalidades da integração de anúncios App Open {#features} 1. O carregamento pode demorar, então não aumente o tempo de inicialização a frio se o anúncio não tiver carregado. 2. Pré-carregue o anúncio para exibição subsequente durante inicializações a quente. 3. 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. 4. Se houve um erro no evento `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} {% list tabs %} - Android ### 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. - iOS ### 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/ios/demo-blocks.md). ### Teste da integração de anúncios Você pode testar sua integração de anúncios usando a ferramenta Console nativa. Para ver logs detalhados, chame o método `enableLogging` da classe `YMAMobileAds`. ```swift YMAMobileAds.enableLogging() ``` Para ver os logs do SDK, acesse a ferramenta Console e defina `Subsystem = com.mobile.ads.ads.sdk`. Você também pode filtrar logs por categoria e nível de erro. Se você estiver tendo problemas para integrar anúncios, receberá um relatório detalhado sobre os problemas e recomendações de como corrigi-los. {% endlist %} ## 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-unity-plugin).