개발자 가이드

Embedded Viewer API를 사용하면 JavaScript로 Google 도서의 도서 콘텐츠를 웹페이지에 직접 삽입할 수 있습니다. 또한 API는 도서 미리보기를 조작하기 위한 여러 유틸리티를 제공하며 이 사이트에 설명된 다른 API와 함께 사용되는 경우가 많습니다.

미리보기 마법사는 Embedded Viewer API를 기반으로 구축된 도구로, 코드 몇 줄만 복사하면 사이트에 미리보기 기능을 손쉽게 추가할 수 있습니다. 이 문서는 뷰어가 사이트에 표시되는 방식을 맞춤설정하려는 고급 개발자를 대상으로 합니다.

시청자층

이 문서는 JavaScript 프로그래밍 및 객체 지향 프로그래밍 개념에 익숙한 개발자를 위해 작성되었습니다. 개발자는 사용자 관점에서 Google 도서에도 익숙해야 합니다. 웹에 다양한 JavaScript 튜토리얼이 있습니다.

이 문서는 완전하며 완전하지 않습니다. Embedded Viewer API를 사용하여 유용한 애플리케이션을 빠르게 개발하고 개발할 수 있도록 설계되었습니다. 고급 사용자는 지원되는 메서드와 응답에 관한 포괄적인 세부정보를 제공하는 Embedded Viewer API 참조를 살펴보는 것이 좋습니다.

위에서 설명한 것처럼 초보자는 사이트에 기본 미리보기를 삽입하는 데 필요한 코드를 자동으로 생성하는 미리보기 마법사를 사용하는 것이 좋습니다.

Embedded Viewer API의 'Hello, World'

Embedded Viewer API에 대해 가장 쉽게 배울 수 있는 방법은 간단한 예를 보는 것입니다. 다음 웹페이지는 Nicholas Perry ISBN 0738531367 (Arcadia Publishing의 'Images of America' 시리즈의 일부)의 Mountain View에 대한 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>

이 예를 보고 다운로드하여 편집하고 활용해 볼 수 있습니다. 이 간단한 예제에서도 다섯 가지 주의할 사항이 있습니다.

  1. script 태그를 사용하여 API 로더를 포함합니다.
  2. 뷰어를 보유할 'viewerCanvas'라는 div 요소를 만듭니다.
  3. 'viewer' 객체를 만드는 JavaScript 함수를 작성합니다.
  4. 고유 식별자 (이 경우 ISBN:0738531367)를 사용하여 책을 로드합니다.
  5. API가 완전히 로드되면 google.books.setOnLoadCallback를 사용하여 initialize를 호출합니다.

각 단계의 내용은 아래와 같습니다.

Embedded Viewer API 로드

API 로더 프레임워크를 사용하여 Embedded Viewer API를 로드하는 것은 비교적 간단합니다. 다음 두 단계를 포함합니다.

  1. API 로더 라이브러리를 포함합니다.
    <script type="text/javascript" src="https://www.google.com/books/jsapi.js"></script>
  2. 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, he, hu, is, id, it, ja, ko, lv, lt, ms - , ja, ko, lv, lt, , , , , , , , , , , , , , , , , ,

영어 이외의 언어로 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(container, opts?) 지정된 HTML container 내에 새 뷰어를 만듭니다. 이 뷰어는 페이지의 블록 수준 요소 (일반적으로 DIV)여야 합니다. 고급 옵션은 선택적 opts 매개변수를 사용하여 전달됩니다.

생성자의 두 번째 매개변수는 선택사항이며(이 문서의 범위를 벗어나는 고급 구현을 위한 것이므로) 'Hello, World' 예에서는 생략됩니다.

특정 도서로 뷰어 초기화하기

  viewer.load('ISBN:0738531367');

DefaultViewer 생성자를 통해 뷰어를 만든 후에는 특정 도서로 뷰어를 초기화해야 합니다. 이 초기화는 뷰어의 load() 메서드를 사용하여 실행됩니다. load() 메서드에는 표시할 도서를 API에 알려주는 identifier 값이 필요합니다. 이 메서드는 뷰어 객체에서 다른 작업이 실행되기 전에 전송되어야 합니다.

도서에 관한 여러 식별자(문고판의 ISBN 또는 대체 OCLC 번호)를 알고 있는 경우 식별자 문자열 배열을 첫 번째 매개변수로 load() 함수에 전달할 수 있습니다. 배열의 식별자 중 하나라도 연결된 삽입 가능한 미리보기가 있는 경우 뷰어가 도서를 렌더링합니다.

지원되는 도서 식별자

동적 링크 기능과 마찬가지로 Embedded Viewer API는 특정 도서를 식별하기 위한 여러 값을 지원합니다. 예를 들면

