Conexão incorporada
O Embedded Connect reduz o atrito e melhora o funil de conversão quando os usuários tentam conectar o Google AdSense à sua plataforma.
O Embedded Connect é uma pequena biblioteca JavaScript que determina o melhor ponto de partida para um determinado usuário e o orienta por um fluxo de inscrição personalizado do Google AdSense, que o ajuda em todas as etapas necessárias para que possam veicular anúncios. Ela lida com cenários como determinar se o usuário tem uma conta do Google AdSense, se ele assinou os Termos e Condições do Google AdSense, se adicionou o site da plataforma à conta do Google AdSense e se o status do site é "Pronto".
O Embedded Connect com a opção de UX gerenciada pelo Google também pode processar a UX envolvida na exibição do status da conta e do site ao usuário, direcionando-o ao local correto no Google AdSense para resolver possíveis problemas.
Para ajudar na experiência do desenvolvedor, a biblioteca também emite callbacks para a plataforma com o ID do editor do Google AdSense do usuário, que é necessário para configurar a veiculação de anúncios corretamente.
O Embedded Connect oferece duas opções de experiência do usuário:
- UX gerenciada pelo Google. Usar o widget Conexão incorporada, que gerencia toda a UX. O widget ajudará os usuários durante um fluxo de inscrição e mostrará a eles as informações sobre o status da conta e do site. Essa opção fornece um retorno de chamada com o ID do editor do Google AdSense acionado quando o usuário conecta uma conta do Google AdSense pela primeira vez.
- UX personalizada. Use o método
adsenseEmbeddedConnect.connect(...)
do Embedded Connect, que aciona o fluxo de inscrição em uma nova janela. Essa opção fornece um retorno de chamada com o ID do editor do Google AdSense e um token de acesso, que pode ser usado para buscar informações adicionais da conta do Google AdSense usando a API AdSense Management. Essa opção exige que você mesmo projete a UX.
Implementação de uma conexão incorporada
Para usar o Embedded Connect, siga estas etapas:
- Criar um projeto no Google Cloud (ou usar um atual)
- Criar um ID do cliente OAuth
- Configurar o ID do cliente OAuth para uso com o Embedded Connect
- (Opcional) Personalizar a tela de permissão OAuth
- Adicionar a biblioteca JavaScript do Embedded Connect à página
- Implementar o código do Embedded Connect
Etapa 1: criar um novo projeto do Google Cloud (ou usar um atual)
Se você já tiver um projeto do Google Cloud, fique à vontade para usá-lo. Caso contrário, siga o guia abaixo sobre como configurar um novo projeto:
https://cloud.google.com/resource-manager/docs/creating-managing-projects
Etapa 2: criar um ID do cliente OAuth
Os projetos do Google Cloud terão um ID do cliente OAuth padrão para você usar. Para isso, acesse APIs e serviços > Credenciais.
Se você quiser criar um ID do cliente OAuth dedicado, siga estas etapas:
- Acesse APIs e serviços > Credenciais
- Clique em "+ Criar credenciais" na parte de cima da página e selecione o ID do cliente OAuth
- O tipo de aplicativo será "aplicativo da Web"
- Nomeie seu ID de cliente e clique em "Criar"
Etapa 3: configurar o ID do cliente OAuth para uso com o Embedded Connect
Depois de decidir qual ID do cliente OAuth você quer usar para a integração do Embedded Connect, é preciso configurá-lo.
Siga estas etapas:
- Na página Credenciais, clique no ícone de lápis do ID do cliente que você quer configurar.
- Na seção Origens JavaScript autorizadas, adicione os URIs autorizados a emitir solicitações usando seu ID do cliente. Normalmente, são adicionados URIs para seu servidor de desenvolvimento e ambiente local (por exemplo, https://dev.example.com e http://localhost:5000). Além disso, é preciso adicionar um URI para o ambiente de produção (por exemplo, https://example.com)
(Opcional) Etapa 4: personalizar a tela de permissão OAuth
A tela de permissão OAuth é onde os usuários concederão ao seu ID de cliente acesso aos dados dele do Google AdSense. Essa é uma parte essencial do funcionamento do Embedded Connect. Você pode personalizar essa tela para incluir o nome da sua plataforma, seu logotipo etc. Acesse a página Tela de permissão OAuth para configurar as personalizações. Clique em "Editar aplicativo" na parte superior da página e siga o assistente.
Etapa 5: implementar a biblioteca JavaScript do Embedded Connect
Essa biblioteca contém os diversos métodos usados para iniciar a conexão incorporada e fornece os callbacks necessários para recuperar e esquecer o ID de editor do usuário. Implemente isso no cabeçalho da página.
Para UX gerenciada pelo Google:
<script src="https://www.google.com/adsense/js/embedded-connect.js?load=initEmbeddedConnect&hl={language}" async defer></script>
Para UX personalizada:
<script src="https://www.google.com/adsense/js/embedded-connect.js?load=initEmbeddedConnect&hl={language}&headless=true" async defer></script>
Forneça uma implementação para o nome da função JavaScript transmitido
no parâmetro load
. A função será chamada quando a API adsenseEmbeddedConnect
estiver pronta para uso.
Atributos da tag de script
Observe no exemplo acima que vários atributos são definidos na tag de script. Confira a seguir uma explicação de cada atributo.
src
: o URL de onde a API Embedded Connect é carregada. O URL pode conter vários parâmetros de consulta, documentados abaixo.async
: solicita que o navegador faça o download e execute o script de forma assíncrona. Quando o script é executado, ele chama a função especificada usando o parâmetroload
.defer
: quando definido, o navegador fará o download do JavaScript do Embedded Connect em paralelo para analisar a página e o executará após o término da análise da página.
Parâmetros src
O atributo src
contém vários parâmetros de consulta necessários para iniciar a conexão incorporada. Confira abaixo o uso de cada parâmetro.
load
é o nome de uma função JavaScript global que será chamada quando a API for carregada completamente. É possível escolher qualquer nome para essa função.hl
especifica o idioma a ser usado para todas as localizações, incluindo, por exemplo, o texto no pop-up de inscrição. É um parâmetro de consulta opcional e, quando não estiver presente ou se o idioma não for suportado pelo Google AdSense, o widget usará o inglês americano por padrão. Veja os idiomas compatíveis com o Google AdSense. O valor do parâmetrohl
precisa seguir BCP 47. Por exemplo, para usuários do inglês britânico, a string seráen-GB
.headless=true
indica que o Embedded Connect será usado com a opção de UX personalizada em vez da UX gerenciada pelo Google.
Agora que você escolheu entre a UX gerenciada pelo Google e a personalizada, veja os exemplos de código para cada abordagem abaixo.
Etapa 6: implementar o código do Embedded Connect
Conforme dito acima, há duas opções de experiência do usuário:
Escolha a opção de implementação que melhor atenda às necessidades da sua plataforma.
UX gerenciada pelo Google
Siga estas etapas para que o Google renderize o widget que aciona o fluxo de inscrição e mostra ao usuário informações relevantes sobre o estado da conta e do site.
Há dois componentes do código do Embedded Connect. A primeira é um <div>
vazio que especifica onde o Embedded Connect deve renderizar o widget de inscrição. O segundo é o código em que as configurações são definidas e os callbacks são gerenciados.
O elemento HTML em que o widget do Embedded Connect é renderizado
Coloque este HTML na página em que deseja que o widget do Embedded Connect seja renderizado:
<div id="adsenseEmbeddedConnect"></div>
Código do Embedded Connect
Em seguida, abaixo da biblioteca Embedded Connect, mas acima do elemento div, insira o código de configuração:
function initEmbeddedConnect() {
adsenseEmbeddedConnect.init({
// <div> to show the Embedded Connect widget in
'divId': 'adsenseEmbeddedConnect',
// OAuth client ID from step 2
'clientId': 'xxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com',
// Access token from the Google Identity APIs, see
// https://developers.google.com/identity/oauth2/web/guides/use-token-model
// Use the following scope when requesting the access token:
// https://www.googleapis.com/auth/adsense.readonly
'accessToken': 'xxxxxxxxxxxxxxxxxxxxxxx',
// Login hint, an optional parameter which suppresses the account
// chooser and either pre-fills the email box on the sign-in form,
// or selects the proper session (if the user is using multiple
// sign-in)
'loginHint': 'user@example.com',
// Child site (which is added to AdSense as part of the Embedded Connect flow)
// Consult with your account manager to ensure this value is set correctly for your platform
'siteUrl': 'site.example.com',
// Optional parameter, the publisher ID of the user.
// When set, the Embedded Connect widget will display the state of the user's AdSense account.
// When unset, the Embedded Connect widget will show the default state which triggers the connection flow.
'publisherId': "pub-0000000000000000",
'onConnect': function(pid) {
// Your custom code to send the publisher ID (pid) to your server for it to be saved.
// The onConnect function is called when the user has completed all the onboarding steps
},
'onDisconnect': function() {
// Your custom code to forget the publisher ID.
// This onDisconnect function is called when the user has clicked the "Disconnect" button in the Embedded Connect widget
},
});
};
Capturas de tela
O widget Conexão incorporada tem quatro estados principais:
- (Padrão) Conectar ao Google AdSense
- Como se conectar ao Google AdSense
- Revisando as informações do site
- Problemas foram detectados
1. (Padrão) Conectar ao Google AdSense
Esse é o estado padrão, mostrado aos usuários quando o campo publisherId
no código do Embedded Connect não está presente. Ele inicia o fluxo de conexão (pop-up) e, após a conclusão bem-sucedida do fluxo pelo usuário, acionará o callback onConnect
.
2. Como se conectar ao Google AdSense
Esse estado é mostrado aos usuários quando eles iniciam o fluxo de conexão (e o pop-up está presente). Após o fechamento do pop-up ou a conclusão do fluxo, esse estado é alterado para um dos outros estados.
3. Revisando as informações do site
Quando um novo site é enviado ao Google AdSense, ocorre um processo de revisão. Os anúncios não podem ser veiculados durante esse período.
Um componente crítico da revisão é a verificação de propriedade, que pode ser aprovada de várias maneiras, incluindo:
- o ID do editor da conta filha está presente no arquivo ads.txt
- o ID do editor da conta filha está presente em uma tag de anúncio no site do usuário
- a metatag google-adsense-child-account está presente no site do usuário. Para melhores resultados, verifique se ele está presente na página inicial do site do usuário.
A melhor abordagem dependerá da estrutura do seu URL e de alguns outros fatores. Consulte o gerente de contas para saber qual é a melhor abordagem para sua plataforma.
4. Problemas foram detectados
Se a conta ou o site do usuário tiver algum problema que precise ser resolvido, esse estado será mostrado aos usuários.
UX personalizada
Siga estas etapas se quiser gerenciar a UX por conta própria e use chamadas de API para acionar o método de inscrição manualmente.
Biblioteca JavaScript de conexão incorporada
Para usar a opção de UX personalizada, o parâmetro headless=true
precisa ser definido no atributo src
. Exemplo:
<script src="https://www.google.com/adsense/js/embedded-connect.js?load=initEmbeddedConnect&hl={language}&headless=true" async defer></script>
Fornecer os botões conectar e desconectar
Quando a API adsenseEmbeddedConnect
estiver pronta para uso, conforme verificado pela
função JavaScript transmitida ao parâmetro load
, forneça uma implementação
para se conectar e desconectar do Google AdSense. Por exemplo, fornecendo dois
botões:
<button onclick="connectAdSense()">Connect to AdSense</button>
<button onclick="disconnectAdSense()">Disconnect account</button>
É possível escolher qual botão exibir, dependendo se você salvou ou não um ID do editor do seu usuário.
O código de conexão
function connectAdSense(){
adsenseEmbeddedConnect.connect({
// OAuth client ID
'clientId': 'xxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com',
// Access token from the Google Identity APIs, see
// https://developers.google.com/identity/oauth2/web/guides/use-token-model
// Use the following scope when requesting the access token:
// https://www.googleapis.com/auth/adsense.readonly
'accessToken': 'xxxxxxxxxxxxxxxxxxxxxxx',
// Child site (which is added to AdSense as part of the Embedded Connect flow)
// Consult with your account manager to ensure this value is set correctly for your platform
'siteUrl': 'site.example.com',
'onConnect': function(response) {
// Your custom code to send the publisher ID (response[publisherId]) to your server for it to be saved.
// The onConnect function is called when the user has completed all the onboarding steps
// Note that you'll additionally receive an OAuth2 access token (response[token]) which can be used with the AdSense Management API to perform other operations
},
'onCancel': function() {
// This callback is called if the user closes the popup window without completing the sign-up flow
}
});
}
O código de desconexão
function disconnectAdSense(){
// Your custom code to forget the publisherId from your server.
}