Guia do desenvolvedor

A API Embed Viewer permite que você incorpore o conteúdo de livros do Google Livros diretamente nas suas páginas da Web com JavaScript. A API também fornece vários utilitários para manipular visualizações de livros e é frequentemente usada com outras APIs descritas neste site.

O Assistente de visualização é uma ferramenta criada na API Embed Viewer que facilita a adição de recursos de visualização ao site copiando apenas algumas linhas de código. Este documento é destinado a desenvolvedores mais avançados que querem personalizar a forma como o visualizador aparece nos sites.

Público

Esta documentação foi projetada para pessoas familiarizadas com a programação JavaScript e com conceitos de programação voltados a objetos. Você também precisa conhecer o Google Livros do ponto de vista de um usuário. Há muitos tutoriais de JavaScript disponíveis na Web.

Esta documentação conceitual não está completa e completa. Ela foi projetada para permitir que você comece rapidamente a explorar e desenvolver aplicativos interessantes com a API Embedded Viewer. Talvez os usuários avançados se interessem pela Referência da API Embed Viewer, que fornece detalhes abrangentes sobre respostas e métodos compatíveis.

Como indicado acima, os iniciantes podem começar com o Assistente de visualização, que gera automaticamente o código necessário para incorporar visualizações básicas ao seu site.

"Hello, World" da API Embedded Viewer

A maneira mais fácil de começar a conhecer a API Embedded Viewer é ver um exemplo simples. A página da Web a seguir exibe uma visualização de 600 x 500 de Mountain View, por Nicholas Perry, ISBN 0738531367 (parte da série "Images of America" da Arcadia Publishing):

<!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>

Confira este exemplo e faça o download para editar e testar ele. Mesmo neste exemplo simples, há cinco itens a observar:

  1. Incluímos o carregador de API usando uma tag script.
  2. Criamos um elemento div chamado "viewerCanvas" para armazenar o visualizador.
  3. Escrevemos uma função JavaScript para criar um objeto "viewer".
  4. Carregamos o livro usando o identificador exclusivo (neste caso, ISBN:0738531367).
  5. Usamos google.books.setOnLoadCallback para chamar initialize quando a API estiver totalmente carregada.

Essas etapas são explicadas a seguir:

Como carregar a API Embedded Viewer

Usar a estrutura do carregador de API para carregar a API Embedded Viewer é relativamente simples. Isso envolve as duas etapas a seguir:

  1. Inclua a biblioteca de API Loader: 
    <script type="text/javascript" src="https://www.google.com/books/jsapi.js"></script>
  2. Invoque o método google.books.load. O método google.books.load usa um parâmetro de lista opcional que especifica uma função ou um idioma de callback, conforme explicado abaixo. 
    <script type="text/javascript">
  google.books.load();
</script>

Como carregar uma versão localizada da API Embedded Viewer

Por padrão, a API Embed Viewer usa o inglês para exibir informações textuais, como dicas, nomes de controles e texto de link. Se você quiser mudar a API Embedded Viewer para exibir informações corretamente em um idioma específico, adicione um parâmetro language opcional à chamada google.books.load.

Por exemplo, para exibir um módulo de visualização de livro com o idioma da interface em português do Brasil:

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

Veja um exemplo (book-language.html)

Atualmente, os códigos de idioma RFC 3066 compatíveis são af, ar, hy, bg, ca, zh-CN, zh-TW, hr, cs, da, nl, en, fil, fi, fr, de, el, he, hu, is, id, it, i, pp, pp, .

Ao usar a API Embedded Viewer em idiomas diferentes do inglês, recomendamos que você veicule sua página com um cabeçalho content-type definido como utf-8 ou incluir uma tag <meta> equivalente. Isso ajuda a garantir que os caracteres sejam renderizados corretamente em todos os navegadores. Para mais informações, consulte a página do W3C sobre como configurar o parâmetro de conjunto de caracteres HTTP.

Elementos DOM do leitor

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

Para que um livro seja exibido em uma página da Web, é necessário reservar um lugar para ele. Geralmente, isso é feito criando um elemento div nomeado e recebendo uma referência a ele no modelo de objeto de documentos (DOM) do navegador.

O exemplo acima define uma div chamada "viewerCanvas" e define o tamanho usando atributos de estilo. O visualizador usa implicitamente o tamanho do contêiner para se ajustar.

O objeto DefaultViewer

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

A classe JavaScript que cria e controla um único visualizador na página é a DefaultViewer. É possível criar mais de uma instância dessa classe. Cada objeto define um visualizador separado na página. Uma nova instância dessa classe é criada usando o operador JavaScript new.

