このページは Cloud Translation API によって翻訳されました。

デベロッパーガイド

Embedded Viewer API を使用すると、JavaScript を使用して Google ブックスの書籍コンテンツをウェブページに直接埋め込むことができます。また、API は書籍のプレビューを操作するためのユーティリティも提供しており、多くの場合、このサイトで説明する他の API と合わせて使用されます。

プレビューウィザードは、Embedded Viewer API 上に構築されたツールで、2 行のコードをコピーするだけでサイトにプレビュー機能を簡単に追加できます。このドキュメントは、サイトでのサイトの表示をカスタマイズしたい上級デベロッパーを対象としています。

視聴者

このドキュメントは、JavaScript のプログラミングとオブジェクト指向プログラミングの概念を理解しているデベロッパーを対象にしています。また、ユーザーの視点で Google ブックスに精通している必要があります。ウェブ上に多数ある JavaScript チュートリアルも参考にしてください。

このドキュメントは、Embedded Viewer API を使用して優れたアプリケーションの調査と開発をすぐに開始できるように作られています。上級ユーザーは、Embedded Viewer API Reference に興味があるかもしれません。サポートされているメソッドとレスポンスに関する総合的な詳細情報をご覧いただけます。

上記のように、プレビューウィザードを使用すると、基本的なプレビューをサイトに埋め込むために必要なコードが自動的に生成されます。

Embedded Viewer API の「Hello, World」

Embedded Viewer API について学習するには、簡単な例を見るのが最も簡単な方法です。次のウェブページには、Nicholas Perry 氏による ISBN 0738531367（Arcadia Publishing の「Images of America」シリーズの一部）によるマウンテンビューの 600x500 プレビューが表示されています。

<!DOCTYPE html "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
    <title>Google Books Embedded Viewer API Example</title>
    <script type="text/javascript" src="https://www.google.com/books/jsapi.js"></script>
    <script type="text/javascript">
      google.books.load();

      function initialize() {
        var viewer = new google.books.DefaultViewer(document.getElementById('viewerCanvas'));
        viewer.load('ISBN:0738531367');
      }

      google.books.setOnLoadCallback(initialize);
    </script>
  </head>
  <body>
    <div id="viewerCanvas" style="width: 600px; height: 500px"></div>
  </body>
</html>

この例を確認してダウンロードして、編集し、試してみてください。簡単な例ですが、次の 5 つの点に注意してください:

script タグを使用する API ローダを含めます。
視聴者を保持する「viewerCanvas」という名前の div 要素を作成します。
「viewer」オブジェクトを作成する JavaScript 関数を作成します。
書籍は一意の識別子（この場合は ISBN:0738531367）を使用して読み込まれます。
API が完全に読み込まれたときに、google.books.setOnLoadCallback を使用して initialize を呼び出す。

上記のステップについて以下で説明します。

Embedded Viewer API の読み込み

API Loader フレームワークを使用して Embedded Viewer API を読み込むのは、比較的簡単です。これには次の 2 つのステップが必要です。

API Loader ライブラリを含めます。

<script type="text/javascript" src="https://www.google.com/books/jsapi.js"></script>

google.books.load メソッドを呼び出します。google.books.load メソッドは、コールバック関数または言語を指定するオプションの list パラメータを受け取ります。これについては、以下をご覧ください。
```
<script type="text/javascript">
  google.books.load();
</script>
```

ローカライズされた Embedded Viewer API の読み込み

Embedded Viewer API では、ツールチップ、コントロールの名前、リンクテキストなどのテキスト情報を表示するときに、デフォルトで英語が使用されます。特定の言語で情報を適切に表示するように Embedded Viewer API を変更する場合は、google.books.load 呼び出しにオプションの language パラメータを追加できます。

たとえば、ブラジルポルトガル語のインターフェース言語で書籍プレビューモジュールを表示するには、次のようにします。

<script type="text/javascript">
  google.books.load({"language": "pt-BR"});
</script>

サンプルを表示（book-language.html）

現在サポートされている RFC 3066 言語コードには、af、ar、hy、bg、ca、zh-CN、zh-TW、hr、cs、da、nl、en、fil、fi、fr、de、el、彼、hu、is、it、ja、ko、l、l、l、l、l、l、l、l、l、l、l、l、l、l、l、l、l、l、l、l、l、l、l、l、l、l、l、l、l、l、l、l

Embedded Viewer API を英語以外の言語で使用する場合は、content-type ヘッダーを utf-8 に設定したページ、または同等の <meta> タグをページに含めることを強くおすすめします。これにより、すべてのブラウザで文字が正しくレンダリングされます。詳細については、W3C の HTTP 文字セットパラメータの設定ページをご覧ください。

閲覧者の DOM 要素

<div id="viewerCanvas" style="width: 600px; height: 500px"></div>

ウェブページに書籍を表示するには、書籍用のスペースを確保する必要があります。通常、これは名前付きの div 要素を作成して、ブラウザのドキュメントオブジェクトモデル（DOM）内でこの要素への参照を取得することで行います。

上の例では、「viewerCanvas」という名前の div を定義し、スタイル属性を使用してサイズを設定しています。閲覧者はコンテナのサイズを暗黙的に使用して、自身のサイズを設定します。

DefaultViewer オブジェクト

var viewer = new google.books.DefaultViewer(document.getElementById('viewerCanvas'));

ページ上の単一のビューアを作成して制御する JavaScript クラスは、DefaultViewer クラスです。（このクラスの複数のインスタンスを作成できます。各オブジェクトはページ上の個別のビューアを定義します）。このクラスの新しいインスタンスは、JavaScript の new 演算子を使用して作成されます。

新しいビューアインスタンスを作成する場合は、ビューアのコンテナとしてページ内の DOM ノード（通常は div 要素）を指定します。HTML ノードは JavaScript document オブジェクトの子要素であり、document.getElementById() メソッドを使用してこの要素への参照を取得します。

このコードは、変数（名前は viewer）を定義して、その変数を新しい DefaultViewer オブジェクトに割り当てます。関数 DefaultViewer() はコンストラクタと呼ばれます。その定義（Embedded Viewer API リファレンスからわかりやすく要約）は次のとおりです。

コンストラクタ	説明
DefaultViewer（コンテナ、オプトイン）	指定された HTML `container` 内に新しいビューアを作成します。これはページのブロックレベルの要素（通常は `DIV`）である必要があります。高度なオプションは、オプションの `opts` パラメータを使用して渡されます。

コンストラクタの 2 番目のパラメータは省略できます。このドキュメントの範囲外の高度な実装に使用し、「Hello, World」の例では省略しています。

特定の書籍で閲覧者を初期化する

  viewer.load('ISBN:0738531367');

DefaultViewer コンストラクタでビューアを作成したら、特定の書籍を使用して初期化する必要があります。この初期化は、ビューアの load() メソッドを使用して行います。load() メソッドには、表示する書籍について API に伝える identifier 値が必要です。このメソッドは、ビューアオブジェクトに対して他のオペレーションが実行される前に送信する必要があります。

文庫版の ISBN コードや代替 OCLC 番号など、書籍に複数の識別情報がある場合は、load() 関数の最初のパラメータとして識別子文字列の配列を渡すことができます。配列内のいずれかの識別子に埋め込み可能なプレビューがある場合、ビューアに書籍がレンダリングされます。

サポートされている書籍識別情報

Dynamic Links 機能と同様に、Embedded Viewer API では特定の書籍を識別するためのさまざまな値がサポートされています。下記はその一例です。

ISBN: 10 桁または 13 桁の一意の国際標準図書番号。
例: ISBN:0738531367
OCLC 番号: 書籍のレコードが WorldCat カタログシステムに追加されたときに OCLC によって書籍に割り当てられた一意の番号。
例: OCLC:70850767
LCCN（# スペースが限られている場合は「LCCN」も可）: 米国議会図書館によってレコードに割り当てられた米国議会図書館番号。
例: LCCN:2006921508
Google ブックスのボリューム ID: 書籍に割り当てられた URL の、Google ブックスで割り当てられている固有の文字列。
例: Py8u3Obs4f4C
Google ブックスのプレビュー URL: Google ブックスで書籍のプレビューページを開く URL。
例: https://books.google.com/books?id=Py8u3Obs4f4C&printsec=frontcover