ISBN
10자리 또는 13자리의 고유한 상업용 국제 표준 도서 번호입니다.
예: ISBN:0738531367
OCLC 번호
도서의 기록이 WorldCat 카탈로그 시스템에 추가될 때 OCLC에서 도서에 할당한 고유 번호입니다.
예: OCLC:70850767
미국 국회도서관 제어번호(LCCN)
미국 의회도서관에서 이 기록에 할당한 의회 도서관 통제 번호입니다.
예: LCCN:2006921508
Google 도서 볼륨 ID
Google 도서에서 권에 할당한 고유한 문자열로, Google 도서의 도서 URL에 표시됩니다.
예: Py8u3Obs4f4C
Google 도서 미리보기 URL
Google 도서에서 도서 미리보기 페이지를 여는 URL입니다.
예: https://books.google.com/books?id=Py8u3Obs4f4C&printsec=frontcover

이러한 식별자는 종종 Google Books API 제품군의 다른 API와 함께 사용됩니다. 예를 들어 도서를 삽입할 수 있는 경우에만 동적 링크를 사용하여 미리보기 버튼을 렌더링하고 사용자가 버튼을 클릭하면 동적 링크 호출로 반환된 미리보기 URL을 사용하여 뷰어를 인스턴스화할 수 있습니다. 볼륨 피드에 여러 적절한 업종 식별자를 반환하는 Books API를 사용하여 풍부한 탐색 및 미리보기 애플리케이션을 빌드할 수도 있습니다. 예시 페이지에서 몇 가지 고급 구현 방법을 살펴보세요.

초기화 실패 처리

경우에 따라 load 호출이 실패할 수 있습니다. 일반적으로 API가 제공된 식별자와 연결된 도서를 찾을 수 없거나, 도서의 미리보기가 없거나, 도서 미리보기를 삽입할 수 없거나, 지역 제한으로 인해 최종 사용자가 특정 도서를 볼 수 없는 경우에 발생합니다. 코드가 이 조건을 적절하게 처리할 수 있도록 이러한 실패에 대해 알림을 받는 것이 좋습니다. 따라서 load 함수를 사용하면 책을 로드할 수 없을 때 호출해야 하는 함수를 나타내는 두 번째 매개변수(선택사항)인 notFoundCallback를 전달할 수 있습니다. 예를 들어 다음 코드는 도서를 삽입할 수 있는 경우 자바스크립트 '알림' 상자를 생성합니다.

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 또는 동적 링크를 사용하여 확인할 수 있습니다. 둘 다 뷰어를 사용하여 도서를 삽입할 수 있는지 여부를 보고합니다.

성공적인 초기화 처리

도서가 성공적으로 로드되었는지 여부와 로드 시점을 알면 유용할 수 있습니다. 따라서 load 함수는 도서 로드가 완료되면 실행되는 선택적 세 번째 매개변수인 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)

뷰어에 대한 프로그래매틱 호출은 뷰어가 특정 도서로 완전히 초기화될 때까지 실패하거나 아무런 영향을 미치지 않습니다. 뷰어가 준비되었을 때만 이러한 함수를 호출하려면 위에서 설명한 대로 successCallback 매개변수를 사용하여 viewer.load하세요.

DefaultViewer 객체에서 지원하는 모든 함수에 대한 자세한 내용은 참조 가이드를 확인하세요.

프로그래밍 참고사항

Embedded Viewer API를 알아보기 전에 애플리케이션이 의도한 플랫폼에서 원활하게 작동하도록 다음 사항에 유의해야 합니다.

브라우저 호환성

Embedded Viewer API는 Internet Explorer, Firefox, Safari의 최신 버전, 그리고 일반적으로 Camino 및 Google Chrome과 같은 기타 Gecko 및 WebKit 기반 브라우저도 지원합니다.

경우에 따라 애플리케이션은 호환되지 않는 브라우저를 사용하는 사용자에게 다른 동작을 요구하기도 합니다. Embedded Viewer 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 코드만 보여줍니다. 자바스크립트 코드를 자체 기본 HTML 파일에 연결하거나, 예 다음에 나오는 링크를 클릭하여 각 예의 전체 HTML 파일을 다운로드할 수 있습니다.

문제 해결

코드가 작동하지 않는 것 같으면 다음과 같은 방법으로 문제를 해결할 수 있습니다.

  • 오타를 찾습니다. 자바스크립트는 대소문자를 구분하는 언어입니다.
  • Javascript 디버거를 사용합니다. Firefox에서는 JavaScript 콘솔, Venkman Debugger 또는 Firebug 부가기능을 사용할 수 있습니다. IE에서는 Microsoft Script Debugger를 사용할 수 있습니다. Chrome 브라우저에는 DOM 검사기 및 자바스크립트 디버거를 비롯한 여러 개발 도구가 내장되어 있습니다.