Primeiros passos

Este documento se destina a desenvolvedores que desejam usar a AdSense Host API para informações sobre sua conta do Google AdSense. Ele pressupõe que você esteja familiarizado com conceitos de programação da Web e formatos de dados da Web.

Índice

Antes de começar

Consulte uma conta do Google AdSense

Você precisa de uma conta do Google AdSense para fins de teste. Se você já tiver uma conta de teste, então está tudo pronto. Você poderá visitar a interface do usuário do Google AdSense para configurar, editar ou visualizar os dados de teste.

Familiarize-se com o Google AdSense

Se você não tem familiaridade com os conceitos do Google AdSense, leia as informações introdutórias sobre o Google AdSense e teste a interface do usuário antes de começar a codificar.

Registre seu aplicativo

Para usar a AdSense Host API, você deve registrar o aplicativo que está desenvolvendo com o Google:

  1. Vá para o Console de APIs.
  2. Faça login em sua Conta do Google ou crie uma conta.
  3. Crie um novo projeto.
  4. Em seu projeto recém-criado, clique no link "Solicitar acesso" na AdSense Host API.

Para aplicativos OAuth 2.0, siga as etapas adicionais descritas em Uso do OAuth 2.0 para acessar as APIs do Google.

Observação: a Conta do Google usada para registro deve ser sua conta de desenvolvedor, ou seja, a conta que você deseja que os usuários de seu aplicativo vejam como o desenvolvedor do aplicativo. Essa conta não precisa estar vinculada a um login do Google AdSense, já que os usuários concederão acesso a suas próprias contas ao usar o aplicativo.

Noções básicas sobre a AdSense Host API

Conceitos básicos

A AdSense Host API foi desenvolvida com base em alguns conceitos básicos do Google AdSense:

  • Clientes de anúncios: os clientes de anúncios representam uma associação entre uma conta do Google AdSense e um produto do Google AdSense, como anúncios de conteúdo ou anúncios da Rede de Pesquisa. Uma conta do Google AdSense pode ter um ou vários clientes de anúncios.
  • Canais: os canais são ferramentas que permitem acompanhar o desempenho de uma página ou um domínio específico.
  • Relatórios: os relatórios oferecem informações sobre seus ganhos, bem como o que afeta esses ganhos. Eles podem ser gerados em uma conta inteira ou em um subconjunto de seu inventário por meio do uso de canais.

Operações compatíveis

As operações aceitas no momento pela API estão descritas na tabela abaixo.

Operação Descrição Mapeamentos de HTTP REST
list Lista todos os recursos em um conjunto. GET em um URI de coleta.
get Adquire um recurso específico. GET em um URI de recurso.
generate Gera um grupo de resultados com base em um recurso especificado. Usado apenas para relatórios. GET/POST em um URI de coleção, onde você transmite o recurso como uma definição para a geração.

Todas as operações exigem autenticação.

Estilo de chamada

REST é um estilo de arquitetura de software que fornece uma abordagem conveniente e consistente para a solicitação e modificação de dados.

O termo REST significa "Transferência de estado de representação". No contexto das APIs do Google, ele se refere ao uso de verbos HTTP para adquirir e modificar representações de dados armazenados pelo Google.

Em um sistema RESTful, recursos são armazenados em um armazenamento de dados. Um cliente envia uma solicitação para o servidor realizar determinada ação (como criar, adquirir, atualizar ou excluir um recurso) e o servidor realiza a ação e envia uma resposta, geralmente na forma de uma representação do recurso especificado.

Nas RESTful APIs do Google, o cliente especifica uma ação usando um verbo HTTP, como POST, GET, PUT ou DELETE. Ele especifica um recurso por meio de um URI único globalmente no seguinte formato:

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

Como todos os recursos de API possuem URIs acessíveis por HTTP exclusivos, REST permite o cache de dados e é otimizado para funcionar com a infraestrutura distribuída da Web.

Para mais informações sobre REST, os documentos de terceiros a seguir podem ser úteis:


