개발자 가이드

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

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

잠재고객

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

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

위에 표시된 대로 초보자는 사이트에 기본 미리보기를 삽입하는 데 필요한 코드를 자동으로 생성하는 미리보기 마법사를 먼저 사용해 보세요.

Embedded Viewer API의 'Hello, World'

Embedded Viewer API에 대해 배우는 가장 쉬운 방법은 간단한 예를 보는 것입니다. 다음 웹페이지에는 니콜라스 페리 저, ISBN 0738531367(아르카디아 출판사의 '미국의 이미지' 시리즈 중 하나)의 마운틴뷰(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. '뷰어' 객체를 만드는 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 메서드는 아래에 설명된 대로 콜백 함수 또는 언어를 지정하는 선택적 목록 매개변수를 사용합니다. 
    <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에서 현재 지원되는 RFC 3066 언어 코드에는 af, ar, hy, bg, 대부분의 af, ar, hy, bg, 의 af, ar, hy, bg, ca, af, ar, hy, bg, ca, zh-CN, zh-

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() 함수는 constructor라고 하며 다음과 같이 정의됩니다 ( 내장 뷰어 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를 전달할 수 있습니다. 이 매개변수는 도서를 로드할 수 없는 경우 호출해야 하는 함수를 나타냅니다. 예를 들어 다음 코드는 도서를 삽입할 수 있는 경우 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 또는 동적 링크를 사용하면 됩니다. 두 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 코드만 보여줍니다. JavaScript 코드를 자체 스켈레톤 HTML 파일에 연결하거나 예시 뒤의 링크를 클릭하여 각 예시의 전체 HTML 파일을 다운로드할 수 있습니다.

문제 해결

코드가 작동하지 않는 것 같으면 다음과 같은 접근 방식을 통해 문제를 해결해 보세요.

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