Kết nối được nhúng

Embedded Connect giúp giảm sự phiền hà và cải thiện phễu chuyển đổi khi người dùng đang cố gắng kết nối AdSense với nền tảng của bạn.

Embedded Connect là một thư viện JavaScript nhỏ xác định điểm bắt đầu tốt nhất cho một người dùng nhất định và hướng dẫn họ thực hiện quy trình đăng ký AdSense tuỳ chỉnh nhằm giúp họ thực hiện tất cả các bước cần thiết để có thể phân phát quảng cáo. Hệ thống này xử lý các tình huống như xác định xem người dùng có tài khoản AdSense hay chưa, liệu họ đã ký các điều khoản và điều kiện của AdSense hay chưa, liệu họ đã thêm trang web của nền tảng của bạn vào tài khoản AdSense hay chưa và trạng thái của trang web là "Sẵn sàng".

Embedded Connect với lựa chọn về trải nghiệm người dùng do Google quản lý cũng có thể xử lý trải nghiệm người dùng liên quan đến việc hiển thị trạng thái tài khoản và trang web cho người dùng, hướng dẫn họ đến đúng vị trí trong AdSense để giải quyết mọi vấn đề tiềm ẩn.

Để hỗ trợ trải nghiệm của nhà phát triển, thư viện cũng đưa ra các lệnh gọi lại đến nền tảng của bạn chứa mã nhà xuất bản AdSense của người dùng. Việc này cần thiết để thiết lập hoạt động phân phát quảng cáo đúng cách.

Embedded Connect cung cấp hai tuỳ chọn cho trải nghiệm người dùng:

  • Trải nghiệm người dùng do Google quản lý. Sử dụng tiện ích Embedded Connect để quản lý toàn bộ trải nghiệm người dùng. Tiện ích này sẽ giúp người dùng thông qua quy trình đăng ký và hiển thị cho người dùng thông tin về trạng thái trang web cũng như tài khoản của họ bên trong tiện ích. Tùy chọn này cung cấp lệnh gọi lại có mã nhà xuất bản AdSense được kích hoạt khi người dùng kết nối tài khoản AdSense lần đầu tiên.
  • Trải nghiệm người dùng tuỳ chỉnh. Sử dụng phương thức Embedded Connect adsenseEmbeddedConnect.connect(...) để kích hoạt quy trình đăng ký trong một cửa sổ mới. Tùy chọn này cung cấp lệnh gọi lại cùng với mã nhà xuất bản AdSense và mã truy cập có thể được dùng để tìm nạp thêm thông tin từ tài khoản AdSense bằng API Quản lý AdSense. Lựa chọn này yêu cầu bạn tự thiết kế trải nghiệm người dùng.

Triển khai Embedded Connect

Để sử dụng Embedded Connect, bạn cần làm theo các bước sau:

  1. Tạo một dự án trong Google Cloud (hoặc sử dụng một dự án hiện có)
  2. Tạo mã ứng dụng OAuth
  3. Định cấu hình mã ứng dụng khách OAuth để dùng với Embedded Connect
  4. (Không bắt buộc) Tuỳ chỉnh màn hình xin phép bằng OAuth
  5. Thêm thư viện JavaScript Embedded Connect vào trang này
  6. Triển khai mã Embedded Connect

Bước 1: Tạo dự án mới trên Google Cloud (hoặc sử dụng dự án hiện có)

Nếu bạn đã có sẵn một dự án trên Google Cloud, hãy sử dụng dự án đó. Nếu không, hãy làm theo hướng dẫn dưới đây về cách thiết lập dự án mới:

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

Bước 2: Tạo mã ứng dụng OAuth

Các dự án trên Google Cloud sẽ có một mã ứng dụng khách OAuth mặc định mà bạn có thể sử dụng. Bạn có thể tìm thấy điều này bằng cách truy cập API & Dịch vụ > Thông tin xác thực.

Nếu bạn muốn tạo mã ứng dụng OAuth chuyên dụng, hãy làm theo các bước sau:

  • Truy cập vào API & Dịch vụ > Thông tin xác thực
  • Nhấp vào "+ Tạo thông tin xác thực" ở đầu trang, sau đó chọn mã ứng dụng khách OAuth
  • Loại ứng dụng của bạn sẽ là "Ứng dụng web"
  • Đặt tên cho ID khách hàng của bạn rồi nhấp vào "Tạo"

Bước 3: Định cấu hình mã ứng dụng khách OAuth để sử dụng với Embedded Connect

Sau khi quyết định mã ứng dụng khách OAuth mà bạn muốn dùng để tích hợp Embedded Connect, hãy định cấu hình mã ứng dụng đó.

