Wbudowane połączenie

Wbudowane połączenie ułatwia obsługę i usprawnia ścieżkę konwersji, gdy użytkownicy próbują połączyć AdSense z Twoją platformą.

Embedded Connect to niewielka biblioteka JavaScript, która określa najlepszy punkt wyjścia dla danego użytkownika i prowadzi go przez proces niestandardowej rejestracji w AdSense, który ułatwia mu wyświetlanie reklam. Uwzględnia scenariusze m.in. ustalenie, czy użytkownik ma konto AdSense, czy zaakceptował Warunki korzystania z usługi AdSense, czy dodał witrynę Twojej platformy do swojego konta AdSense i czy witryna ma stan „Gotowe”.

Wbudowana usługa Connect z opcją UX zarządzanego przez Google może również obsługiwać wrażenia użytkowników związane z wyświetlaniem stanu kont i witryn użytkownikom, wskazując im odpowiednie miejsce w AdSense, w którym można rozwiązać ewentualne problemy.

Z myślą o deweloperach biblioteka wysyła też wywołania zwrotne do Twojej platformy zawierające identyfikator wydawcy AdSense użytkownika, który jest potrzebny do prawidłowej konfiguracji wyświetlania reklam.

Wbudowane połączenie udostępnia 2 opcje interfejsu użytkownika:

• Wrażenia użytkowników zarządzane przez Google. Użyj widżetu Embedded Connect, który zarządza wszystkimi wrażeniami użytkowników. Widżet ułatwia użytkownikom proces rejestracji i wyświetla w widżecie informacje o ich koncie i stanie witryny. Ta opcja umożliwia wywołanie zwrotne z identyfikatorem wydawcy AdSense aktywowanym, gdy użytkownik po raz pierwszy połączy konto AdSense.
• Niestandardowy interfejs. Użyj metody adsenseEmbeddedConnect.connect(...) Embedded Connect, która uruchomi proces rejestracji w nowym oknie. Ta opcja umożliwia wywołanie zwrotne z identyfikatorem wydawcy AdSense i tokenem dostępu, za pomocą którego można pobrać dodatkowe informacje z konta AdSense przy użyciu interfejsu API do zarządzania AdSense. Ta opcja wymaga samodzielnego zaprojektowania interfejsu użytkownika.

Wdrażanie technologii Embedded Connect

Aby korzystać z Embedded Connect, wykonaj te czynności:

1. Utwórz projekt w Google Cloud (lub użyj istniejącego)
2. Tworzenie identyfikatora klienta OAuth
3. Skonfiguruj identyfikator klienta OAuth na potrzeby Embedded Connect
4. (Opcjonalnie) Zmodyfikuj ekran zgody OAuth
5. Dodaj do strony bibliotekę JavaScript Embedded Connect
6. Implementowanie kodu Embedded Connect

Krok 1. Utwórz nowy projekt Google Cloud (lub użyj istniejącego)

Jeśli masz już projekt Google Cloud, możesz go użyć. W przeciwnym razie postępuj zgodnie z instrukcjami konfigurowania nowego projektu zgodnie z instrukcjami poniżej:

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

Krok 2. Utwórz identyfikator klienta OAuth

Projekty Google Cloud będą miały domyślny identyfikator klienta OAuth, którego możesz używać. Możesz go znaleźć na stronie Interfejsy API i usługi > Dane logowania.

Jeśli chcesz utworzyć specjalny identyfikator klienta OAuth, wykonaj te czynności:

• Otwórz Interfejsy API i usługi > Dane logowania.
• Kliknij „+ Create Credentials” (+ Utwórz dane logowania) u góry strony i wybierz identyfikator klienta OAuth.
• Typ aplikacji to „Aplikacja internetowa”
• Nazwij identyfikator klienta i kliknij „Utwórz”

Krok 3. Skonfiguruj identyfikator klienta OAuth na potrzeby Embedded Connect

Po wybraniu identyfikatora klienta OAuth, którego chcesz używać na potrzeby integracji Embedded Connect, musisz go skonfigurować.

Aby to zrobić:

• Na stronie Dane logowania kliknij ikonę ołówka obok identyfikatora klienta, który chcesz skonfigurować.
• W sekcji Autoryzowane źródła JavaScript dodaj identyfikatory URI, które mogą wysyłać żądania przy użyciu Twojego identyfikatora klienta. Normalnie dodawane są identyfikatory URI serwera programistycznego i środowiska lokalnego (np. https://dev.example.com i http://localhost:5000). Dodatkowo dodaj identyfikator URI środowiska produkcyjnego (np. https://example.com)

(Opcjonalnie) Krok 4. Dostosuj ekran zgody OAuth

Ekran zgody OAuth to miejsce, w którym użytkownicy przyznają Twojemu identyfikatorowi klienta dostęp do swoich danych AdSense. Jest to kluczowy element działania usługi Embedded Connect. Możesz dostosować ten ekran, aby zawierał nazwę Twojej platformy, logo itp. Aby skonfigurować dostosowania, otwórz stronę Ekran akceptacji OAuth. Kliknij „Edytuj aplikację” u góry strony i postępuj zgodnie z instrukcjami.

Krok 5. Zaimplementuj bibliotekę JavaScript Embedded Connect

Ta biblioteka zawiera różne metody używane do inicjowania połączenia wbudowanego i udostępnia wywołania zwrotne potrzebne do odzyskania i zapomnienia identyfikatora wydawcy użytkownika. Zaimplementuj go w nagłówku strony.

W przypadku rozwiązań UX zarządzanych przez Google:

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

W przypadku niestandardowych wrażeń użytkownika:

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

Udostępnij implementację nazwy funkcji JavaScriptu przekazywanej do parametru load. Funkcja zostanie wywołana, gdy interfejs API adsenseEmbeddedConnect będzie gotowy do użycia.

Atrybuty tagów skryptu

Zwróć uwagę, że w powyższym przykładzie tag skryptu zawiera kilka atrybutów. Poniżej objaśniamy poszczególne atrybuty.

• src: adres URL, z którego wczytuje się interfejs Embedded Connect API. Adres URL może zawierać kilka parametrów zapytania opisanych poniżej.
• async: prosi przeglądarkę o asynchroniczne pobieranie i wykonywanie skryptu. Podczas wykonywania skryptu wywołuje on funkcję określoną za pomocą parametru load.
• defer: gdy skonfigurujesz tę zasadę, przeglądarka pobierze kod JavaScript Embedded Connect równolegle do analizowania strony i wykona go po zakończeniu analizy strony.

Parametry: src

Atrybut src zawiera kilka parametrów zapytania wymaganych do zainicjowania Embedded Connect. Poniżej dowiesz się, jak używać poszczególnych parametrów.

• load to nazwa globalnej funkcji JavaScript, która zostanie wywołana po całkowitym wczytaniu interfejsu API. Funkcja może mieć dowolną nazwę.
• hl określa język, który będzie używany podczas całej lokalizacji, w tym (np.) tekstu w wyskakującym okienku. Jest to opcjonalny parametr zapytania. Jeśli go nie ma lub jeśli język nie jest obsługiwany przez AdSense, widżet domyślnie wybiera język angielski (USA). Sprawdź, jakie języki są obsługiwane przez AdSense. Wartość parametru hl musi być zgodna z BCP 47. Na przykład w przypadku użytkowników angielskich w Wielkiej Brytanii ciąg będzie mieć postać en-GB.
• headless=true oznacza, że funkcja Embedded Connect będzie używana z opcją Niestandardowy interfejs użytkownika, a nie z zarządzanym przez Google UX.

Uwaga: biblioteka JavaScript Embedded Connect w odpowiedzi wyświetli stan 200 tylko wtedy, gdy identyfikator URI, pod którym jest ładowana, został dodany przez Google do listy dozwolonych. W przeciwnym razie żądanie zostanie odrzucone z użyciem kodu 403. Jeśli na przykład chcesz używać biblioteki JavaScript Embedded Connect na stronie konsoli.example.com, Google musi dodać ten identyfikator URI do listy dozwolonych, aby biblioteka mogła się wczytać. Aby rozwiązać ten problem na swojej platformie, skontaktuj się ze swoim menedżerem konta. Podobnie kod 403 zostanie zwrócony, jeśli spróbujesz wywołać funkcję Embedded Connect z adresu URL z protokołem HTTP (użyj HTTPS).

Po wybraniu UX zarządzanego przez Google lub niestandardowego UX zapoznaj się z przykładami kodu dla każdego podejścia poniżej.

Krok 6. Wdróż kod Embedded Connect

Jak już wspomnieliśmy, interfejs użytkownika może wyglądać na 2 sposoby:

• UX zarządzane przez Google
• Niestandardowy interfejs

Wybierz opcję implementacji, która najlepiej odpowiada potrzebom Twojej platformy.

Wrażenia użytkowników zarządzane przez Google

Wykonaj te czynności, aby umożliwić Google wyrenderowanie widżetu, który uruchamia proces rejestracji i wyświetla użytkownikowi istotne informacje o stanie jego konta i witryny.

Kod Embedded Connect składa się z 2 komponentów. Pierwszym z nich jest pusty element <div>, który określa, gdzie ma być renderowany widżet rejestracji. Drugi kod to kod, w którym konfiguruje się konfiguracje i zarządza wywołaniami zwrotnymi.

Element HTML, w którym jest renderowany widżet Embedded Connect

Umieść ten kod HTML na stronie, na której ma być renderowany widżet Embedded Connect:

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

Kod Embedded Connect

Następnie, pod biblioteką Embedded Connect, ale nad elementem div, umieść kod konfiguracji:

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

Zrzuty ekranu

Widżet Embedded Connect ma cztery główne stany:

1. (Domyślnie) Połącz się z AdSense
2. Łączenie z AdSense
3. Sprawdzanie informacji o witrynie
4. ponieważ wykryto problemy

1. (Domyślnie) Połącz się z AdSense

Jest to stan domyślny wyświetlany użytkownikom, gdy w kodzie Embedded Connect nie ma pola publisherId. Inicjuje ono przepływ połączenia (wyskakujące okienko), a po pomyślnym zakończeniu procesu przez użytkownika uruchamia wywołanie zwrotne onConnect.

2. Łączenie z AdSense

Ten stan wyświetla się użytkownikom, gdy rozpoczynają proces połączenia (i pojawia się wyskakujące okienko). Po zamknięciu wyskakującego okienka lub zakończeniu procesu ten stan zmienia się na jeden z pozostałych.

3. Sprawdzanie informacji o witrynie

Gdy nowa witryna zostanie przesłana do AdSense, rozpocznie się proces jej sprawdzania. W tym czasie nie można wyświetlać reklam.

Kluczowym elementem procesu weryfikacji jest kontrola własności, którą można przeprowadzić na wiele sposobów. Jednym z nich jest:

• w pliku ads.txt znajduje się identyfikator wydawcy konta podrzędnego.
• identyfikator wydawcy konta podrzędnego znajduje się w tagu reklamy w witrynie użytkownika.
• metatag google-adsense-child-account znajduje się w witrynie użytkownika; Aby uzyskać najlepsze wyniki, upewnij się, że reklama wyświetla się na stronie głównej witryny użytkownika.

Wybór najlepszej metody zależy od struktury adresu URL i kilku innych czynników. Skonsultuj się ze swoim menedżerem konta, aby wybrać najlepsze rozwiązanie dla Twojej platformy.

4. ponieważ wykryto problemy

Ten stan zostanie wyświetlony użytkownikom, jeśli na koncie lub w witrynie będą występować problemy, które trzeba rozwiązać.

Niestandardowy interfejs

Wykonaj te czynności, jeśli chcesz samodzielnie zarządzać wrażeniami użytkowników i ręcznie aktywujesz metodę rejestracji za pomocą wywołań interfejsu API.

Biblioteka JavaScriptu Embedded Connect

Aby można było użyć opcji Niestandardowy interfejs użytkownika, parametr headless=true musi być ustawiony w atrybucie src. Na przykład:

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

Udostępnianie przycisków łączenia i rozłączania

Gdy interfejs API adsenseEmbeddedConnect będzie gotowy do użycia (co zostanie potwierdzone przez funkcję JavaScript przekazaną do parametru load), udostępnij implementację umożliwiającą łączenie i odłączanie od AdSense. Na przykład dzięki dodaniu 2 przycisków:

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

Możesz wybrać przycisk do wyświetlenia w zależności od tego, czy masz zapisany identyfikator wydawcy powiązany z użytkownikiem.

Kod połączenia

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

Kod rozłączenia

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