Cómo empezar

Este documento va dirigido a los programadores que quieran usar AdSense Host API para obtener información sobre su cuenta de AdSense. En este documento se supone que estás familiarizado con los conceptos de programación web y los formatos de datos web.

Índice

Antes de empezar

Cómo obtener una cuenta de AdSense

Necesitas una cuenta de AdSense para realizar pruebas. Si ya tienes una cuenta de prueba, no necesitas nada más; puedes acceder a la interfaz de usuario de AdSense para configurar, modificar o ver tus datos de prueba.

Cómo familiarizarse con AdSense

Si no estás familiarizado con los conceptos de AdSense, consulta la información de introducción sobre AdSense y experimenta con la interfaz de usuario antes de empezar a codificar.

Cómo registrar la aplicación

Para usar AdSense Host API, debes registrar la aplicación que estás programando con Google:

  1. Ve a la consola de las API.
  2. Inicia sesión en tu cuenta de Google o crea una cuenta.
  3. Crea un nuevo proyecto.
  4. En el proyecto recién creado, haz clic en el enlace "Request access" debajo de AdSense Host API.

Para las aplicaciones OAuth 2.0, sigue los pasos adicionales que se describen en Uso de OAuth 2.0 para acceder a las API de Google.

Nota: La cuenta de Google empleada para el registro debe ser tu cuenta de programador, es decir, la cuenta que quieres que los usuarios de tu aplicación vean como el programador de la aplicación. Esta cuenta no es necesario que esté vinculada a datos de acceso de AdSense, ya que a los usuarios se les concederá acceso a sus propias cuentas mientras usan la aplicación.

Descripción de AdSense Host API

Conceptos básicos

AdSense Host API se basa en algunos conceptos de AdSense básicos:

  • Clientes publicitarios: los clientes publicitarios representan una asociación entre una cuenta de AdSense y un producto de AdSense, como los anuncios de la Red de Display o los anuncios de la red de búsqueda. Una cuenta de AdSense puede tener uno o varios clientes publicitarios.
  • Canales: son herramientas que permiten realizar el seguimiento del rendimiento de una determinada página o dominio.
  • Informes: ofrecen estadísticas sobre los ingresos que obtienes, así como lo que afecta a dichos ingresos. Se pueden ejecutar en una cuenta completa o en un subconjunto del inventario, a través del uso de criterios de seguimiento.

Operaciones admitidas

Las operaciones que actualmente admite la API se describen en la tabla siguiente.

Operación Descripción Asignaciones de REST HTTP
list Enumera todos los recursos de una colección. GET en un URI de colección.
get Obtiene un recurso específico. GET en un URI de recurso.
generate Genera un conjunto de resultados basado en un recurso específico. Solo se usa para informes. GET/POST en un URI de colección, donde se pasa el recurso como una definición para la generación.

Todas las operaciones requieren autenticación.

Estilo de llamada

REST es un estilo de arquitectura de software que proporciona un planteamiento cómodo y coherente para solicitar y modificar datos.

El término REST es la abreviatura en inglés de "Representational State Transfer" (transferencia de estado representacional). En el contexto de las API de Google, hace referencia al uso de verbos HTTP para recuperar y modificar representaciones de datos almacenados por Google.

En un sistema que utiliza REST, los recursos se guardan en un almacén de datos; un cliente envía una solicitud para que el servidor realice una determinada acción (como crear, recuperar, actualizar o suprimir un recurso) y el servidor lleva a cabo la acción y envía una respuesta, normalmente como una representación del recurso especificado.

En las API de Google que utilizan REST, el cliente especifica una acción mediante un verbo HTTP, como POST, GET, PUT o DELETE. Especifica un recurso mediante un URI único globalmente con el siguiente formato:

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

Debido a que todos los recursos de la API tienen URI accesibles mediante HTTP, REST habilita el almacenamiento en caché de los datos y está optimizado para trabajar con la infraestructura distribuida de la Web.

