AdSense for Platforms | Google for Developers

Esta página foi traduzida pela API Cloud Translation.

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 meio de um fluxo de inscrição personalizado do Google AdSense, que o ajuda em todas as etapas necessárias para se tornar capaz de 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 lidar com a UX de mostrar os 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 retornos de chamada para sua plataforma contendo o ID de 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 do Embedded Connect, que gerencia toda a UX. O widget ajudará os usuários em um fluxo de inscrição e mostrará informações do usuário sobre o status da conta e do site dentro do widget. Essa opção fornece um retorno de chamada com o ID do editor do Google AdSense acionado quando o usuário conecta pela primeira vez uma conta do Google AdSense.
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ê crie a UX por conta própria.

Como implementar o Embedded Connect

Para usar o Embedded Connect, você precisa seguir estas etapas:

Crie um projeto no Google Cloud (ou use um projeto existente)
Criar um ID do cliente OAuth
Configurar seu 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 para 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 que pode ser usado. Para encontrar essa informação, acesse APIs e Serviços > Credenciais.

Se você quiser criar um ID de cliente OAuth dedicado, siga estas etapas:

Acesse APIs e Serviços > Credenciais
Clique em "+ Criar credenciais" na parte superior da página e selecione "ID do cliente OAuth"
O tipo do seu aplicativo será "Aplicativo da Web"
Dê um nome ao ID do cliente e clique em "Criar".

Etapa 3: configurar seu ID do cliente OAuth para uso com o Embedded Connect

Depois de decidir qual ID do cliente OAuth quer usar para a integração do Embedded Connect, você precisará 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 que podem emitir solicitações usando seu ID do cliente. Normalmente são adicionados URIs do servidor de desenvolvimento e do ambiente local (por exemplo, https://dev.example.com e http://localhost:5000). Além disso, adicione um URI ao seu 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 o usuário concede ao seu ID de cliente acesso aos dados do Google AdSense dele. Essa é uma parte essencial do funcionamento do Embedded Connect. Você pode personalizar essa tela para incluir o nome da plataforma, seu logotipo etc. Acesse a página Tela de consentimento 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 vários métodos usados para iniciar a conexão incorporada e fornecer os callbacks necessários para que você recupere e esqueça o ID de editor do usuário. Implemente isso na parte superior 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 está pronta para uso.

Atributos da tag do script

Observe no exemplo acima que vários atributos estão definidos na tag do 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, conforme documentado 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âmetro load.
defer: quando definido, o navegador faz o download do JavaScript do Embedded Connect em paralelo à análise da página e o executa após a conclusão da análise da página.

Parâmetros src

O atributo src contém vários parâmetros de consulta necessários para iniciar o Embedded Connect. Veja 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. Você pode escolher qualquer nome para essa função.
O hl especifica o idioma a ser usado em toda a localização, incluindo (por exemplo) o texto no pop-up de inscrição. Ele é um parâmetro de consulta opcional e, quando ausente, ou se o idioma não for compatível com o Google AdSense, o widget usará o inglês americano como padrão. Veja os idiomas compatíveis. O valor do parâmetro hl precisa seguir o BCP 47. Por exemplo, para usuários de 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 abaixo os exemplos de código para cada abordagem.

Etapa 6: implementar o código do Embedded Connect

Como mencionado acima, há duas opções de experiência do usuário:

Escolha a opção de implementação mais adequada à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.

Estado padrão do Embedded Connect

Há dois componentes no código do Embedded Connect. O primeiro é um <div> vazio que especifica onde o Embedded Connect precisa 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 você quer que o widget do Embedded Connect seja renderizado:

<div id="adsenseEmbeddedConnect"></div>

O código do Embedded Connect

Em seguida, abaixo da biblioteca do 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 do Embedded Connect tem quatro estados principais:

(Padrão) Conectar-se ao Google AdSense
Como se conectar ao Google AdSense
Analisando as informações do site
Problemas foram detectados

1. (Padrão) Conectar-se 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 (popup) e, após a conclusão bem-sucedida do fluxo pelo usuário, aciona o callback onConnect.

Estado padrão do Embedded Connect

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.

Embedded Connect: conexão com o Google AdSense

3. Analisando 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.

Conexão incorporada: como revisar as informações do site

Um componente crítico da avaliaçã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 seu 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 problemas que precisem ser resolvidos, esse estado será mostrado aos usuários.

Conexão incorporada: problemas detectados

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.

A biblioteca Embedded Connect JavaScript.

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>

Oferecer botões de conexão e desconexão

Quando a API adsenseEmbeddedConnect estiver pronta para uso, conforme verificado pelo função JavaScript transmitida para o parâmetro load), forneça uma implementação para conectar e desconectar o Google AdSense. Por exemplo, ao fornecer duas botões:

<button onclick="connectAdSense()">Connect to AdSense</button>
<button onclick="disconnectAdSense()">Disconnect account</button>

Dependendo se você tem ou não um ID do editor salvo do seu usuário, é possível escolher qual botão exibir.

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.
}