Connessione incorporata

Collegamento incorporato riduce le difficoltà e migliora la canalizzazione di conversione quando gli utenti tentano di collegare AdSense alla tua piattaforma.

Embedded Connect è una piccola libreria JavaScript che determina il miglior punto di partenza per un determinato utente, guidandolo attraverso una procedura di registrazione ad AdSense personalizzata che lo aiuterà a svolgere tutti i passaggi necessari per essere in grado di pubblicare gli annunci. Gestisce scenari, tra cui determinare se l'utente dispone di un account AdSense, se ha firmato i Termini e condizioni di AdSense, se ha aggiunto il sito della tua piattaforma al suo account AdSense e se lo stato del sito è "Pronto".

Collegamento incorporato con l'opzione UX gestita da Google può anche gestire l'esperienza utente necessaria per mostrare all'utente gli stati di account e siti, indirizzandolo alla posizione corretta in AdSense per risolvere eventuali problemi.

Per agevolare l'esperienza degli sviluppatori, la libreria invia anche dei callback alla tua piattaforma contenenti l'ID publisher AdSense dell'utente, necessario per configurare correttamente la pubblicazione degli annunci.

Connessione incorporata offre due opzioni per definire l'esperienza utente:

• UX gestita da Google. Usare il widget Connessione incorporata, che gestisce tutta l'UX. Il widget aiuterà gli utenti nella procedura di registrazione e mostrerà all'utente informazioni sul loro account e sullo stato del sito all'interno del widget. Questa opzione consente di richiamare l'ID publisher AdSense attivato quando l'utente collega per la prima volta un account AdSense.
• UX personalizzata. Utilizza il metodo Collegamento incorporato adsenseEmbeddedConnect.connect(...), che attiva il flusso di registrazione in una nuova finestra. Questa opzione fornisce un callback con l'ID publisher AdSense e un token di accesso che possono essere utilizzati per recuperare ulteriori informazioni dall'account AdSense utilizzando l'API AdSense Management. Questa opzione richiede la progettazione dell'UX personalmente.

Implementazione di Embedded Connect

Per utilizzare Embedded Connect, devi seguire questi passaggi:

1. Crea un progetto in Google Cloud (o utilizzane uno esistente)
2. Creare un ID client OAuth
3. Configurare l'ID client OAuth per l'utilizzo con Embedded Connect
4. (Facoltativo) Personalizzare la schermata per il consenso OAuth
5. Aggiungi la libreria JavaScript Connect incorporato alla pagina
6. Implementare il codice di connessione incorporata

Passaggio 1: crea un nuovo progetto Google Cloud (o utilizzane uno esistente)

Se hai già un progetto Google Cloud, puoi usarlo. In caso contrario, segui la guida riportata di seguito per la configurazione di un nuovo progetto:

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

Passaggio 2: crea un ID client OAuth

I progetti Google Cloud avranno un ID client OAuth predefinito che puoi utilizzare. Puoi trovarlo ad API e servizi > Credenziali.

Se vuoi creare un ID client OAuth dedicato, segui questi passaggi:

• Vai ad API e servizi > Credenziali
• Fai clic su "+ Crea credenziali" nella parte superiore della pagina e seleziona l'ID client OAuth
• Il tipo di applicazione sarà "Applicazione web"
• Assegna un nome all'ID cliente e fai clic su "Crea"

Passaggio 3: configura il tuo ID client OAuth per l'utilizzo con Embedded Connect

Una volta deciso quale ID client OAuth vuoi utilizzare per l'integrazione di Embedded Connect, dovrai configurarlo.

Segui questi passaggi:

• Nella pagina Credenziali, fai clic sull'icona a forma di matita in corrispondenza dell'ID client da configurare.
• Nella sezione Origini JavaScript autorizzate, aggiungi gli URI autorizzati a inviare richieste utilizzando il tuo ID client. Normalmente vengono aggiunti gli URI del server di sviluppo e dell'ambiente locale (ad es. https://dev.example.com e http://localhost:5000). Devi aggiungere anche un URI per il tuo ambiente di produzione (ad es. https://example.com)

(Facoltativo) Passaggio 4: personalizza la schermata per il consenso OAuth

Nella schermata per il consenso OAuth gli utenti concedono al tuo ID cliente l'accesso ai dati di AdSense. Questa è una parte essenziale del funzionamento di Embedded Connect. Puoi personalizzare questa schermata per includere il nome della piattaforma, il tuo logo e così via. Visita la pagina Schermata consenso OAuth per configurare le personalizzazioni. Fai clic su "Modifica app" nella parte superiore della pagina e segui la procedura guidata.

Passaggio 5: implementa la libreria JavaScript di Connect incorporato

Questa libreria contiene i vari metodi utilizzati per avviare la connessione incorporata e fornisce i callback necessari per recuperare e dimenticare l'ID publisher dell'utente. Implementa questa opzione verso l'inizio della pagina.

Per l'UX gestita da Google:

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

Per l'UX personalizzata:

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

Assicurati di fornire un'implementazione per il nome della funzione JavaScript passata al parametro load. La funzione verrà chiamata quando l'API adsenseEmbeddedConnect sarà pronta per l'uso.

Attributi del tag script

Nell'esempio precedente sono stati impostati diversi attributi nel tag script. Di seguito è riportata una spiegazione di ciascun attributo.

• src: l'URL da cui viene caricata l'API Embedded Connect. L'URL può contenere diversi parametri di query, documentati di seguito.
• async: chiede al browser di scaricare ed eseguire lo script in modo asincrono. Quando lo script viene eseguito, chiama la funzione specificata utilizzando il parametro load.
• defer: se questa impostazione è impostata, il browser scaricherà Embedded Connect JavaScript in parallelo all'analisi della pagina e la eseguirà al termine dell'analisi.

