Guia Prático: Monetizando seu App com Upeex Ads SDK no React Native

Se você está desenvolvendo um aplicativo em React Native ou Expo e deseja rentabilizá-lo exibindo anúncios de forma rápida e elegante, o @upeex/ads-sdk é a solução ideal.

Neste tutorial, vamos cobrir desde a instalação básica até a exibição de banners padronizados e popups intersticiais de tela inteira (aqueles que cobrem a tela e possuem um timer de fechamento).

---

🛠️ Pré-requisitos

Para utilizar este SDK, você vai precisar de um projeto básico rodando em:

• React (versão 17+)
• React Native (versão 0.68+) ou Expo
• Conexão à internet ativada no seu aplicativo/webview.

💡 Nota: O SDK não exige nenhuma biblioteca pesada ou nativa de terceiros. É construído para funcionar perfeitamente tanto no CLI nativo quanto no “Expo Go”.

---

🌍 Onde Funciona e Limitações

A maior vantagem do @upeex/ads-sdk é ser 100% JavaScript, feito inteiramente com componentes padrões do react-native.

Onde você PODE usar:

• ✅ React Native CLI: Qualquer projeto padrão nativo.
• ✅ Expo: Funciona impecavelmente no Expo Go ou builds via EAS (sem precisar de npx expo prebuild ou instalar Pods).
• ✅ React Native Web: Suporta renderização em navegadores caso seu projeto Expo tenha suporte à Web.

Onde você NÃO DEVE usar:

• ❌ Códigos em Kotlin, Java ou Swift puro (O app precisa ser empacotado em React Native).
• ❌ Projetos React tradicionais para Web pura (como Vite, Next.js, Create React App) sem a ponte do react-native-web.

---

🚀 1. Instalação

Abra o terminal na pasta raiz do seu projeto e rode o comando do seu gerenciador de pacotes favorito:

Usando NPM:

npm install @upeex/ads-sdk

Se seu projeto e ambiente estiverem consistentes, nenhuma configuração extra nativa (como pod install) será exigida!

---

🖼️ 2. Implementando um Anúncio tipo “Banner”

Os anúncios do tipo Banner são pequenos e ficam geralmente fixos no rodapé, cabeçalho, ou entre listas de conteúdos dentro do seu aplicativo.

Veja o exemplo de como carregá-lo em uma tela comum:

import React from 'react';
import { View, StyleSheet } from 'react-native';
// 1. Importe o SDK
import AdBanner from '@upeex/ads-sdk';

export default function HomeScreen() {
  return (
    <View style={styles.container}>
      {/* O resto do seu conteúdo vai aqui */}
      
      {/* 2. Insira o Banner onde desejar exibí-lo */}
      <AdBanner
        client="SEU_CLIENTE_AQUI"
        slot="SEU_SLOT_AQUI"
        typeAds="banner"
        theme="light" // 'light' ou 'dark'
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#fff',
    justifyContent: 'center', // Para centralizar no exemplo
  },
});

O que aconteceu aqui?

• Passamos as propriedades obrigatórias client e slot. Estes valores são os identificadores únicos da sua conta no painel do Upeex.
• Com typeAds="banner", o componente entende que a renderização deve ser linear e não bloquear a visão do app do usuário.

---

📱 3. Implementando um Anúncio tipo “Popup” (Intersticial)

O Popup é um formato de anúncio que ocupa a tela inteira, ganhando forte atenção. Muito utilizado entre mudanças de fase num jogo, ou ao concluir uma tarefa no aplicativo.

O visual padrão traz uma barra de progresso no topo, durando 5 segundos, antes de permitir que o usuário possa fechar o anúncio de forma amigável.

import React, { useState } from 'react';
import { View, Button, StyleSheet } from 'react-native';
import AdBanner from '@upeex/ads-sdk';

export default function PaymentSuccessScreen() {
  const [showPopup, setShowPopup] = useState(false);

  return (
    <View style={styles.container}>
      <Button 
        title="Ver recompensa ou próxima fase" 
        onPress={() => setShowPopup(true)} 
      />
      
      {/* Renderização Condicional */}
      {showPopup && (
        <AdBanner
          client="SEU_CLIENTE_AQUI"
          slot="SEU_SLOT_AQUI"
          typeAds="popup"
          debug={true} // Útil enquanto testamos!
        />
      )}
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
});

Detalhes do Popup:

• Assim que ativado, o SDK abre um Modal nativo sobrepondo as outras telas.
• O botão de fechar “X” só ficará visível e habilitado após o ciclo (5s) da barra de progresso terminar.

---

⚙️ 4. Tabela de Propriedades (Props)

Para você customizar a renderização, pode configurar as propriedades diretamente no <AdBanner />. Aqui estão todas as props disponíveis:

Propriedade	Tipo	Obrigatório	Padrão	Descrição
client	string	Sim	-	Seu ID/Chave de Cliente fornecido na conta da Upeex
slot	string	Sim	-	Identificação do espaço de anúncio (Ex: home_footer, main_popup)
typeAds	string	Não	banner	Formato do anúncio: pode ser 'banner' ou 'popup'.
theme	string	Não	'light'	Adapta o fundo. Pode usar 'dark' para apps em modo escuro.
debug	boolean	Não	false	Se true, exibe logs de funcionamento no seu console (CLI).
baseUrl	string	Não	[Produção]	Define o endpoint base da API Upeex. Geralmente você nunca precisará alterar.
style	object	Não	{}	Estilos adicionais para o container do tipo banner.

Nota: Também suportamos typeads (em minúsculo) como prop de conveniência.

---

🐛 5. Modo Console (Debug)

Na fase de integração pode ser desafiador saber se os banners estão requisitando corretamente as fontes de mídia. É por isso que você pode adicionar debug={true}.

Ao rodar seu aplicativo dessa forma:

<AdBanner client="TESTE" slot="TESTE" debug={true} />

Você verá a trilha real no console (Terminal / Metro Bundler), como:

[UPEEX ADS] Buscando anúncio {"client":"TESTE","slot":"TESTE"}
[UPEEX ADS] Resposta do servidor { "image": "...", "clickUrl": "..." }
...

Assim fica super fácil garantir que o link foi requisitado e que tudo retornou com código 200 (Sucesso).

---

🎨 Dicas e Boas Práticas (UI/UX)

1. Popup Responsável: Para os formatos popup, deixe para carregá-lo somente nos pontos de mudança natural das telas de usuário (por exemplo, após enviar um formulário ou de assistir um vídeo). Exibições aleatórias sem base no contexto podem assustar o usuário.
2. Espaço Fixo para Banners: É recomendável você setar uma View ou componente que abrace os Banners garantindo um tamanho exato (ex: height: 50 para celular). Assim evita-se que, enquanto a internet carrega a imagem do anúncio, a tela dê uns “pulos” visuais estranhos incomodando a usabilidade.

Espero que este guia tenha facilitado o processo! Qualquer dúvida consulte nosso suporte técnico aos desenvolvedores.