これらの識別子は、多くの場合、Google Books API ファミリーの他の API で使用されます。たとえば、Dynamic Links は、書籍が埋め込み可能な場合にのみプレビューボタンをレンダリングし、ユーザーがボタンをクリックしたときに、Dynamic Links 呼び出しによって返されたプレビュー URL を使用してビューアをインスタンス化できます。同様に、Books API を使用して、閲覧やプレビューを行うリッチなアプリケーションを構築できます。この API は、Volume フィードで適切な業界 ID を返します。高度な実装については、サンプルページをご覧ください。

初期化が失敗した場合の処理

load の呼び出しが失敗することがあります。一般に、これは、指定された ID に関連付けられている書籍が API で見つからない場合、書籍のプレビューが利用できない場合、書籍のプレビューを埋め込むことができない場合、地域的な制限がある場合にエンドユーザーにその書籍が表示されない場合に発生します。コードがこのような状態を適切に処理できるように、このようなエラーのアラートを受け取ることをおすすめします。このため、load 関数ではオプションの 2 つ目のパラメータ notFoundCallback を渡すことができます。これは、書籍を読み込めない場合にどの関数を呼び出すかを示します。たとえば次のコードでは、書籍を埋め込むことができる場合に JavaScript の「アラート」ボックスが生成されます。

function alertNotFound() {
  alert("could not embed the book!");
}

function initialize() {
  var viewer = new google.books.DefaultViewer(document.getElementById('viewerCanvas'));
  viewer.load('ISBN:1234', alertNotFound);
}

例を表示（book-notfound.html）

このコールバックを使用して同様のエラーを表示するか、viewerCanvas 要素を完全に非表示にすることもできます。エラーコールバックパラメータはオプションであり、「Hello World」の例には含まれていません。

注: プレビューは、すべての書籍とすべてのユーザーが利用できるわけではないため、プレビューを読み込む前にプレビューが利用可能かどうかを知る方法をおすすめします。たとえば、プレビューを実際にユーザーが利用できる場合のみ、UI に [Google プレビュー] ボタン、ページ、セクションを表示します。これを行うには、Books API または Dynamic Links を使用します。どちらも、ビューアを使用して書籍の埋め込みが可能かどうかをレポートします。

成功した初期化の処理

また、書籍が正常に読み込まれたかどうか、またいつ読み込まれたのかを把握しておくと便利です。このため、load 関数ではオプションの 3 つ目のパラメータ successCallback がサポートされています。このパラメータは、書籍の読み込みが完了したときに実行されます。

function alertInitialized() {
  alert("book successfully loaded and initialized!");
}

function initialize() {
  var viewer = new google.books.DefaultViewer(document.getElementById('viewerCanvas'));
  viewer.load('ISBN:0738531367', null, alertInitialized);
}

例を表示（book-success.html）

このコールバックは、たとえば、ビューアが完全にレンダリングされた場合にのみページ上の特定の要素を表示したい場合に役立ちます。

読み込み時に視聴者を表示する

  google.books.setOnLoadCallback(initialize);

HTML ページがレンダリングされている間、ドキュメントオブジェクトモデル（DOM）が作成され、外部の画像とスクリプトが取得されて document オブジェクトに組み込まれます。ページが完全に読み込まれた後にのみページにビューアを配置するには、google.books.setOnLoadCallback 関数を使用して、DefaultViewer オブジェクトを作成する関数の実行を遅らせます。setOnLoadCallback は、Embedded Viewer API が読み込まれて使用できる状態になった場合にのみ initialize を呼び出すため、予期しない動作を回避し、ビューアを描画する方法とタイミングを制御できます。

注: クロスブラウザの互換性を最大化するには、<body> タグに onLoad イベントを使用するのではなく、google.books.setOnLoadCallback 関数を使用して視聴者の読み込みをスケジュール設定することを強くおすすめします。

