Embedded Connect

埋め込み Connect を使用すると、ユーザーが AdSense とプラットフォームを接続する際の煩わしさが軽減され、コンバージョン ファネルが改善されます。

Embedded Connect は、特定のユーザーにとって最適な開始点を判断し、広告の配信を開始するために必要なすべての手順を案内する、カスタマイズされた AdSense 登録フローを案内する小さな JavaScript ライブラリです。ユーザーが AdSense アカウントを持っているかどうか、AdSense 利用規約に同意しているかどうか、プラットフォームのサイトを AdSense アカウントに追加しているかどうか、サイトのステータスが「準備完了」かどうかなどのシナリオに対応します。

埋め込み Connect で Google 管理の UX オプションを使用すると、アカウントとサイトのステータスをユーザーに表示する UX も処理できます。また、潜在的な問題を解決するために、AdSense の適切な場所にユーザーを誘導することもできます。

デベロッパーの利便性を高めるために、このライブラリは、広告配信を正しく設定するために必要なユーザーの AdSense パブリッシャー ID を含むコールバックをプラットフォームに送信します。

Embedded Connect には、ユーザー エクスペリエンスの 2 つのオプションがあります。

  • Google が管理する UX。すべての UX を管理する Embedded Connect ウィジェットを使用する。このウィジェットは、ユーザーが登録フローを完了できるようサポートし、アカウントとサイトのステータスに関するユーザー情報をウィジェット内に表示します。このオプションでは、ユーザーが AdSense アカウントを初めて接続したときにトリガーされる AdSense パブリッシャー ID を含むコールバックが提供されます。
  • カスタム UX。埋め込み Connect の adsenseEmbeddedConnect.connect(...) メソッドを使用して、新しいウィンドウで登録フローをトリガーします。このオプションでは、AdSense パブリッシャー ID とアクセス トークンを含むコールバックが提供されます。このアクセス トークンを使用して、AdSense Management API で AdSense アカウントから追加情報を取得できます。このオプションでは、UX を自分で設計する必要があります。

Embedded Connect の実装

Embedded Connect を使用するには、次の手順が必要です。

  1. Google Cloud でプロジェクトを作成する（または既存のプロジェクトを使用する）
  2. OAuth クライアント ID を作成する
  3. Embedded Connect で使用する OAuth クライアント ID を構成する
  4. （省略可）OAuth 同意画面をカスタマイズする
  5. Embedded Connect JavaScript ライブラリをページに追加する
  6. Embedded Connect コードを実装する

ステップ 1: 新しい Google Cloud プロジェクトを作成する（または既存のプロジェクトを使用する）

既存の Google Cloud プロジェクトがある場合は、そのプロジェクトを使用できます。プロジェクトがない場合は、以下のガイドに沿って新しいプロジェクトを設定してください。

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

ステップ 2: OAuth クライアント ID を作成する

Google Cloud プロジェクトには、使用できるデフォルトの OAuth クライアント ID があります。[API とサービス] > [認証情報] に移動すると確認できます。

専用の OAuth クライアント ID を作成する手順は次のとおりです。

  • [API とサービス] > [認証情報] に移動します。
  • ページ上部の [+ 認証情報を作成] をクリックし、[OAuth クライアント ID] を選択します。
  • アプリケーションの種類は「ウェブ アプリケーション」です。
  • クライアント ID に名前を付けて、[作成] をクリックします。

ステップ 3: Embedded Connect で使用するように OAuth クライアント ID を構成する

Embedded Connect の統合に使用する OAuth クライアント ID を決定したら、その ID を構成する必要があります。

手順は次のとおりです。

  • [認証情報] ページで、設定するクライアント ID の鉛筆アイコンをクリックします。
  • [承認済みの JavaScript 生成元] セクションで、クライアント ID を使用してリクエストを発行できる URI を追加します。通常、開発用サーバーおよびローカル環境の URI（https://dev.example.com や http://localhost:5000 など）が追加されます。本番環境の URI（https://example.com など）も追加する必要があります。

OAuth 同意画面では、ユーザーがクライアント ID に AdSense データへのアクセスを許可します。これは Embedded Connect の仕組みにおいて不可欠な部分です。この画面は、プラットフォームの名前やロゴなどを追加するようにカスタマイズできます。カスタマイズを構成するには、OAuth 同意画面のページをご覧ください。ページ上部の [アプリを編集] をクリックし、ウィザードの指示に沿って操作します。

ステップ 5: Embedded Connect JavaScript ライブラリを実装する

このライブラリには、埋め込みコネクションの開始に使用されるさまざまなメソッドと、ユーザーのパブリッシャー ID の取得と削除に必要なコールバックが含まれています。これをページの上部に実装します。

Google 管理の UX の場合:

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

カスタム UX の場合:

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

load パラメータに渡される JavaScript 関数名の実装を指定してください。この関数は、adsenseEmbeddedConnect API の使用準備が整うと呼び出されます。

スクリプトタグ属性

