Sambungan Tersemat

Embedded Connect mengurangi hambatan dan meningkatkan funnel konversi saat pengguna mencoba menghubungkan AdSense dengan platform Anda.

Embedded Connect adalah library JavaScript kecil yang menentukan titik awal terbaik untuk pengguna tertentu dan memandu mereka melalui alur pendaftaran AdSense yang disesuaikan yang membantu mereka melalui semua langkah yang diperlukan agar dapat menayangkan iklan. Google Play Protect menangani skenario termasuk menentukan apakah pengguna memiliki akun AdSense, apakah pengguna telah menandatangani persyaratan dan ketentuan AdSense, apakah mereka telah menambahkan situs platform Anda ke akun AdSense mereka, dan apakah status situs tersebut "Siap".

Embedded Connect dengan opsi UX yang dikelola Google juga dapat menangani UX yang terlibat dalam menampilkan status akun dan situs kepada pengguna, yang memandu mereka ke lokasi yang benar di AdSense untuk menyelesaikan setiap potensi masalah.

Untuk membantu pengalaman developer, library juga mengirimkan callback ke platform Anda yang berisi ID penayang AdSense pengguna yang diperlukan untuk menyiapkan penayangan iklan dengan benar.

Embedded Connect menawarkan dua opsi terkait tampilan pengalaman pengguna:

• UX yang dikelola Google. Menggunakan widget Embedded Connect, yang mengelola semua UX. Widget ini akan membantu pengguna melalui alur pendaftaran dan menampilkan informasi tentang akun dan status situs mereka di dalam widget kepada pengguna. Opsi ini memberikan callback dengan ID penayang AdSense yang dipicu saat pengguna pertama kali menghubungkan akun AdSense.
• UX Kustom. Gunakan metode Embedded Connect adsenseEmbeddedConnect.connect(...), yang memicu alur pendaftaran di jendela baru. Opsi ini memberikan callback dengan ID penayang AdSense dan token akses yang dapat digunakan untuk mengambil informasi tambahan dari akun AdSense menggunakan AdSense Management API. Opsi ini mengharuskan Anda untuk mendesain UX sendiri.

Menerapkan Sambungan Tersemat

Untuk menggunakan Embedded Connect, Anda harus mengikuti langkah-langkah berikut:

1. Membuat project di Google Cloud (atau menggunakan project yang sudah ada)
2. Membuat client ID OAuth
3. Mengonfigurasi client ID OAuth untuk digunakan dengan Embedded Connect
4. (Opsional) Menyesuaikan layar izin OAuth
5. Menambahkan library Embedded Connect JavaScript ke halaman
6. Mengimplementasikan kode Embedded Connect

Langkah 1: Buat project Google Cloud baru (atau gunakan yang sudah ada)

Jika Anda sudah memiliki project Google Cloud, silakan menggunakannya. Jika tidak, ikuti panduan di bawah tentang menyiapkan project baru:

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

Langkah 2: Buat client ID OAuth

Project Google Cloud akan memiliki client ID OAuth default yang dapat Anda gunakan. Anda dapat menemukannya dengan membuka API & Layanan > Kredensial.

Jika Anda ingin membuat client ID OAuth khusus, ikuti langkah-langkah berikut:

• Buka APIs & Services > Credentials
• Klik "+ Create Credentials" di bagian atas halaman, lalu pilih client ID OAuth
• Jenis aplikasi Anda adalah "Aplikasi web"
• Beri nama client ID Anda dan klik "Buat"

Langkah 3: Konfigurasikan client ID OAuth untuk digunakan dengan Embedded Connect

Setelah memutuskan client ID OAuth yang ingin digunakan untuk integrasi Embedded Connect, Anda harus mengonfigurasinya.

Ikuti langkah-langkah berikut:

• Dari halaman Kredensial, klik ikon pensil untuk client ID yang ingin dikonfigurasi
• Di bagian Asal JavaScript yang sah, tambahkan URI yang diizinkan untuk mengeluarkan permintaan menggunakan client ID Anda. Biasanya URI untuk server pengembangan dan lingkungan lokal Anda akan ditambahkan (misalnya https://dev.example.com dan http://localhost:5000). Selain itu, Anda harus menambahkan URI untuk lingkungan produksi (misalnya, https://example.com)

(Opsional) Langkah 4: Sesuaikan layar izin OAuth Anda

Layar izin OAuth adalah tempat pengguna akan memberi client ID Anda akses ke data AdSense mereka. Ini adalah bagian penting dari cara kerja Embedded Connect. Anda dapat menyesuaikan layar ini untuk menyertakan nama platform, logo, dll. Buka halaman Layar izin OAuth untuk mengonfigurasi penyesuaian. Klik "Edit aplikasi" di bagian atas halaman dan ikuti wizardnya.

Langkah 5: Implementasikan library Embedded Connect JavaScript

Library ini berisi berbagai metode yang digunakan untuk memulai Sambungan Tersemat dan memberi Anda callback yang diperlukan agar Anda dapat mengambil dan melupakan ID penayang pengguna. Terapkan ini di bagian head halaman.

Untuk UX yang dikelola Google:

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

Untuk UX Kustom:

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

Pastikan Anda menyediakan implementasi untuk nama fungsi JavaScript yang diteruskan ke parameter load. Fungsi ini akan dipanggil saat adsenseEmbeddedConnect API siap digunakan.

Atribut Tag Skrip

Perhatikan pada contoh di atas bahwa beberapa atribut ditetapkan pada tag skrip. Berikut adalah penjelasan dari setiap atribut.

• src: URL tempat Embedded Connect API dimuat. URL dapat berisi beberapa parameter kueri, yang didokumentasikan di bawah ini.
• async: Meminta browser untuk mendownload dan mengeksekusi skrip secara asinkron. Ketika dieksekusi, skrip akan memanggil fungsi yang ditentukan menggunakan parameter load.
• defer: jika disetel, browser akan mendownload JavaScript Sambungan Tersemat secara paralel dengan mengurai halaman, dan akan menjalankannya setelah halaman selesai diuraikan.

Parameter src

Atribut src berisi beberapa parameter kueri yang diperlukan untuk memulai Embedded Connect. Lihat penggunaan setiap parameter di bawah.

• load adalah nama fungsi JavaScript global yang akan dipanggil saat API telah dimuat sepenuhnya. Anda dapat memilih nama apa pun untuk fungsi ini.
• hl menentukan bahasa yang akan digunakan untuk semua pelokalan, termasuk (misalnya) teks pada pop-up pendaftaran. Parameter kueri ini bersifat opsional, dan jika bahasanya tidak didukung oleh AdSense, widget akan ditetapkan secara default ke bahasa Inggris AS. Lihat bahasa yang didukung AdSense. Nilai parameter hl harus mengikuti BCP 47, misalnya untuk pengguna bahasa Inggris Britania Raya, stringnya akan menjadi en-GB.
• headless=true menunjukkan bahwa Embedded Connect akan digunakan dengan opsi UX Kustom, bukan UX yang dikelola Google.

Catatan: Library Embedded Connect JavaScript hanya akan merespons dengan status 200 jika URI yang dimuatnya telah diizinkan oleh Google. Jika tidak, permintaan akan ditolak dengan kode 403. Misalnya, jika Anda ingin menggunakan library JavaScript Embedded Connect di console.example.com, Google harus mengizinkan URI tersebut agar library dapat dimuat. Hubungi Account Manager Anda untuk menyelesaikan masalah ini untuk platform Anda. Demikian pula, kode 403 akan ditampilkan jika Anda mencoba memanggil Embedded Connect dari URL dengan protokol HTTP (gunakan HTTPS).

Setelah Anda memilih antara UX yang dikelola Google dan UX Kustom, lanjutkan untuk melihat contoh kode untuk setiap pendekatan di bawah ini.

Langkah 6: Terapkan kode Embedded Connect

Seperti yang disebutkan di atas, ada dua opsi untuk tampilan pengalaman pengguna:

• UX yang dikelola Google
• UX Kustom

Pilih opsi penerapan yang paling sesuai dengan kebutuhan platform Anda.

UX yang dikelola Google

Ikuti langkah-langkah berikut agar Google merender widget yang memicu alur pendaftaran dan menampilkan informasi yang relevan kepada pengguna tentang status akun dan situs mereka.

Ada dua komponen kode Embedded Connect. Yang pertama adalah <div> kosong yang menentukan tempat Embedded Connect harus merender widget pendaftaran. Yang kedua adalah kode tempat konfigurasi ditetapkan dan callback dikelola.

Elemen HTML tempat widget Embedded Connect dirender

Tempatkan HTML ini pada halaman tempat Anda ingin widget Embedded Connect dirender:

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

Kode Embedded Connect

Berikutnya, di bawah library Embedded Connect tetapi di atas elemen div, tempatkan kode konfigurasi:

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

Widget Embedded Connect memiliki empat status utama:

1. (Default) Terhubung ke AdSense
2. Menghubungkan ke AdSense
3. Meninjau info situs
4. Masalah terdeteksi

1. (Default) Terhubung ke AdSense

Ini adalah status default, yang ditampilkan kepada pengguna saat kolom publisherId dalam kode Embedded Connect tidak ada. Fungsi ini memulai alur koneksi (popup) dan setelah berhasil menyelesaikan alur oleh pengguna, akan memicu callback onConnect.

2. Menghubungkan ke AdSense

Status ini ditampilkan kepada pengguna saat mereka memulai alur koneksi (dan pop-up akan muncul). Setelah penutupan pop-up, atau penyelesaian alur, status ini diubah ke salah satu status lain.

3. Meninjau info situs

Setelah situs baru dikirim ke AdSense, proses peninjauan akan berlangsung. Iklan tidak dapat ditayangkan selama periode ini.

Komponen penting dari peninjauan adalah pemeriksaan kepemilikan, yang dapat diteruskan melalui beberapa cara termasuk:

• ID penayang akun turunan ada di file ads.txt
• ID penayang akun turunan ada dalam tag iklan di situs pengguna
• tag meta google-adsense-child-account ada di situs pengguna. Untuk hasil terbaik, pastikan URL tersebut ada di halaman beranda situs pengguna.

Pendekatan terbaik akan bergantung pada struktur URL Anda dan beberapa faktor lainnya. Konsultasikan dengan Account Manager Anda untuk mendapatkan pendekatan terbaik bagi platform Anda.

4. Masalah terdeteksi

Jika akun atau situs pengguna mengalami masalah yang perlu diselesaikan, status ini akan ditampilkan kepada pengguna.

UX Kustom

Ikuti langkah-langkah ini jika Anda ingin mengelola UX sendiri, dan gunakan panggilan API untuk memicu metode pendaftaran secara manual.

Library JavaScript terhubung yang disematkan

Untuk menggunakan opsi UX Kustom, parameter headless=true harus ditetapkan dalam atribut src. Contoh:

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

Menyediakan tombol hubungkan dan putuskan koneksi

Setelah adsenseEmbeddedConnect API siap digunakan (seperti yang diverifikasi oleh fungsi JavaScript yang diteruskan ke parameter load), berikan implementasi untuk menghubungkan dan memutuskan sambungan dari AdSense. Misalnya, dengan menyediakan dua tombol:

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

Bergantung pada apakah Anda memiliki ID penayang yang disimpan dari pengguna atau tidak, Anda dapat memilih tombol mana yang akan ditampilkan.

Kode koneksi

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

Kode pemutusan koneksi

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