Conexión incorporada

Embedded Connect reduce la fricción y mejora el embudo de conversión cuando los usuarios intentan conectar AdSense con tu plataforma.

Embedded Connect es una pequeña biblioteca de JavaScript que determina el mejor punto de partida para un usuario determinado y lo guía a través de un flujo de registro personalizado de AdSense que los ayuda con todos los pasos necesarios para publicar anuncios. Se controlan situaciones, como determinar si el usuario tiene una cuenta de AdSense, si firmó los Términos y Condiciones de AdSense, si agregó su sitio de plataforma a su cuenta de AdSense y si el estado del sitio es "Listo".

El complemento de Connect con la opción de UX administrada por Google también puede manejar la UX que se requiere para mostrar a los usuarios los estados de la cuenta y el sitio, lo que los guía al lugar correcto en AdSense para resolver cualquier problema potencial.

Para ayudar a la experiencia del desarrollador, la biblioteca también emite devoluciones de llamada a tu plataforma que contienen el ID de publicador de AdSense del usuario, que es necesario para configurar correctamente la publicación de anuncios.

Embedded Connect ofrece dos opciones de experiencia del usuario:

• UX administrada por Google. Usa el widget de Embedded Connect, que administra toda la UX. El widget ayudará a los usuarios a través de un flujo de registro y mostrará a los usuarios información acerca del estado de su cuenta y sitio dentro del widget. Esta opción proporciona una devolución de llamada con el ID de publicador de AdSense que se activa cuando el usuario conecta una cuenta de AdSense por primera vez.
• UX personalizada. Usa el método adsenseEmbeddedConnect.connect(...) de Embedded Connect, que activa el flujo de registro en una ventana nueva. Esta opción proporciona una devolución de llamada con el ID de publicador de AdSense y un token de acceso que se puede usar para obtener información adicional de la cuenta de AdSense mediante la API de AdSense Management. Esta opción requiere que diseñes la UX tú mismo.

Cómo implementar Embedded Connect

Para usar Embedded Connect, debes seguir estos pasos:

1. Crea un proyecto en Google Cloud (o usa uno existente)
2. Crea un ID de cliente de OAuth
3. Cómo configurar tu ID de cliente de OAuth para usarlo con Embedded Connect
4. Personaliza la pantalla de consentimiento de OAuth (opcional)
5. Agrega la biblioteca de JavaScript incorporada de Connect a la página
6. Cómo implementar el código de Embedded Connect

Paso 1: Crea un proyecto de Google Cloud nuevo (o usa uno existente)

Si ya tienes un proyecto de Google Cloud, puedes usarlo. De lo contrario, sigue la guía a continuación sobre cómo configurar un proyecto nuevo:

https://cloud.google.com/resource-manager/docs/creating-managing-projects

Paso 2: Crea un ID de cliente de OAuth

Los proyectos de Google Cloud tendrán un ID de cliente de OAuth predeterminado que puedes usar. Para encontrarlo, visita APIs y servicios > Credenciales.

Si quieres crear un ID de cliente de OAuth exclusivo, sigue estos pasos:

• Ve a APIs y servicios > Credenciales.
• Haz clic en "+ Crear credenciales" en la parte superior de la página y, luego, selecciona el ID de cliente de OAuth.
• El tipo de aplicación será "Aplicación web"
• Asígnale un nombre a tu ID de cliente y haz clic en "Crear".

Paso 3: Configura tu ID de cliente de OAuth para usarlo con Embedded Connect

Una vez que decidas qué ID de cliente de OAuth quieres usar para la integración de Embedded Connect, deberás configurarlo.

Lleve a cabo los pasos siguientes:

