개발자 가이드

Embedded Viewer API를 사용하면 자바스크립트로 웹페이지에 직접 Google 도서의 도서 콘텐츠를 삽입할 수 있습니다. 또한 API는 책 미리보기를 조작하기 위한 여러 유틸리티를 제공하며 이 사이트에서 설명하는 다른 API와 함께 자주 사용됩니다.

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

시청자층

이 문서는 자바스크립트 프로그래밍 및 객체 지향 프로그래밍 개념에 익숙한 개발자를 위해 작성되었습니다. 또한 사용자의 관점에서 Google 도서에 익숙해져야 합니다. 웹에서 여러 자바스크립트 튜토리얼을 사용할 수 있습니다.

이 개념 문서는 완전하지 않습니다. 이 문서는 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. 자바스크립트 함수를 작성하여 '뷰어' 객체를 만듭니다.
  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 메서드는 아래에 설명된 대로 콜백 함수 또는 언어를 지정하는 선택적 목록 매개변수를 사용합니다. 
    <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, lt, tr, ms, pt, ms, ts, ms, ts, ms, ts, ms, ms, ms, ms, ms, ms, ms, ms, ms, ms, ms, tr, ms

Embedded Viewer API를 영어 이외의 언어로 사용할 때는 content-type 헤더를 utf-8로 설정하거나 페이지에 상응하는 <meta> 태그를 포함하여 페이지를 제공하는 것이 좋습니다. 이렇게 하면 모든 브라우저에서 문자가 올바르게 렌더링됩니다. 자세한 내용은 HTTP 문자 집합 매개변수 설정에 관한 W3C 페이지를 참고하세요.

뷰어 DOM 요소

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

웹페이지에 책을 표시하려면 책의 자리를 예약해야 합니다. 일반적으로 이름이 지정된 div 요소를 만들고 브라우저의 DOM (문서 객체 모델)에서 이 요소에 대한 참조를 가져옵니다.

위의 예에서는 'viewerCanvas'라는 div를 정의하고 스타일 속성을 사용하여 크기를 설정합니다. 뷰어는 암시적으로 컨테이너의 크기를 사용하여 자체 크기를 조정합니다.

DefaultViewer 객체

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

페이지에서 단일 뷰어를 만들고 제어하는 자바스크립트 클래스는 DefaultViewer 클래스입니다. (이 클래스의 인스턴스를 두 개 이상 만들 수 있습니다. 각 객체는 페이지에 별도의 뷰어를 정의합니다.) 자바스크립트 new 연산자를 사용하여 이 클래스의 새 인스턴스를 만듭니다.

새 뷰어 인스턴스를 만들 때 페이지의 DOM 노드 (일반적으로 div 요소)를 뷰어의 컨테이너로 지정합니다. HTML 노드는 자바스크립트 document 객체의 하위 요소이며 document.getElementById() 메서드를 통해 이 요소에 대한 참조를 가져올 수 있습니다.

이 코드는 viewer이라는 변수를 정의하고 이 변수를 새 DefaultViewer 객체에 할당합니다. DefaultViewer() 함수는 생성자라고 하며 그 정의 (삽입된 뷰어 API 참조에서 명확성을 위해 압축됨)는 다음과 같습니다.

생성자 설명
DefaultViewer(컨테이너, 선택 여부) 지정된 HTML container 내에 새 뷰어를 만듭니다. 이 뷰어는 페이지의 블록 수준 요소 (일반적으로 DIV)여야 합니다. opts 옵션은 선택사항으로 고급 옵션을 사용하여 전달됩니다.

생성자의 두 번째 매개변수는 선택사항이며(이 문서의 범위를 벗어나는 고급 구현용) '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
LCN
의회 도서관이 기록에 할당한 의회도서관 제어 번호
예: 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 미리보기' 버튼, 페이지 또는 섹션을 표시할 수 있습니다. 도서 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 파일이 아닌 관련 자바스크립트 코드만 표시합니다. 자바스크립트 코드를 자체 스켈레톤 HTML 파일에 연결하거나 예시 다음에 있는 링크를 클릭하여 각 예시의 전체 HTML 파일을 다운로드할 수 있습니다.

문제 해결

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

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