Como começar a usar a AdMob no seu projeto C++

Este guia de início rápido é destinado a editores e desenvolvedores que querem usar a AdMob para gerar receita por meio de um app criado com o Firebase.

Confira todos os benefícios de usar o Firebase, o Google Analytics e a AdMob juntos caso ainda não tenha feito isso.

Se essa for a primeira vez que você consulta este guia, recomendamos fazer o download do app de teste do SDK dos anúncios para dispositivos móveis do Google para C++.

Antes de começar

Se você ainda não tiver um projeto e um app do Firebase, acompanhe o Guia de iniciação do Firebase: adicionar o Firebase ao seu projeto para C++.
Verifique se o Google Analytics está ativado no seu projeto do Firebase:
- Se você estiver criando um novo projeto do Firebase, ative o Google Analytics durante o fluxo de trabalho de criação do projeto.
- Se você já tiver um projeto do Firebase sem o Google Analytics ativado, poderá ativar o serviço na guia Integrações em > Configurações do projeto.
Observação: adicionar o SDK do Firebase para o Google Analytics ao seu app é opcional, mas altamente recomendável. Saiba mais sobre os benefícios dessa ação.

Etapa 1: configurar o app na conta da AdMob

Registre cada variante da plataforma do seu app como um app da AdMob.
1. Faça login ou inscreva-se em uma conta da AdMob.
2. Registre cada variante da plataforma do seu app com a AdMob. Essa etapa cria um app com um ID da AdMob exclusivo que vai ser usado mais adiante neste guia.
Vai ser solicitado que você adicione o SDK de anúncios para dispositivos móveis ao seu app. Este guia aborda instruções detalhadas para essa tarefa mais adiante.
Vincule cada um dos seus apps da AdMob ao app do Firebase correspondente.

Esta etapa é opcional, mas altamente recomendada. Saiba mais sobre os benefícios de ativar as métricas do usuário e vincular seus apps da AdMob ao Firebase.

Para cada variante de plataforma, conclua as duas etapas seguintes do painel Apps da sua conta da AdMob:
1. Ative as Métricas do usuário para que a AdMob possa processar e exibir dados de análise selecionados na sua conta da AdMob. Essa também é uma configuração obrigatória para conectar seu app da AdMob ao Firebase.
2. Vincule seu app da AdMob ao projeto atual e ao app correspondente do Firebase.
  
  Verifique se você inseriu o mesmo nome de pacote (Android) ou ID do pacote (iOS) usado para o app do Firebase. Busque o nome ou o ID do pacote do seu app do Firebase no card Seus apps em > Configurações do projeto.

Etapa 2: adicionar o ID do app da AdMob ao seu aplicativo

Android

Inclua o ID do app da AdMob no arquivo AndroidManifest.xml do seu aplicativo. Para fazer isso, adicione a tag <meta-data>, como mostrado abaixo.

<manifest>
    <application>
        <!-- Sample AdMob App ID: ca-app-pub-3940256099942544~3347511713 -->
        <meta-data
            android:name="com.google.android.gms.ads.APPLICATION_ID"
            android:value="ADMOB_APP_ID"/>
    </application>
</manifest>

iOS

No arquivo Info.plist do seu aplicativo, adicione uma chave GADApplicationIdentifier com um valor de string do ID do app da AdMob.

É possível fazer essa alteração de maneira programática:

<!-- Sample AdMob App ID: ca-app-pub-3940256099942544~1458002511 -->
<key>GADApplicationIdentifier</key>
<string>ADMOB_APP_ID</string>

Ou edite o arquivo no editor da lista de propriedades:

Editor da lista de propriedades

Etapa 3: adicionar o SDK dos anúncios para dispositivos móveis do Google

Como o SDK dos anúncios para dispositivos móveis do Google para C++ reside no namespace firebase::gma, é necessário fazer download do SDK do Firebase para C++ e descompactá-lo no diretório desejado.