REST na AdSense Host API

As operações aceitas são mapeadas diretamente para verbos HTTP REST, conforme descrito em Operações da AdSense Host API.

O formato específico para URIs da AdSense Host API é:

https://www.googleapis.com/adsensehost/v4.1/resourceID?parameters

em que resourceID é o identificador de um cliente de anúncios, critério de URL, critério personalizado ou conjunto de relatórios, e parameters são os parâmetros a serem aplicados à consulta.

O formato das extensões de caminho resourceID permite identificar o recurso em operação no momento, por exemplo:

https://www.googleapis.com/adsensehost/v4.1/adclients
https://www.googleapis.com/adsensehost/v4.1/adclients/adClientId
https://www.googleapis.com/adsensehost/v4.1/adclients/adClientId/urlchannels
...

O grupo completo de URIs usados para cada operação aceita na API é resumido no documento Referência da AdSense Host API.

Veja um exemplo de como isso funciona na AdSense Host API.

Listar clientes de anúncios:

GET https://www.googleapis.com/adsensehost/v4.1/adclients/

Formato de dados

JSON (Notação de Objetos JavaScript) é um formato de dados comum e independente do linguagem, que fornece uma representação de texto simples de estruturas de dados arbitrários. Para mais informações, acesse json.org.

Como fazer solicitações

Como autorizar solicitações

Toda solicitação que seu aplicativo envia para a AdSense Host API deve incluir um token de autorização. O token também identifica seu aplicativo para o Google.

Sobre protocolos de autorização

O aplicativo deve usar o OAuth 2.0 para autorizar solicitações. Não há mais protocolos de autorização compatíveis.

Como autorizar solicitações com o OAuth 2.0

Todas as solicitações para a AdSense Host API devem ser autorizadas por um usuário autenticado.

Os detalhes do processo de autorização, ou "fluxo", para o OAuth 2.0 variam um pouco dependendo do tipo de aplicativo que você está criando. O processo geral a seguir aplica-se a todos os tipos de aplicativo:

  1. Ao criar seu aplicativo, você o registra usando o Google Developers Console. Em seguida, o Google fornece informações que serão usadas posteriormente, como um ID de cliente e um segredo de cliente.
  2. Ative a AdSense Host API no Google Developers Console. Se ela não estiver listada no Developers Console, ignore esta etapa.
  3. Quando seu aplicativo precisar de acesso aos dados do usuário, ele solicitará ao Google um determinado escopo do acesso.
  4. O Google exibirá uma tela de consentimento para o usuário, perguntando se ele autoriza que seu aplicativo solicite alguns dados.
  5. Se o usuário aprovar, o Google concederá a seu aplicativo um token de acesso de curto prazo.
  6. Seu aplicativo solicitará os dados do usuário anexando o token de acesso à solicitação.
  7. Se o Google determinar que sua solicitação e o token são válidos, ele retornará os dados solicitados.

Alguns fluxos incluem etapas adicionais, como usar tokens de atualização para adquirir novos tokens de acesso. Para informações detalhadas sobre fluxos de vários tipos de aplicativo, consulte a documentação do OAuth 2.0 do Google.

Veja as informações de escopo do OAuth 2.0 para a AdSense Host API:

Escopo Significado
https://www.googleapis.com/auth/adsensehost Acesso de leitura/gravação de dados do Google AdSense.

Para solicitar acesso usando o OAuth 2.0, seu aplicativo precisará de informações do escopo, bem como informações fornecidas pelo Google durante o registro do aplicativo (como o ID e o segredo do cliente).

Dica: as bibliotecas cliente das APIs do Google podem cuidar de parte do processo de autorização por você. Elas estão disponíveis para uma série de linguagens de programação. Acesse a página Bibliotecas e exemplos para mais detalhes.

Consulte a seção OAuth 2.0 para mais informações.

Como realizar uma solicitação

A etapa final é fazer a solicitação de API. Se você não estiver usando bibliotecas cliente, acesse a documentação de referência.