Ao criar uma nova instância de visualizador, você especifica um nó DOM na página (geralmente um elemento div) como um contêiner para o visualizador. Os nós HTML são filhos do objeto JavaScript document, e recebemos uma referência a esse elemento pelo método document.getElementById().

Esse código define uma variável (chamada viewer) e a atribui a um novo objeto DefaultViewer. A função DefaultViewer() é conhecida como construtor, e a definição, condensada, para fins de clareza da Referência da API Embed Viewer, é mostrada abaixo:

Construtor Descrição
DefaultViewer(container, opts?) Cria um novo leitor dentro do container HTML fornecido, que precisa ser um elemento de nível de bloco na página (normalmente, um DIV). As opções avançadas são transmitidas usando o parâmetro opts opcional.

O segundo parâmetro no construtor é opcional e destinado a implementações avançadas, além do escopo deste documento. Ele é omitido do exemplo "Hello, World".

Inicializar o leitor com um livro específico

  viewer.load('ISBN:0738531367');

Depois de criar um visualizador com o construtor DefaultViewer, ele precisa ser inicializado com um livro específico. Essa inicialização é feita com o uso do método load() do visualizador. O método load() requer um valor identifier, que informa à API qual livro exibir. Esse método precisa ser enviado antes que outras operações sejam realizadas no objeto visualizador.

Se você conhece vários identificadores de um livro, como o ISBN da edição em brochura ou números alternativos da OCLC, pode transmitir uma matriz de strings de identificador como o primeiro parâmetro para a função load(). O leitor renderizará o livro se houver uma visualização incorporável associada a qualquer um identificador na matriz.

Identificadores de livros compatíveis

Assim como o recurso Dynamic Links, a API Embed Viewer oferece suporte a vários valores para identificar um livro específico. São elas:

ISBN
O número padrão internacional do livro (em inglês) comercial exclusivo de 10 ou 13 dígitos.
Exemplo: ISBN:0738531367
Número OCLC
O número exclusivo atribuído a um livro pela OCLC quando o registro dele é adicionado ao sistema de catálogo do WorldCat.
Exemplo: OCLC:70850767
CLC
O número de controle da Biblioteca do Congresso atribuído ao registro da Biblioteca do Congresso.
Exemplo: LCCN:2006921508
ID do volume do Google Livros
A string exclusiva atribuída pelo Google Livros ao volume, que aparece no URL do livro no Google Livros.
Exemplo: Py8u3Obs4f4C
URL de visualização do Google Livros
Um URL que abre uma página de visualização de livros no Google Livros.
Exemplo: https://books.google.com/books?id=Py8u3Obs4f4C&printsec=frontcover

Esses identificadores geralmente são usados com outras APIs na família de APIs do Google Livros. Por exemplo, é possível usar o Dynamic Links para renderizar um botão de visualização somente se o livro for incorporável. Depois, quando o usuário clicar no botão, instancie um leitor usando o URL de visualização retornado pela chamada do Dynamic Links. Da mesma forma, é possível criar um aplicativo avançado de navegação e visualização com a API Books, que retorna vários identificadores adequados do setor nos feeds de volumes. Acesse a página de exemplos para conferir algumas implementações avançadas.

Como lidar com inicializações com falha

Em alguns casos, a chamada de load pode falhar. Normalmente, isso ocorre quando a API não consegue encontrar um livro associado ao identificador fornecido, quando não há visualização do livro disponível, quando a visualização do livro não pode ser incorporada ou quando as restrições territoriais impedem que o usuário final veja esse livro específico. É possível receber um alerta sobre essa falha para que seu código possa gerenciar essa condição normalmente. Por isso, a função load permite que você transmita um segundo parâmetro opcional, notFoundCallback, que indica qual função precisa ser chamada se o livro não puder ser carregado. Por exemplo, o código a seguir vai gerar uma caixa "alerta" JavaScript caso o livro possa ser incorporado:

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

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

Ver exemplo (book-notfound.html)

Usando esse callback, você pode exibir um erro semelhante ou ocultar completamente o elemento viewerCanvas. O parâmetro de callback de falha é opcional e não está incluído no exemplo "Hello World".

Observação: como as prévias podem não estar disponíveis para todos os livros e usuários, pode ser útil saber se uma visualização está disponível antes de tentar carregar um leitor para ela. Por exemplo, talvez você queira mostrar um botão, uma página ou seção "Visualização do Google" na IU apenas se uma visualização estiver disponível para o usuário. Faça isso usando a API Books ou o Dynamic Links, que informam se um livro estará disponível para incorporação usando o leitor.