上記の例では、スクリプト タグに複数の属性が設定されています。以下に、各属性について説明します。

  • src: Embedded Connect API の読み込み元となる URL。URL には複数のクエリ パラメータを含めることができます。以下に説明します。
  • async: スクリプトを非同期でダウンロードして実行するようブラウザに指示します。このスクリプトの実行時に、load パラメータで指定された関数が呼び出されます。
  • defer: 設定すると、ブラウザはページの解析と並行して Embedded Connect JavaScript をダウンロードし、ページの解析が完了した後に実行します。

src パラメータ

src 属性には、Embedded Connect の開始に必要な複数のクエリ パラメータが含まれています。各パラメータの使用方法については、以下をご覧ください。

  • load は、API の読み込みが完了したときに呼び出されるグローバル JavaScript 関数の名前です。この関数には任意の名前を付けることができます。
  • hl には、登録ポップアップのテキストなど、すべてのローカライズに使用する言語を指定します。これは省略可能なクエリ パラメータです。指定しない場合、または指定した言語が AdSense でサポートされていない場合、ウィジェットはデフォルトで米国英語になります。AdSense でサポートされている言語をご確認ください。hl パラメータ値は BCP 47 に従っている必要があります。たとえば、英国英語のユーザーの場合は、文字列は en-GB になります。
  • headless=true は、Embedded Connect が Google 管理の UX ではなく、カスタム UX オプションで使用されることを示します。

Google 管理の UX とカスタム UX のどちらを選択したかを確認したら、以下の各アプローチのコード例をご覧ください。

ステップ 6: Embedded Connect コードを実装する

前述のとおり、ユーザー エクスペリエンスには次の 2 つのオプションがあります。

プラットフォームのニーズに最適な実装オプションを選択します。

Google が管理する UX

次の手順に沿って、登録フローをトリガーし、アカウントとサイトの状態に関する関連情報をユーザーに表示するウィジェットを Google がレンダリングするようにします。

Embedded Connect のデフォルト状態

Embedded Connect コードには 2 つのコンポーネントがあります。1 つ目は空の <div> で、Embedded Connect が登録ウィジェットをレンダリングする場所を指定します。2 つ目は、構成が設定され、コールバックが管理されるコードです。

埋め込み Connect ウィジェットがレンダリングされる HTML 要素

埋め込み Connect ウィジェットをレンダリングするページに、次の HTML を配置します。

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

埋め込み Connect コード

次に、Embedded Connect ライブラリの下、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': '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
        },
    });
};
スクリーンショット

埋め込み Connect ウィジェットには、主に次の 4 つの状態があります。

  1. （デフォルト）AdSense に接続する
  2. AdSense へのリンク
  3. サイト情報の確認
  4. 問題が検出されました
1. （デフォルト）AdSense に接続する

これはデフォルトの状態であり、埋め込み Connect コードに publisherId フィールドが存在しない場合、ユーザーに表示されます。接続フロー（ポップアップ）を開始し、ユーザーがフローを正常に完了すると、onConnect コールバックがトリガーされます。

埋め込み接続のデフォルト状態

2. AdSense へのリンク

この状態は、ユーザーが接続フローを開始したときに（ポップアップが表示されている場合）表示されます。ポップアップの閉鎖時、またはフローの完了時に、この状態は他のいずれかの状態に変更されます。

Embedded Connect - AdSense への接続

3. サイト情報の確認

新しいサイトが AdSense に送信されると、審査プロセスが開始されます。この期間中は広告を配信できません。

埋め込み Connect - サイト情報の確認

埋め込み Connect - メニューを開いてサイト情報を確認する

審査の重要な要素は所有権チェックです。これは、次のようなさまざまな方法で合格できます。

  • 子アカウントのパブリッシャー ID が ads.txt ファイルに存在する
  • 子アカウントのパブリッシャー ID がユーザーのサイトの広告タグに含まれている
  • google-adsense-child-account メタタグがユーザーのサイトに存在している。最適な結果を得るには、ユーザーのサイトのホームページに表示されていることをご確認ください。

最適な方法は、URL 構造やその他の要因によって異なります。ご利用のプラットフォームに最適な方法については、アカウント マネージャーにご相談ください。

4. 問題が検出されました

ユーザーのアカウントまたはサイトに解決が必要な問題がある場合は、このステータスがユーザーに表示されます。

Embedded Connect - 問題が検出されました

埋め込み Connect - メニューを開いたときに問題が検出される

カスタム UX

UX を自分で管理し、API 呼び出しを使用して登録方法を手動でトリガーする場合は、次の手順を行います。

埋め込みの connect JavaScript ライブラリ

カスタム UX オプションを使用するには、src 属性に headless=true パラメータを設定する必要があります。次に例を示します。

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

接続ボタンと切断ボタンを用意する

adsenseEmbeddedConnect API が使用可能になったら（load パラメータに渡された JavaScript 関数によって確認済み）、AdSense との接続と切断の実装を提供します。たとえば、次の 2 つのボタンを用意します。

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

ユーザーからニュース メディア ID が保存されているかどうかに応じて、表示するボタンを選択できます。

接続コード

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

切断コード

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