AdSense for Platforms | Google for Developers

Questa pagina è stata tradotta dall'API Cloud Translation.

Connessione incorporata

La funzionalità Connessione 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 punto di partenza migliore per un determinato utente e lo guida attraverso un flusso di registrazione ad AdSense personalizzato che lo aiuta attraverso tutti i passaggi necessari per essere in grado di pubblicare 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 proprio account AdSense e se lo stato del sito è "Pronto".

Connessione integrata con l'opzione UX gestita da Google consente anche di gestire l'esperienza utente necessaria per mostrare lo stato dell'account e del sito agli utenti, indirizzandoli alla posizione corretta in AdSense per risolvere eventuali problemi potenziali.

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.

L'esperienza utente di Embedded Connect presenta due opzioni:

UX gestita da Google. Usa il widget Connessione incorporata, che gestisce tutta l'esperienza utente. Il widget aiuterà gli utenti attraverso un flusso di registrazione e mostrerà le informazioni utente sullo stato del loro account e del loro 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 adsenseEmbeddedConnect.connect(...) di collegamento incorporato, che attiva il flusso di registrazione in una nuova finestra. Questa opzione consente di richiamare l'ID publisher AdSense e un token di accesso che può essere utilizzato per recuperare ulteriori informazioni dall'account AdSense utilizzando l'API AdSense Management. Questa opzione richiede la progettazione dell'esperienza utente in autonomia.

Implementazione di una connessione incorporata

Per utilizzare Embedded Connect, dovrai seguire questi passaggi:

Crea un progetto in Google Cloud (o utilizzane uno esistente)
Crea un ID client OAuth
Configurare l'ID client OAuth per l'utilizzo con Embedded Connect
(Facoltativo) Personalizzare la schermata per il consenso OAuth
Aggiungere la libreria JavaScript Embedded Connect alla pagina
Implementazione del codice Embedded Connect

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

Se hai già un progetto Google Cloud, utilizzalo. 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 visitando API e Servizi > Credenziali.

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

Vai su API e Servizi > Credenziali
Fai clic su "+ Crea credenziali" nella parte superiore della pagina, poi seleziona ID client OAuth
Il tipo di applicazione sarà "Applicazione web"
Assegna un nome al tuo ID cliente e fai clic su "Crea"

Passaggio 3: configura l'ID client OAuth da utilizzare con Embedded Connect

Una volta deciso quale ID client OAuth 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 che vuoi 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 inoltre aggiungere un URI per l'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 propri dati AdSense. Si tratta di una parte essenziale del funzionamento di Embedded Connect. Puoi personalizzare questa schermata in modo da includere il nome della tua piattaforma, il tuo logo e così via. Visita la pagina Schermata consenso OAuth per configurare le tue personalizzazioni. Fai clic su "Modifica app" nella parte superiore della pagina e segui la procedura guidata.

Passaggio 5: implementa la libreria JavaScript di Embedded Connect

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

Per l'esperienza utente gestita da Google:

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

Per 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 passato nel parametro load. La funzione viene chiamata quando L'API adsenseEmbeddedConnect è pronta per essere utilizzata.

Attributi del tag di script

Nota nell'esempio precedente che sono impostati diversi attributi nel tag script. Di seguito è riportata una spiegazione di ogni 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 viene eseguito, lo script chiama la funzione specificata utilizzando il parametro load.
defer: se impostato, il browser scaricherà il codice JavaScript Embedded Connect durante l'analisi della pagina e lo eseguirà al termine dell'analisi.

Parametri src

L'attributo src contiene diversi parametri di query necessari per avviare Embedded Connect. Di seguito è riportato l'utilizzo di ciascun parametro.

load è il nome di una funzione JavaScript globale che verrà chiamata al termine del caricamento dell'API. Puoi scegliere qualsiasi nome per questa funzione.
hl specifica la lingua da utilizzare per tutta la localizzazione, incluso, ad esempio, il testo nel popup di registrazione. È un parametro di query facoltativo e, se non presente, o se la lingua non è supportata da AdSense, per impostazione predefinita il widget sarà l'inglese americano. Consulta le lingue supportate da AdSense. Il valore del parametro hl deve seguire BCP 47. Ad esempio, per gli utenti dell'inglese britannico, la stringa sarà en-GB.
headless=true indica che Embedded Connect verrà utilizzato con l'opzione UX personalizzata anziché con l'esperienza utente gestita da Google.

di Gemini Advanced.

Ora che hai scelto tra l'esperienza utente gestita da Google e quella personalizzata, esamina gli esempi di codice per ogni approccio riportati di seguito.

Passaggio 6: implementa il codice Embedded Connect

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

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 esegua il rendering del widget che attiva il flusso di registrazione e mostra all'utente informazioni pertinenti sullo stato del suo account e del suo sito.

Stato predefinito di Connect incorporato

Il codice di Embedded Connect presenta due componenti. Il primo è un campo <div> vuoto che specifica dove Embedded Connect deve visualizzare il 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 Connect incorporato

Inserisci questo codice HTML nella pagina in cui vuoi che venga visualizzato il widget Connect incorporato:

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

Codice di Embedded Connect

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

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': 'user@example.com',

        // 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 incorporato ha quattro stati principali:

(Predefinito) Connettersi ad AdSense
Connessione ad AdSense
Revisione delle informazioni sul sito in corso...
Problemi riscontrati

1. (Predefinito) Connettersi ad AdSense

Questo è lo stato predefinito, mostrato agli utenti quando il campo publisherId nel codice di Embedded Connect non è presente. Avvia il flusso di connessione (popup) e, al completamento del flusso da parte dell'utente, attiva il callback onConnect.

Stato predefinito di Connect incorporato

2. Connessione ad AdSense

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 modificato in uno degli altri stati.

Collegamento incorporato - Collegamento ad AdSense

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

Dopo aver inviato un nuovo sito ad AdSense, viene eseguita una procedura di revisione. Durante questo periodo non è possibile pubblicare gli annunci.

Collegamento incorporato - Revisione delle informazioni del sito

Un componente fondamentale della revisione è il controllo della proprietà, che può essere superato in vari 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. Rivolgiti al tuo account manager per conoscere l'approccio migliore per la tua piattaforma.

4. Problemi riscontrati

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

Connessione incorporata - Problemi rilevati

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 Embedded Connect

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 collegamento e disconnessione

Quando l'API adsenseEmbeddedConnect è pronta per essere utilizzata (come verificato dal funzione JavaScript passata nel parametro load), fornire un'implementazione per connetterti e disconnetterti da AdSense. Ad esempio, fornendo due pulsanti:

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

Puoi scegliere quale pulsante mostrare, a seconda che tu disponga o meno di un ID publisher salvato per l'utente.

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

Codice di disconnessione

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