視聴者の操作

DefaultViewer オブジェクトを取得したら、操作できます。基本的なビューアオブジェクトは、Google ブックスのウェブサイトで操作するビューアと見た目や動作が異なり、さまざまな組み込み動作があります。

視聴者はプログラムを使って操作することもできます。DefaultViewer オブジェクトは、プレビュー状態を直接変更するいくつかのメソッドをサポートしています。たとえば、zoomIn()、nextPage()、highlight() メソッドは、ユーザー操作ではなく、プログラムによって閲覧者に対して動作します。

次の例では、3 秒ごとに自動的に「次のページ」に切り替わる書籍プレビューを表示しています。次のページがビューアの表示部分にある場合、ビューアはスムーズにパンします。そうでない場合、視聴者は次のページの最上部に直接移動します。

function nextStep(viewer) {
  window.setTimeout(function() {
    viewer.nextPage();
    nextStep(viewer);
  }, 3000);
}

function initialize() {
  var viewer = new google.books.DefaultViewer(document.getElementById('viewerCanvas'));
  viewer.load('ISBN:0738531367');
  nextStep(viewer);
}

google.books.setOnLoadCallback(initialize);

例を表示（book-animate.html）

閲覧者が特定の書籍を使用して完全に初期化するまで、閲覧者へのプログラムによる呼び出しは失敗するか、効果がありません。ビューアの準備ができたときにのみこれらの関数を呼び出すには、上記のように viewer.load の successCallback パラメータを使用します。

DefaultViewer オブジェクトでサポートされているすべての関数については、リファレンスガイドをご覧ください。

プログラミングメモ

Embedded Viewer API の使用を開始する前に、お使いのアプリが意図したプラットフォーム上でスムーズに動作するように、以下の留意点をご確認ください。

ブラウザの互換性

Embedded Viewer API は、Internet Explorer、Firefox、Safari の最新バージョンと、通常は Camino や Google Chrome などの Gecko ベースや WebKit ベースのブラウザをサポートしています。

互換性のないブラウザを使用しているユーザーに対しては、アプリケーションごとに異なる動作が必要となる場合があります。 Embedded Browser API は互換性のないブラウザを検出した場合、自動的には動作しません。このドキュメントのほとんどの例では、ブラウザの互換性は確認しません。古いブラウザの場合はエラーメッセージを表示しません。実際のアプリケーションでは、古いブラウザや互換性のないブラウザのほうが使いやすい場合がありますが、例を読みやすくするためにこのようなチェックは省略しています。

重要なアプリケーションの場合、ブラウザとプラットフォームの間で不整合が発生することは避けられません。quirksmode.org などのサイトも、回避策を見つけるのに便利です。

XHTML と後方互換モード

ビューアを含むページでは、規格に準拠した XHTML を使用することをおすすめします。ブラウザが XHTML DOCTYPE をページ上部に表示する場合、ページを「標準コンプライアンスモード」でレンダリングするため、ブラウザ間でレイアウトと動作がはるかに予測しやすくなります。この定義がないページの場合、「互換モード」でレンダリングすると、レイアウトに一貫性がなくなる可能性があります。

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

Embedded Viewer API の例に関する注意事項

なお、このドキュメントの例のほとんどは、HTML ファイル全体ではなく、関連する JavaScript コードのみを示しています。この JavaScript コードを独自のスケルトン HTML ファイルに接続するか、サンプルの後のリンクをクリックして各サンプルの完全な HTML ファイルをダウンロードできます。

トラブルシューティング

コードが機能していないと思われる場合は、次の方法をお試しください。

入力ミスを探します。JavaScript では大文字と小文字が区別されることに注意してください。
JavaScript デバッガを使用します。Firefox では、JavaScript コンソール、Venkman Debugger、または Firebug アドオンを使用できます。IE では、Microsoft Script Debugger を使用できます。Google Chrome ブラウザには、DOM インスペクタや JavaScript デバッガなど、さまざまな開発ツールが組み込まれています。

デベロッパー ガイド

視聴者