src parametri

L'attributo src contiene diversi parametri di query necessari per avviare Embedded Connect. Vedi di seguito come utilizzare ciascun parametro.

• load è il nome di una funzione JavaScript globale che verrà chiamata quando l'API sarà stata caricata completamente. Puoi scegliere qualsiasi nome per questa funzione.
• hl specifica la lingua da utilizzare per tutte le operazioni di localizzazione, incluso, ad esempio, il testo nel popup di registrazione. È un parametro di query facoltativo. Se non è presente oppure se la lingua non è supportata da AdSense, il widget verrà impostato in modo predefinito sull'inglese (Stati Uniti). Consulta le lingue supportate da AdSense. Il valore del parametro hl deve essere conforme a BCP 47; ad esempio, per gli utenti di inglese britannico, la stringa sarà en-GB.
• headless=true indica che Connessione incorporata verrà utilizzata con l'opzione UX personalizzata al posto dell'UX gestita da Google.

Nota: la libreria JavaScript Embedded Connect risponderà con lo stato 200 solo se l'URI su cui viene caricato è stato inserito nella lista consentita da Google. In caso contrario, la richiesta verrà rifiutata con il codice 403. Ad esempio, se intendi utilizzare la libreria JavaScript di Connect incorporato su console.example.com, Google deve inserire l'URI nella lista consentita per consentire il caricamento della libreria. Contatta il tuo account manager per risolvere il problema per la tua piattaforma. Analogamente, verrebbe restituito un errore 403 se provi a chiamare Embedded Connect da un URL con il protocollo HTTP (utilizza HTTPS).

Ora che hai scelto tra UX personalizzata e UX gestita da Google, continua a vedere di seguito gli esempi di codice per ogni approccio.

Passaggio 6: implementa il codice Collegamento incorporato

Come indicato in precedenza, sono disponibili due opzioni per definire l'esperienza utente:

• Esperienza utente gestita da Google
• Esperienza utente personalizzata

Scegli l'opzione di implementazione più adatta alle esigenze della tua piattaforma.

UX gestita da Google

Segui questi passaggi per fare in modo che Google visualizzi il widget che attiva il flusso di registrazione e mostri all'utente informazioni pertinenti sullo stato del suo account e del suo sito.

Ci sono due componenti del codice Collegamento incorporato. Il primo è un <div> vuoto che specifica dove Embedded Connect deve eseguire il rendering del widget di registrazione. Il secondo è il codice in cui vengono impostate le configurazioni e vengono gestiti i callback.

L'elemento HTML in cui viene visualizzato il widget Connessione incorporata

Inserisci questo codice HTML nella pagina in cui vuoi che venga visualizzato il widget Connessione incorporata:

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

Codice di connessione incorporato

Quindi, inserisci il codice di configurazione sotto la libreria di Connect incorporato, ma sopra l'elemento div:

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

Screenshot

Il widget Connessione incorporata ha quattro stati principali:

1. (Predefinito) Connettersi ad AdSense
2. Connessione ad AdSense in corso...
3. Controllo delle informazioni sul sito in corso...
4. Problemi riscontrati

1. (Predefinito) Connettersi ad AdSense

Questo è lo stato predefinito, che viene mostrato agli utenti quando non è presente il campo publisherId nel codice di connessione incorporata. Avvia il flusso di connessione (popup) e, una volta completato il flusso da parte dell'utente, attiva il callback onConnect.

2. Connessione ad AdSense in corso...

Questo stato viene mostrato agli utenti quando avviano il flusso di connessione (e il popup è presente). Alla chiusura del popup o al completamento del flusso, questo stato viene cambiato in uno degli altri stati.

3. Controllo delle informazioni sul sito in corso...

Dopo aver inviato un nuovo sito ad AdSense, viene eseguita una procedura di revisione. Durante questo periodo, gli annunci non possono essere pubblicati.

Un elemento fondamentale della revisione è il controllo della proprietà, che può essere superato in diversi modi, tra cui:

• L'ID publisher dell'account secondario sia presente nel file ads.txt
• L'ID publisher dell'account secondario sia presente in un tag annuncio sul sito dell'utente
• Il meta tag google-adsense-child-account sia presente sul sito dell'utente. Per ottenere risultati ottimali, assicurati che sia presente sulla home page del sito dell'utente.

L'approccio migliore dipenderà dalla struttura dell'URL e da alcuni altri fattori. Consulta il tuo account manager per conoscere l'approccio migliore per la tua piattaforma.

4. Problemi riscontrati

Se l'account o il sito dell'utente presenta problemi che devono essere risolti, questo stato verrà mostrato agli utenti.

UX personalizzata

Segui questi passaggi se vuoi gestire personalmente l'esperienza utente e utilizzare le chiamate API per attivare manualmente il metodo di registrazione.

Libreria JavaScript di connessione incorporata

Per utilizzare l'opzione UX personalizzata, è necessario impostare il parametro headless=true nell'attributo src. Ad esempio:

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

Fornire i pulsanti di connessione e disconnessione

Quando l'API adsenseEmbeddedConnect è pronta per essere utilizzata (come verificato dalla funzione JavaScript passata nel parametro load), fornisci un'implementazione per la connessione e lo scollegamento da AdSense. Ad esempio, fornendo due pulsanti:

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

A seconda che tu abbia salvato o meno un ID publisher del tuo utente, puoi scegliere quale pulsante mostrare.

Il codice di connessione

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

Il codice di disconnessione

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