Hãy làm theo các bước sau:

  • Trên trang Thông tin đăng nhập, hãy nhấp vào biểu tượng bút chì của mã ứng dụng khách mà bạn muốn định cấu hình
  • Trong phần Nguồn gốc JavaScript được cho phép, hãy thêm các URI được phép đưa ra yêu cầu bằng mã ứng dụng khách của bạn. Thông thường, URI cho máy chủ phát triển và môi trường cục bộ sẽ được thêm (ví dụ: https://dev.example.com và http://localhost:5000). Bạn nên thêm URI cho môi trường phát hành chính thức (ví dụ: https://example.com)

Màn hình xin phép bằng OAuth là nơi người dùng có thể sử dụng để cấp cho mã ứng dụng khách của bạn quyền truy cập vào dữ liệu AdSense của họ. Đây là một phần thiết yếu trong cách thức hoạt động của Embedded Connect. Bạn có thể tuỳ chỉnh màn hình này để bao gồm tên nền tảng, biểu trưng của bạn, v.v. Truy cập vào màn hình xin phép của OAuth để định cấu hình các chế độ tuỳ chỉnh. Nhấp vào "Chỉnh sửa ứng dụng" ở đầu trang và làm theo trình hướng dẫn.

Bước 5: Triển khai thư viện JavaScript Embedded Connect

Thư viện này chứa nhiều phương thức dùng để khởi chạy tính năng Kết nối được nhúng và cung cấp cho bạn các lệnh gọi lại cần thiết để bạn truy xuất và quên mã nhà xuất bản của người dùng. Hãy triển khai việc này ở phía đầu trang.

Đối với trải nghiệm người dùng do Google quản lý:

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

Đối với trải nghiệm người dùng tuỳ chỉnh:

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

Đảm bảo bạn cung cấp phương thức triển khai cho tên hàm JavaScript được chuyển vào tham số load. Hàm này sẽ được gọi khi API adsenseEmbeddedConnect đã sẵn sàng cho bạn sử dụng.

Thuộc tính thẻ tập lệnh

Lưu ý trong ví dụ trên, một số thuộc tính được đặt trên thẻ tập lệnh. Sau đây là nội dung giải thích về từng thuộc tính.

  • src: URL nơi API Embedded Connect được tải từ đó. URL có thể chứa một số tham số truy vấn được ghi lại bên dưới.
  • async: Yêu cầu trình duyệt tải xuống và thực thi tập lệnh một cách không đồng bộ. Khi được thực thi, tập lệnh sẽ gọi hàm được chỉ định bằng tham số load.
  • defer: khi bạn đặt chính sách này, trình duyệt sẽ tải JavaScript Embedded Connect xuống song song để phân tích cú pháp trang và sẽ thực thi sau khi trang hoàn tất quá trình phân tích cú pháp.

Tham số src

Thuộc tính src chứa một số tham số truy vấn cần thiết để khởi chạy Embedded Connect. Hãy xem cách sử dụng từng thông số ở bên dưới.

  • load là tên của hàm JavaScript chung sẽ được gọi khi API được tải hoàn toàn. Bạn có thể chọn bất kỳ tên nào cho hàm này.
  • hl chỉ định ngôn ngữ để sử dụng cho mọi nội dung bản địa hoá, bao gồm cả văn bản trong cửa sổ bật lên đăng ký. Đây là một thông số truy vấn không bắt buộc. Khi không có thông số này hoặc nếu ngôn ngữ mà AdSense không hỗ trợ, tiện ích này sẽ mặc định là tiếng Anh (Mỹ). Xem các ngôn ngữ mà AdSense hỗ trợ. Giá trị tham số hl phải tuân theo BCP 47, ví dụ: đối với người dùng tiếng Anh (Anh), chuỗi sẽ là en-GB.
  • headless=true cho biết rằng Embedded Connect sẽ được sử dụng cùng với tuỳ chọn Tuỳ chỉnh trải nghiệm người dùng thay vì trải nghiệm người dùng do Google quản lý.

Giờ đây, bạn đã chọn giữa UX do Google quản lý và UX tuỳ chỉnh, hãy tiếp tục xem các ví dụ về mã cho từng phương pháp bên dưới.

Bước 6: Triển khai mã Embedded Connect

Như đã đề cập ở trên, có hai tùy chọn giao diện cho trải nghiệm người dùng:

Chọn phương thức triển khai phù hợp nhất với nhu cầu của nền tảng.

Trải nghiệm người dùng do Google quản lý

Hãy làm theo các bước sau để yêu cầu Google hiển thị tiện ích kích hoạt quy trình đăng ký và cho người dùng thấy thông tin liên quan về trạng thái tài khoản và trang web của họ.

Trạng thái mặc định của Embedded Connect

Có hai thành phần của mã Embedded Connect. Đầu tiên là một <div> trống chỉ định vị trí Embedded Connect sẽ hiển thị tiện ích đăng ký. Thứ hai là mã nơi bạn đặt cấu hình và quản lý các lệnh gọi lại.

Phần tử HTML nơi tiện ích Embedded Connect hiển thị

Đặt HTML này trên trang mà bạn muốn tiện ích Embedded Connect hiển thị:

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

Mã Embedded Connect

Tiếp theo, bên dưới thư viện Embedded Connect nhưng phía trên phần tử div, hãy đặt mã cấu hình:

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
        },
    });
};
Ảnh chụp màn hình

