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:

1. Criar um projeto no Google Cloud (ou usar um atual)
2. Criar um ID do cliente OAuth
3. Configurar o ID do cliente OAuth para uso com o Embedded Connect
4. (Opcional) Personalizar a tela de permissão OAuth
5. Adicionar a biblioteca JavaScript do Embedded Connect à página
6. 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âmetro load.
• 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âmetro hl 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.

Observação: a biblioteca JavaScript do Embedded Connect só responderá com um status 200 se o URI em que está sendo carregado estiver na lista de permissões do Google. Caso contrário, a solicitação será recusada com um código 403. Por exemplo, se você pretende usar a biblioteca JavaScript do Embedded Connect em console.example.com, o Google precisa incluir esse URI na lista de permissões para que a biblioteca seja carregada. Entre em contato com o gerente de contas para resolver isso na sua plataforma. Da mesma forma, o código 403 será retornado se você tentar chamar o Embedded Connect de um URL com o protocolo HTTP (use HTTPS).

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:

• UX gerenciada pelo Google
• UX personalizada

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': '[e-mail]',

        // 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:

1. (Padrão) Conectar ao Google AdSense
2. Como se conectar ao Google AdSense
3. Revisando as informações do site
4. 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.
}