O SDK do Firebase para C++ não é específico de uma plataforma, mas requer configurações de bibliotecas que são.

Android

No arquivo gradle.properties do projeto, especifique o local do SDK descompactado:
```
systemProp.firebase_cpp_sdk.dir=FULL/PATH/TO/SDK
```

Adicione o seguinte conteúdo ao arquivo settings.gradle do seu projeto:

def firebase_cpp_sdk_dir = System.getProperty('firebase_cpp_sdk.dir')

gradle.ext.firebase_cpp_sdk_dir = "$firebase_cpp_sdk_dir"
includeBuild "$firebase_cpp_sdk_dir"

No arquivo do Gradle do seu módulo no nível do app, que geralmente é app/build.gradle, adicione o conteúdo a seguir, que inclui a dependência da biblioteca do SDK dos anúncios para dispositivos móveis do Google para C++.

android.defaultConfig.externalNativeBuild.cmake {
  arguments "-DFIREBASE_CPP_SDK_DIR=$gradle.firebase_cpp_sdk_dir"
}

# Add the dependency for the Google Mobile Ads C++ SDK
apply from: "$gradle.firebase_cpp_sdk_dir/Android/firebase_dependencies.gradle"
firebaseCpp.dependencies {
  gma
}

Adicione o conteúdo a seguir ao arquivo CMakeLists.txt do seu projeto.

# Add Firebase libraries to the target using the function from the SDK.
add_subdirectory(${FIREBASE_CPP_SDK_DIR} bin/ EXCLUDE_FROM_ALL)

# Add the Google Mobile Ads C++ SDK.

# The Firebase C++ library `firebase_app` is required,
# and it must always be listed last.

set(firebase_libs
  firebase_gma
  firebase_app
)

target_link_libraries(${target_name} "${firebase_libs}")

Sincronize seu app para garantir que todas as dependências tenham as versões necessárias.

Está tudo pronto! Seu app em C++ está configurado para usar o SDK dos anúncios para dispositivos móveis do Google para C++.

iOS

As etapas desta seção são um exemplo de como adicionar o SDK dos anúncios para dispositivos móveis do Google para C++ ao seu projeto do iOS.

Faça download do CocoaPods versão 1 ou mais recente executando:
```
sudo gem install cocoapods --pre
```
Adicione o pod de anúncios para dispositivos móveis do Google a partir do SDK descompactado.
1. Crie um Podfile, caso ainda não tenha um:
```
cd YOUR_APP_DIRECTORY
pod init
```
2. No seu Podfile, adicione o pod do SDK dos anúncios para dispositivos móveis do Google para C++:
```
pod 'Google-Mobile-Ads-SDK'
```
3. Instale o pod e abra o arquivo .xcworkspace no Xcode.
```
pod install
open YOUR_APP.xcworkspace
```
4. Adicione os seguintes frameworks do SDK do Firebase para C++ ao projeto:
  - xcframeworks/firebase.xcframework
  - xcframeworks/firebase_gma.xcframework

Está tudo pronto! Seu app em C++ está configurado para usar o SDK dos anúncios para dispositivos móveis do Google para C++.

Etapa 4: inicializar o SDK dos anúncios para dispositivos móveis do Google

Antes de carregar anúncios, inicialize o SDK de anúncios para dispositivos móveis chamando firebase::gma::Initialize().

Essa chamada retorna um firebase::Future que é concluído depois que a inicialização é finalizada ou após um tempo limite de 30 segundos. Chame esse método apenas uma vez e o quanto antes, de preferência na inicialização do app.

Aviso: os anúncios podem ser pré-carregados pelo SDK dos anúncios para dispositivos móveis ou SDKs de parceiros de mediação ao chamar Initialize(). Se for preciso realizar alguma ação antes de carregar anúncios, invoque firebase::gma::SetRequestConfiguration() antes de inicializar o SDK de anúncios para dispositivos móveis. Veja alguns exemplos de ações que podem ser necessárias antes da inicialização:

Conseguir o consentimento dos usuários no Espaço Econômico Europeu (EEE)
Definir qualquer sinalização específica das solicitações (como tag_for_child_directed_treatment ou tag_for_under_age_of_consent)

Para mais informações, consulte nosso Guia de segmentação.

Veja um exemplo de como chamar Initialize():

Android

// Initialize the Google Mobile Ads library
firebase::InitResult result;
Future<AdapterInitializationStatus> future =
  firebase::gma::Initialize(jni_env, j_activity, &result);

if (result != kInitResultSuccess) {
  // Initialization immediately failed, most likely due to a missing dependency.
  // Check the device logs for more information.
  return;
}

// Monitor the status of the future.
// See "Use a Future to monitor the completion status of a method call" below.
if (future.status() == firebase::kFutureStatusComplete &&
    future.error() == firebase::gma::kAdErrorCodeNone) {
  // Initialization completed.
} else {
  // Initialization on-going, or an error has occurred.
}

iOS

// Initialize the Google Mobile Ads library.
firebase::InitResult result;
Future<AdapterInitializationStatus> future =
  firebase::gma::Initialize(&result);

if (result != kInitResultSuccess) {
  // Initialization immediately failed, most likely due to a missing dependency.
  // Check the device logs for more information.
  return;
}

// Monitor the status of the future.
// See "Use a Future to monitor the completion status of a method call" below.
if (future.status() == firebase::kFutureStatusComplete &&
    future.error() == firebase::gma::kAdErrorCodeNone) {
  // Initialization completed.
} else {
  // Initialization on-going, or an error has occurred.
}

Usar `Future` para monitorar o status de conclusão de uma chamada de método

Um Future permite determinar o status de conclusão das suas chamadas de métodos assíncronas.

Por exemplo, quando seu app chama firebase::gma::Initialize(), um novo firebase::Future é criado e retornado. Seu app vai poder consultar o status() do Future para determinar quando a inicialização foi concluída. Depois da conclusão, seu app vai poder invocar result() para receber o AdapterInitializationStatus resultante.

Os métodos que retornam um Future têm um método de "último resultado" correspondente que os apps podem usar para recuperar o Future mais recente de uma determinada ação. Por exemplo, firebase::gma::Initialize() tem um método correspondente chamado firebase::gma::InitializeLastResult(), que retorna um Future que pode ser usado pelo seu app para verificar o status da última chamada para firebase::gma::Initialize().

Se o status de Future for concluído e o código do erro for firebase::gma::kAdErrorCodeNone, significa que a operação foi concluída com sucesso.

Além disso, callbacks podem ser registrados para que sejam invocados quando um Future for concluído. Em alguns casos, o callback vai ser executado em uma linha de execução diferente. Verifique se o código é thread-safe. Este snippet de código usa um ponteiro de função para o callback:

// Registers the OnCompletion callback. user_data is a pointer that is passed verbatim
// to the callback as a void*. This allows you to pass any custom data to the callback
// handler. In this case, the app has no data, so you must pass nullptr.
firebase::gma::InitializeLastResult().OnCompletion(OnCompletionCallback,
  /*user_data=*/nullptr);

// The OnCompletion callback function.
static void OnCompletionCallback(
  const firebase::Future<AdapterInitializationStatus>& future, void* user_data) {
  // Called when the Future is completed for the last call to firebase::gma::Initialize().
  // If the error code is firebase::gma::kAdErrorCodeNone,
  // then the SDK has been successfully initialized.
  if (future.error() == firebase::gma::kAdErrorCodeNone) {
    // success!
  } else {
    // failure.
  }
}

Etapa 5: escolher um formato de anúncio para implementar no seu app

Na AdMob, há vários formatos de anúncios diferentes para que você possa escolher o mais adequado à experiência do usuário no seu app. Clique no botão de um formato de anúncio para consultar instruções detalhadas de implementação na documentação da AdMob.