• En la página Credenciales, haz clic en el ícono de lápiz del ID de cliente que deseas configurar.
• En la sección Orígenes autorizados de JavaScript, agrega los URIs autorizados para emitir solicitudes con tu ID de cliente. Normalmente, se agregan los URI para tu servidor de desarrollo y entorno local (p.ej., https://dev.example.com y http://localhost:5000). Además, debes agregar un URI para tu entorno de producción (p.ej., https://example.com)

Paso 4: Personaliza la pantalla de consentimiento de OAuth (opcional)

La pantalla de consentimiento de OAuth es donde los usos le otorgarán a tu ID de cliente acceso a sus datos de AdSense. Esta es una parte esencial del funcionamiento de Embedded Connect. Puedes personalizar esta pantalla para incluir el nombre de tu plataforma, tu logotipo, etc. Visita la página Pantalla de consentimiento de OAuth para configurar tus personalizaciones. Haz clic en "Editar app" en la parte superior de la página y sigue el asistente.

Paso 5: Implementa la biblioteca de JavaScript incorporada de Connect

Esta biblioteca contiene los diversos métodos que se usan para iniciar la conexión incorporada y proporcionarte las devoluciones de llamada necesarias para que recuperes y olvides el ID de publicador del usuario. Impleméntalo en el encabezado de la página.

Para UX administrada por 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>

Asegúrate de proporcionar una implementación para el nombre de la función de JavaScript que se pasó al parámetro load. Se llamará a la función cuando la API de adsenseEmbeddedConnect esté lista para usarse.

Atributos de la etiqueta de secuencia de comandos

Observa en el ejemplo anterior que se configuraron varios atributos en la etiqueta de la secuencia de comandos. A continuación, se incluye una explicación de cada atributo.

• src: Es la URL desde la que se carga la API de Embedded Connect. La URL puede contener varios parámetros de consulta, los que se documentan a continuación.
• async: Solicita al navegador que descargue y ejecute la secuencia de comandos de manera asíncrona. Cuando se ejecute la secuencia de comandos, llamará a la función especificada mediante el parámetro load.
• defer: Cuando se configura, el navegador descargará el código JavaScript de Embedded Connect en paralelo para analizar la página y lo ejecutará después de que haya terminado de analizarse.

Parámetros src

El atributo src contiene varios parámetros de consulta que son necesarios para iniciar la conexión incorporada. Consulta a continuación el uso de cada parámetro.

• load es el nombre de una función global de JavaScript a la que se llamará cuando la API se cargue por completo. Puedes elegir cualquier nombre para esta función.
• hl especifica el idioma que se usará para toda la localización, incluido, por ejemplo, el texto que se muestra en la ventana emergente de registro. Es un parámetro de búsqueda opcional y, cuando no está presente, o si el idioma no es compatible con AdSense, el widget se establecerá de forma predeterminada en inglés de EE.UU. Consulta los idiomas que AdSense admite. El valor del parámetro hl debe seguir BCP 47. Por ejemplo, para los usuarios que hablan inglés británico, la cadena será en-GB.
• headless=true indica que Embedded Connect se usará con la opción de UX personalizada en lugar de la UX administrada por Google.

Nota: La biblioteca de JavaScript de Embedded Connect solo responderá con un estado 200 si Google incluyó el URI en el que se carga. De lo contrario, la solicitud se rechazará con un código 403. Por ejemplo, si quieres usar la biblioteca de JavaScript de Embedded Connect en console.example.com, Google debe incluir ese URI en la lista de entidades permitidas para que se cargue la biblioteca. Comunícate con tu administrador de cuentas para resolver el problema en tu plataforma. Del mismo modo, se mostrará el error 403 si intentas llamar a Embedded Connect desde una URL con el protocolo HTTP (usa HTTPS).

Ahora que elegiste entre la UX administrada por Google y la UX personalizada, a continuación, observa los ejemplos de código para cada enfoque.

Paso 6: Implementa el código de Embedded Connect

Como se mencionó anteriormente, hay dos opciones para la experiencia del usuario:

• UX administrada por Google
• UX personalizada

Elige la opción de implementación que mejor se adapte a las necesidades de tu plataforma.

UX administrada por Google

Sigue estos pasos para que Google renderice el widget que activa el flujo de registro y muestra al usuario información relevante sobre el estado de su cuenta y su sitio.

Hay dos componentes del código de Embedded Connect. El primero es un elemento <div> vacío que especifica dónde debe renderizar el widget de registro Embedded Connect. Y el segundo es el código en el que se establecen las configuraciones y se administran las devoluciones de llamada.

El elemento HTML en el que se renderiza el widget de Connected Connect

Coloca este código HTML en la página donde quieres que se renderice el widget de Embedded Connect:

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

El código de Embedded Connect

A continuación, debajo de la biblioteca Embedded Connect, pero sobre el elemento div, coloca el código de configuración:

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 pantalla

El widget de Embedded Connect tiene cuatro estados principales:

1. Conectar a AdSense (predeterminado)
2. Conéctate a AdSense
3. Revisa la información del sitio
4. Se detectaron problemas

1. Conectar a AdSense (predeterminado)

Este es el estado predeterminado que se muestra a los usuarios cuando no está presente el campo publisherId en el código de Embedded Connect. Inicia el flujo de conexión (ventana emergente) y, cuando el usuario completa con éxito el flujo, activa la devolución de llamada onConnect.

2. Conéctate a AdSense

Este estado se muestra a los usuarios cuando inician el flujo de conexión (y la ventana emergente está presente). Cuando se cierra la ventana emergente o se completa el flujo, este estado se cambia a uno de los otros.

3. Revisa la información del sitio

Una vez que se envíe un sitio nuevo a AdSense, se llevará a cabo un proceso de revisión. No se pueden publicar los anuncios durante este período.

Un componente fundamental de las opiniones es una verificación de propiedad, que puede aprobarse de varias maneras, como las siguientes:

• El ID de publicador de la cuenta secundaria está presente en el archivo ads.txt
• El ID de publicador de la cuenta secundaria está presente en una etiqueta de anuncio del sitio del usuario
• Que la metaetiqueta google-adsense-child-account esté presente en el sitio del usuario. Para obtener los mejores resultados, asegúrate de que esté presente en la página principal del sitio del usuario.

El mejor enfoque dependerá de la estructura de tu URL y de otros factores. Consulta a tu administrador de cuentas a fin de obtener el mejor enfoque para tu plataforma.

4. Se detectaron problemas

En caso de que la cuenta o el sitio del usuario tenga algún problema que deba resolverse, este estado se mostrará a los usuarios.

UX personalizada

Sigue estos pasos si quieres administrar la UX por tu cuenta y usa llamadas a la API para activar el método de registro de forma manual.

La biblioteca de JavaScript de Embed Connect

Para usar la opción de UX personalizada, el parámetro headless=true debe establecerse en el atributo src. Por ejemplo:

<script src="https://www.google.com/adsense/js/embedded-connect.js?load=initEmbeddedConnect&hl={language}&headless=true" async defer></script>

Proporciona botones para conectar y desconectar

Una vez que la API de adsenseEmbeddedConnect esté lista para usar (como lo verifica la función de JavaScript que se pasó al parámetro load), proporciona una implementación para conectarse y desconectarse de AdSense. Por ejemplo, proporcionando dos botones:

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

Puedes elegir qué botón mostrar según si el usuario tiene guardado un ID de publicador.

El código de conexión

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
        }
    });
}

El código de desconexión

function disconnectAdSense(){
    // Your custom code to forget the publisherId from your server.
}