Para obtener más información sobre REST, estos documentos de terceros te pueden resultar útiles:


REST en AdSense Host API

Las operaciones compatibles se asignan directamente a verbos HTTP de REST, tal como se describe en Operaciones de AdSense Host API.

El formato específico para los URI de AdSense Host API es:

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

donde resourceID es el identificador de un cliente publicitario, criterio de seguimiento de URL, criterio de seguimiento personalizado o la colección de informes, y parameters corresponde a los parámetros que se aplican a la consulta.

El formato de las extensiones de ruta de resourceID te permiten identificar el recurso en el que operas actualmente, por ejemplo:

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

El conjunto completo de los URI empleados para cada operación admitida en el API se resume en el documento Referencia de AdSense Host API.

A continuación, te ofrecemos un ejemplo de cómo funciona en AdSense Host API.

Lista de clientes publicitarios:

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

Formato de datos

JSON (JavaScript Object Notation, Notación de objetos JavaScript) es un formato de datos común e independiente del lenguaje que proporciona una representación de texto simple de estructuras de datos arbitrarios. Para obtener más información, consulta json.org.

Cómo realizar solicitudes

Cómo autorizar solicitudes

Cada solicitud que tu aplicación envíe a AdSense Host API debe incluir un token de autorización. El token también identifica tu aplicación en Google.

Acerca de los protocolos de autorización

Tu aplicación debe utilizar OAuth 2.0 para autorizar las solicitudes. No se admite ningún otro protocolo de autorización.

Cómo autorizar solicitudes con OAuth 2.0

Todas las solicitudes a AdSense Host API las debe autorizar un usuario autenticado.

Los detalles del proceso de autorización, o "flujo", para OAuth 2.0 varían dependiendo del tipo de aplicación que estés escribiendo. El siguiente proceso general se aplica a todos los tipos de aplicación.

  1. Cuando hayas creado tu aplicación, regístrala utilizando Google Developers Console. A continuación, Google le proporcionará la información que necesitará posteriormente, como un ID de cliente y un secreto de cliente.
  2. Activa AdSense Host API en Google Developers Console (si no aparece en la consola, omite este paso).
  3. Cuando tu aplicación deba acceder a los datos de usuario, pedirá a Google un determinado ámbito de acceso.
  4. Google muestra una pantalla de consentimiento al usuario pidiéndole su autorización para que la aplicación le solicite algunos datos.
  5. Si el usuario aprueba esta petición, Google ofrecerá a la aplicación un token de acceso de corta duración.
  6. Tu aplicación solicita los datos del usuario y adjunta el token de acceso a la solicitud.
  7. Si Google determina que tu solicitud y el token son válidos, muestra los datos solicitados.

Algunos flujos incluyen pasos adicionales, como el uso de tokens de actualización para adquirir nuevos tokens de acceso. Para obtener información detallada sobre los flujos de distintos tipos de aplicaciones, consulta la documentación de OAuth 2.0 de Google.

A continuación, te indicamos la información de ámbito de OAuth 2.0 para AdSense Host API:

Alcance Significado
https://www.googleapis.com/auth/adsensehost Acceso de lectura/escritura a los datos de AdSense.

Para solicitar el acceso con OAuth 2.0, la aplicación necesita la información del alcance, así como la información que proporciona Google durante el registro de la aplicación (como el ID o la clave secreta del cliente).

Consejo: Las bibliotecas cliente de las API de Google pueden gestionar algunos de los procesos de autorización de forma automática. Están disponibles para varios lenguajes de programación; consulta la página con bibliotecas y ejemplos para obtener más detalles.

Consulta la sección de OAuth 2.0 para obtener más información.

Cómo realizar una solicitud

El paso final es realizar una solicitud del API. Si no utilizas ninguna biblioteca cliente, puedes consultar la documentación de referencia.