Tiện ích Embedded Connect có bốn trạng thái chính:

  1. (Mặc định) Kết nối với AdSense
  2. Đang kết nối với AdSense
  3. Đang xem xét thông tin trang web
  4. Đã phát hiện thấy vấn đề
1. (Mặc định) Kết nối với AdSense

Đây là trạng thái mặc định, hiển thị cho người dùng khi không có trường publisherId trong mã Embedded Connect. Hàm này bắt đầu luồng kết nối (bật lên) và sau khi người dùng hoàn tất thành công luồng, sẽ kích hoạt lệnh gọi lại onConnect.

Trạng thái mặc định của Embedded Connect

2. Đang kết nối với AdSense

Trạng thái này được hiển thị cho người dùng khi họ bắt đầu quy trình kết nối (và có cửa sổ bật lên). Khi cửa sổ bật lên hoặc khi hoàn tất luồng, trạng thái này sẽ thay đổi thành một trong những trạng thái khác.

Embedded Connect – Kết nối với AdSense

3. Đang xem xét thông tin trang web

Sau khi bạn gửi trang web mới đến AdSense, một quy trình xem xét sẽ diễn ra. Quảng cáo không thể phân phát trong khoảng thời gian này.

Embedded Connect - Xem xét thông tin trang web

Embedded Connect – Xem xét thông tin trang web với trình đơn đang mở

Một phần quan trọng của quy trình xem xét là kiểm tra quyền sở hữu. Bạn có thể thông qua quy trình này theo nhiều cách, chẳng hạn như:

  • mã nhà xuất bản của tài khoản con có trong tệp ads.txt
  • mã nhà xuất bản của tài khoản con có trong một thẻ quảng cáo trên trang web của người dùng
  • thẻ meta google-adsense-child-account hiện diện trên trang web của người dùng. Để thu được kết quả tốt nhất, hãy đảm bảo rằng quảng cáo đó xuất hiện trên trang chủ trên trang web của người dùng.

Cách tiếp cận tốt nhất sẽ phụ thuộc vào cấu trúc URL của bạn và một số yếu tố khác. Vui lòng tham khảo ý kiến của người quản lý tài khoản để có phương pháp phù hợp nhất cho nền tảng của bạn.

4. Đã phát hiện thấy vấn đề

Nếu tài khoản hoặc trang web của người dùng có vấn đề cần được giải quyết, trạng thái này sẽ hiển thị cho người dùng.

Embedded Connect – Đã phát hiện thấy sự cố

Embedded Connect – Phát hiện thấy sự cố khi trình đơn đang mở

Trải nghiệm người dùng tuỳ chỉnh

Hãy làm theo các bước sau nếu bạn muốn tự quản lý trải nghiệm người dùng và sử dụng lệnh gọi API để kích hoạt phương thức đăng ký theo cách thủ công.

Thư viện JavaScript kết nối được nhúng

Để sử dụng Lựa chọn tuỳ chỉnh về trải nghiệm người dùng, bạn cần đặt tham số headless=true trong thuộc tính src. Ví dụ:

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

Cung cấp nút kết nối và ngắt kết nối

Sau khi API adsenseEmbeddedConnect đã sẵn sàng để sử dụng (như đã được xác minh bởi Hàm JavaScript được truyền vào thông số load), cung cấp phương thức triển khai để kết nối và ngắt kết nối khỏi AdSense. Ví dụ: bằng cách cung cấp hai các nút:

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

Tùy thuộc vào việc bạn có lưu mã nhà xuất bản từ người dùng của mình hay không, bạn có thể chọn nút để hiển thị.

Mã kết nối

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

Đoạn mã ngắt kết nối

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