Se você estiver usando as bibliotecas cliente, esta tarefa é muito mais fácil. Consulte Exemplos e bibliotecas para um guia completo de como fazer sua primeira solicitação com a biblioteca cliente do Java, Python, PHP ou JavaScript.

OAuth 2.0

A autenticação e a autorização na AdSense Host API são manipuladas pelo OAuth 2.0. No entanto, devido a algumas particularidades do modelo de uso Host do Google AdSense, as coisas podem ser manipuladas de maneira um pouco diferente daquela a que você está acostumado em outras APIs do Google.

Participantes

Existem três entidades envolvidas em uma solicitação OAuth 2.0:

  • o usuário, que está concedendo acesso a dados pessoais
  • o desenvolvedor, que está solicitando acesso aos dados do usuário por meio do aplicativo
  • o Google, que autentica as partes e oferece o serviço de API.

No caso da AdSense Host API, no entanto, o usuário e o desenvolvedor são realmente a mesma pessoa, pois você como desenvolvedor usará a API para conseguir acesso à sua própria conta do Google AdSense e, por meio dela, às contas de seus editores.

Como criar um projeto

Você pode criar novos projetos na sua página do console de APIs.
Figura 1: novo projeto no Console de APIs

Antes de começar, você precisará criar um novo projeto no Console de APIs, assim como faria para qualquer outra Google API que usa. A conta do Google que você usa para criar o projeto do desenvolvedor precisa estar na lista de permissões para o acesso à AdSense Host API. Dessa forma, verifique se você está usando ou a conta sandbox que criamos para você durante a inscrição ou sua conta do Google AdSense de produção, se já tiver concluído a implementação da API e ela estiver ativa.

A guia "Serviços" permite que você escolha as APIs ativas no seu projeto.
Figura 2: APIs ativadas e desativadas para um projeto

Você pode encontrar mais informações sobre como criar projetos de APIs do Google na documentação do Console de APIs.

Como configurar o acesso à API

Quando tiver um projeto, você precisará permitir o acesso à API nele criando um ID do cliente do OAuth 2.0.

Você é capaz de criar clientes OAuth 2.0 na guia "Acesso à API".
Figura 3: como criar um novo cliente OAuth 2.0 no Console de APIs

Você tem várias opções aqui, mas recomendamos que crie um projeto Aplicativo instalado, pois facilita as próximas etapas.

Autentique uma vez, guarde para sempre

Você precisa se autenticar usando sua própria conta do Google AdSense. Você pode fazer isso com um pequeno script ou um aplicativo de teste (confira nosso código de exemplo para ver exemplos).

Após a autenticação, não se esqueça de guardar o token de atualização que você recebeu na etapa de autorização. Esse é um token de longa duração, que não expira, a menos que o acesso seja revogado explicitamente. Por ser o usuário, você não deve revogar o acesso aos seus próprios aplicativos.

Você deve salvar o token de atualização no armazenamento de dados de seu aplicativo para todas as futuras solicitações de autenticação.

Uso do token guardado em seu aplicativo

Quando você tiver o token de atualização, não importa mais se ele foi gerado em um fluxo de Aplicativo de servidor da Web ou um fluxo de Aplicativo instalado. Você pode simplesmente usá-lo para fazer solicitações de atualização de token para novos tokens de acesso conforme necessário. Se você estiver usando uma de nossas bibliotecas cliente, verifique a documentação para ver como especificar seus próprios tokens. Pode ser necessário editar um arquivo gerado automaticamente ou uma entrada do banco de dados.

Juntando tudo

Resultado final: o fluxo OAuth 2.0 é executado somente uma vez e, depois, todas as solicitações acontecem em segundo plano, sem qualquer intervenção manual por parte do usuário final de seu site (o editor) ou sua, como desenvolvedor.

Anúncios

Mantenha-se informado sobre novas versões, novos recursos e atualizações de serviços importantes por meio de anúncios da AdSense API.

Enviar comentários sobre…