Si usas las bibliotecas cliente, esta tarea es considerablemente más sencilla. Consulta Ejemplos y bibliotecas para obtener una guía completa de cómo realizar tu primera solicitud con la biblioteca cliente Java, Python, PHP o JavaScript.

OAuth 2.0

La autenticación y la autorización en AdSense Host API se gestionan mediante OAuth 2.0. No obstante, debido a una serie de particularidades del modelo de uso de AdSense Host, la gestión puede ser ligeramente distinta a lo habitual en otras API de Google.

Participantes

En una solicitud de OAuth 2.0 intervienen tres entidades:

  • el usuario, que concede acceso a los datos personales,
  • el programador, que solicita acceso a los datos de usuario a través de la aplicación,
  • Google, que autentica a ambas partes y proporciona el acceso a la API.

No obstante, en el caso de AdSense Host API, el usuario y el programador son, en realidad, la misma persona, ya que como programador utilizarás la API para obtener acceso a tu cuenta de AdSense y, a través de ella, a las cuentas de tus editores.

Cómo crear un proyecto

Puedes crear nuevos proyectos en tu página de consola de las API.
Figura 1: Nuevo proyecto en la consola de las API

Antes de empezar, deberás crear un nuevo proyecto en tu consola de las API, del mismo modo que con cualquier API de Google que emplees. La cuenta de Google que uses para crear el proyecto de programador debe estar incluida en la lista blanca para acceder a AdSense Host API, por lo que te debes asegurar de que usas la cuenta de zona de pruebas que hemos creado automáticamente durante el registro o tu cuenta de AdSense de producción si ya has finalizado la implementación de la versión 4.x y has pasado a la fase activa.

La pestaña "Services" (Servicios) permite elegir las API activas en tu proyecto.
Figura 2: API habilitadas e inhabilitadas de un proyecto

En la documentación de la consola de las API puedes encontrar más información sobre la creación de proyectos de las API de Google.

Cómo configurar el acceso a la API

Cuando tengas un proyecto, debes habilitar el acceso a la API en él mediante la creación de un ID de cliente de OAuth 2.0.

Podrás crear clientes OAuth 2.0 en la pestaña "API Access" (Acceso a la API).
Figura 3: Creación de un nuevo cliente de OAuth 2.0 en la consola de las API

Dispones de varias opciones, pero te recomendamos que crees un proyecto Aplicación instalada, ya que facilita los siguientes pasos.

Autenticar una vez, almacenar para siempre

Ahora deberás autenticarte con tu propia cuenta de AdSense, lo que puedes hacer con una pequeña secuencia de comandos o una aplicación de prueba (consulta los ejemplos en nuestro código de ejemplo).

Después de autenticarte, asegúrate de almacenar el token de actualización que has obtenido del paso de autorización. Se trata de un token de larga duración que no caducará a menos que el acceso se revoque de forma explícita y, como tú eres el usuario, no revocarás el acceso a tu propia aplicación.

Debes guardar el token de actualización en el almacén de datos de tu aplicación para todas las solicitudes de autenticación futuras.

Cómo usar el token guardado en tu aplicación

Una vez que tengas un token de actualización, ya no importa si se ha generado en un flujo Aplicación de servidor web o Aplicación instalada. Puedes usarlo simplemente para realizar solicitudes de actualización de token para nuevos tokens de acceso según sea necesario. Si usas una de nuestras bibliotecas cliente, consulta en la documentación cómo especificar tus propios tokens; es posible que debas editar un archivo generado de forma automática o una entrada de base de datos.

Conclusión

El resultado final es que el flujo de OAuth 2.0 solo se ejecuta una vez y, después de eso, todas las solicitudes se producen en segundo plano, sin intervención manual por parte del usuario final de tu sitio (el editor) o por tu parte, como programador.

Avisos

Mantente informado de las nuevas versiones, funciones y actualizaciones de los servicios importantes a través de los avisos de AdSense API.

Enviar comentarios sobre…