Anúncios retangulares que aparecem na parte superior ou inferior da tela do dispositivo

Os anúncios de banner permanecem na tela enquanto os usuários interagem com o aplicativo e podem ser atualizados automaticamente após um determinado período. Se você começou a usar os anúncios para dispositivos móveis agora, saiba que eles são um excelente ponto de partida.

Implementar anúncios de banner

Intersticial

Anúncios em tela cheia que cobrem a interface de um aplicativo até serem fechados pelo usuário

Os anúncios intersticiais são indicados para pausas naturais no fluxo de execução de um app, como entre as fases de um jogo ou logo após a conclusão de uma tarefa.

Implementar anúncios intersticiais

Premiado

Anúncios que recompensam os usuários por assistir a vídeos curtos e interagir com pesquisas e anúncios jogáveis

Os anúncios premiados (ou "baseados em recompensas") podem ajudar a gerar receita com usuários de jogos sem custo para jogar.

Implementar anúncios premiados

Outros tópicos de interesse

Ver métricas do usuário e dados de análise

Após a inicialização do SDK de anúncios para dispositivos móveis, ele começa a registrar automaticamente as análises de eventos e propriedades do usuário do seu app. É possível consultar esses dados sem adicionar código ao app ou implementar anúncios. Esses dados de análise podem ser encontrados em:

No card Métricas do usuário da sua conta da AdMob (painel Início ou Apps), é possível ver as métricas do usuário selecionadas e derivadas dos dados de análise coletados, como a duração média da sessão, a ARPU e a retenção.
No painel Analytics do Console do Firebase, é possível ver estatísticas agregadas e resumos das principais métricas. Se você adicionar o SDK do Firebase para o Google Analytics, também poderá marcar conversões para campanhas publicitárias e criar públicos-alvo personalizados no Console do Firebase.

Para representar melhor as métricas ARPU e ARPPU, inclua dados de um evento personalizado de análise chamado ecommerce_purchase no cálculo da receita dessas métricas (saiba como).

(Opcional) Usar mais recursos do Google Analytics e do Firebase

Aproveite mais oportunidades e recursos para melhorar a monetização de apps e o engajamento dos usuários:

Adicionar e usar o SDK do Firebase para o Google Analytics
- Implemente a geração de registros de eventos personalizados no seu aplicativo.
- Marque as conversões para campanhas publicitárias personalizadas.
- Inclua dados de eventos ecommerce_purchase no cálculo da receita para as métricas ARPU e ARPPU.
Usar outros produtos do Firebase no seu app

Depois de adicionar o SDK do Firebase para o Google Analytics, use outros produtos do Firebase para otimizar os anúncios no seu aplicativo.
- A Configuração remota permite que você altere o comportamento e a aparência do app sem publicar uma atualização para ele, sem custos e sem limite de usuários ativos por dia.
- O Teste A/B permite testar alterações na IU, nos recursos ou nas campanhas de engajamento do seu app para saber, antes da implementação, se elas afetarão as principais métricas (como receita e retenção).

Para começar, acesse o guia sobre como usar o Google Analytics e o Firebase com apps da AdMob.

Como começar a usar a AdMob no seu projeto C++

Antes de começar

Etapa 1: configurar o app na conta da AdMob

Etapa 2: adicionar o ID do app da AdMob ao seu aplicativo

Android

iOS

Etapa 3: adicionar o SDK dos anúncios para dispositivos móveis do Google

Android

iOS

Etapa 4: inicializar o SDK dos anúncios para dispositivos móveis do Google

Android

iOS

Usar Future para monitorar o status de conclusão de uma chamada de método

Etapa 5: escolher um formato de anúncio para implementar no seu app

Banner

Intersticial

Premiado

Outros tópicos de interesse

Ver métricas do usuário e dados de análise

(Opcional) Usar mais recursos do Google Analytics e do Firebase

Usar `Future` para monitorar o status de conclusão de uma chamada de método