Como gerenciar inicializações bem-sucedidas

Também pode ser útil saber se e quando um livro foi carregado. Por esse motivo, a função load é compatível com um terceiro parâmetro opcional, successCallback, que será executado se e quando o carregamento do livro for concluído.

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

Ver exemplo (book-success.html)

Esse callback pode ser útil se, por exemplo, você só quiser mostrar determinados elementos na sua página se o visualizador tiver sido totalmente renderizado.

Como mostrar o visualizador ao carregar

  google.books.setOnLoadCallback(initialize);

Enquanto uma página HTML é renderizada, o modelo de objeto de documento (DOM) é criado e todas as imagens e scripts externos são recebidos e incorporados ao objeto document. Para garantir que nosso visualizador seja colocado na página somente após a página ser totalmente carregada, a função google.books.setOnLoadCallback é usada para adiar a execução da função que constrói o objeto DefaultViewer. Como setOnLoadCallback só chamará initialize quando a API Embed Viewer estiver carregada e pronta para ser usada, isso evita um comportamento imprevisível e garante o controle de como e quando o visualizador será desenhado.

Observação:para maximizar a compatibilidade entre navegadores, é altamente recomendável programar o carregamento do visualizador usando a função google.books.setOnLoadCallback em vez de usar um evento onLoad na tag <body>.

Interações com espectadores

Agora que você tem um objeto DefaultViewer, é possível interagir com ele. O objeto de visualização básico se parece e se comporta de maneira muito parecida com a dos leitores do site do Google Livros e tem muitos comportamentos integrados.

No entanto, também é possível interagir com o espectador de maneira programática. O objeto DefaultViewer é compatível com vários métodos que alteram o estado da visualização diretamente. Por exemplo, os métodos zoomIn(), nextPage() e highlight() operam no visualizador de forma programática, e não pela interação do usuário.

O exemplo a seguir exibe uma visualização de livro que "volta" automaticamente para a próxima página a cada três segundos. Se a próxima página estiver na parte visível do visualizador, ela será deslocada de forma suave até a página. Caso contrário, vai diretamente à parte superior da próxima página.

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

Ver exemplo (book-animate.html)

As chamadas programáticas para o leitor falham ou não têm efeito até que ele seja totalmente inicializado com um livro específico. Para garantir que você chame essas funções somente quando o visualizador estiver pronto, use o parâmetro successCallback para viewer.load, conforme descrito acima.

Para informações sobre todas as funções compatíveis com o objeto DefaultViewer, consulte o Guia de referência.

Observações de programação

Antes de começar a mergulhar na API Embedded Viewer, você precisa observar as seguintes preocupações para garantir que seu aplicativo funcione bem nas plataformas pretendidas.

Compatibilidade do navegador

A API Embedded Viewer oferece suporte a versões recentes do Internet Explorer, Firefox e Safari. Geralmente, outros navegadores com base em Gecko e WebKit, como Camino e Google Chrome, também são compatíveis.

Às vezes, aplicativos diferentes exigem comportamentos distintos de usuários com navegadores incompatíveis. A API Embed Viewer não tem nenhum comportamento automático quando detecta um navegador incompatível. A maioria dos exemplos neste documento não verifica a compatibilidade do navegador nem exibe uma mensagem de erro para navegadores mais antigos. Aplicativos reais podem fazer algo mais amigável com navegadores antigos ou incompatíveis, mas essas verificações são omitidas para tornar os exemplos mais legíveis.

Aplicativos não triviais encontrarão inconsistência entre navegadores e plataformas. Sites como quirksmode.org também são bons recursos para encontrar soluções alternativas.

Modo XHTML e quirks

Recomendamos que você use XHTML compatível com padrões nas páginas que contenham o visualizador. Quando os navegadores veem o DOCTYPE do XHTML no topo da página, eles renderizam a página no "modo de conformidade com padrões", o que torna o layout e os comportamentos muito mais previsíveis em todos os navegadores. Páginas sem essa definição podem ser renderizadas no modo quirks, o que pode levar a um layout inconsistente.

<!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">

Uma observação sobre os exemplos da API Embedded Viewer

A maioria dos exemplos nesta documentação mostra apenas o código JavaScript relevante, e não o arquivo HTML completo. É possível conectar o código JavaScript ao seu próprio arquivo HTML básico ou fazer o download do arquivo HTML completo para cada exemplo clicando no link após o exemplo.

Solução de problemas

Se o código parece não estar funcionando, veja algumas abordagens que podem ajudar a resolver os problemas: