O recurso Dynamic Links do Google Livros permite criar links confiáveis e personalizáveis para o Google Livros a partir do seu site. Por exemplo, essa ferramenta permite gerar links "inteligentes" que aparecem somente quando um livro está em nosso índice, ou exibir links que indiquem a seus usuários se um livro pode ser visualizado no Google Livros. O recurso Dynamic Links também permite incluir uma imagem em miniatura no seu link para o Google Livros. Esse documento permite adicionar rapidamente essa funcionalidade ao seu site.
Observação: esse recurso era conhecido como a API Book Visibility.
O Assistente de visualização é uma ferramenta criada em Dynamic Links que facilita ainda mais a criação de links para a visualização de livros do site, basta copiar algumas linhas de código. Este documento é destinado a desenvolvedores mais avançados que querem personalizar a forma como eles vinculam à Pesquisa de livros.
Índice
- Público
- Terminologia da Pesquisa de livros
- Introdução
- Diretrizes da promoção de marca
- API do lado do cliente
- Modos síncronos e assíncronos
- Perguntas frequentes
- Exemplos de código
Público
A documentação de links dinâmicos é destinada a programadores que querem criar aplicativos da Web que tenham links para livros no Google Livros. Nesta documentação, presumimos que você esteja familiarizado com o protocolo HTTP e o JavaScript básico.
Terminologia da Pesquisa de livros
O Google Livros respeita as restrições locais de direitos autorais do usuário e, como resultado, as visualizações ou as visualizações completas de alguns livros não estão disponíveis em todos os locais. A visibilidade é agrupada nas seguintes classes:
- Visualização completa
- O livro inteiro pode ser visualizado. Esses livros podem ser de domínio público.
- Visualização limitada
- Uma parte do livro está visível. Este livro está sob direitos autorais, e o Google Livros recebeu permissão para tornar essas páginas acessíveis aos usuários. Esses livros são diferentes dos livros da visualização de snippets, porque os usuários podem ver páginas inteiras.
- Visualização de trechos e sem visualização
- Os usuários veem apenas uma página "Sobre o livro". Só é possível usar trechos curtos do livro. Este livro não foi digitalizado ou está sob direitos autorais. O Google Livros não recebeu permissão para expor mais do que alguns "snippets" relacionados a um termo de pesquisa do usuário.
Introdução
A documentação de Links estáticos descreve uma maneira muito simples de gerar URLs para a página de um livro específico no Google Livros. Às vezes, um determinado livro não está no índice do Google Livros ou uma visualização não está disponível para um usuário em uma localização geográfica específica. Como os links estáticos são "cegos&&;t, às vezes eles não têm o efeito desejado.
O Dynamic Links oferece um método alternativo e programático do lado do cliente para consultar a visibilidade de um livro usando JavaScript. Isso permite que você inclua links mais confiáveis e previsíveis na Pesquisa de livros, levando a uma experiência mais consistente para os usuários. Como a visibilidade varia de acordo com a localização do usuário final, a interface do link dinâmico não foi projetada para consultas do lado do servidor ou off-line.
Para saber o que os Dynamic Links podem fazer, pule para as amostras de código no final deste documento.
Diretrizes da promoção de marca
Ao renderizar links dinâmicos, é preciso obedecer às diretrizes da promoção de marca que regem a família de APIs do Google Livros. Especificamente,
- Você precisa manter a atribuição e os links para o Google Livros.
- Ao vincular a visualizações no Google Livros, é necessário usar somente o botão aprovado do Google Preview.
- Links de texto, botões, documentação ou texto descritivo precisam obedecer às convenções de nomenclatura aprovadas. Por exemplo, não use os verbos "quot;download" nem "read" ao vincular as visualizações do Google Livros, já que somente obras de domínio público podem ser transferidas por download na íntegra.
Exemplo de branding
A seção de amostras no final deste documento fornece mais exemplos de conformidade com as diretrizes de marca atuais.
API do cliente
A base do link dinâmico do lado do cliente é um formato de URL que permite aos desenvolvedores criar URLs que solicitem informações sobre um ou mais livros e enviem as solicitações ao Google Livros usando a tag <script>.
- Exemplo de sintaxe:
<script src="https://books.google.com/books?bibkeys=ISBN:0451526538&jscmd=viewapi&callback=mycallback"></script>
Formato da solicitação
O formato do URL é semelhante à sintaxe de URL usada para vincular a livros, mas o campo de código do livro pode conter vários IDs de livros separados por vírgula, e há parâmetros adicionais 'jscmd' e 'callback' Também é possível incluir argumentos adicionais para controlar os filtros de visibilidade.
O Dynamic Links é compatível com vários métodos diferentes de identificação de livros: ISBNs, números OCLC e chaves LCCN. A API permite consultas em lote de até o tamanho máximo de uma solicitação GET.
- ISBN
&bibkeys=ISBN:0451526538A API é compatível com ISBN 10 e 13.- OCLC
&bibkeys=OCLC:36792831- LCCN
&bibkeys=LCCN:96072233
Formato de resultados JSON
A resposta desta chamada será de informações sobre os livros solicitados retornados como um ou mais objetos JSON. Os objetos JSON usam a seguinte estrutura:
JsonSearchResult {
string bib_key;
string info_url;
string preview_url;
string thumbnail_url;
string preview;
};
Esses campos exibem as seguintes informações:
- bib_key
- O identificador usado para consultar este livro.
- URL de informações
- Um URL para uma página no Google Livros com informações sobre o livro (a página "Sobre este livro").
- visualizar_URL
- É um URL para a visualização do livro, que leva o usuário diretamente para a capa do livro. Se somente a visualização do snippet ou a ausência de livros de visualização estiverem disponíveis para uma solicitação, nenhum URL de visualização será retornado.
- miniatura do URL
- Um URL para uma miniatura da capa do livro.
- visualização
- Um valor que indica o estado de visualização do livro:
full(para livros com visualização completa),partial(para livros de visualização limitada) ounoview(para livros com snippet ou sem visualização). - incorporável
- Esse booleano será
truese o livro puder ser incorporado a páginas de terceiros usando o visualizador incorporado da Pesquisa de livros. - jscmd
- A solicitação para o Google Livros.
- callback
- Nome da função JavaScript para a qual transmitimos o retorno.
- P: Preciso de uma chave de API ou outra permissão para usar links dinâmicos?
- R: Nenhuma chave de API ou outra autorização é necessária para usar links dinâmicos. Para começar, copie e cole um dos nossos exemplos e comece a trabalhar.
- P: E quanto aos navegadores que não suportam JavaScript ou que os desativaram?
- R: Não há como testar se o Google Livros tem ou não um livro quando o navegador do usuário não tem JavaScript ativado. Recomendamos o uso da estrutura de link estático do Google Livros para navegadores sem JavaScript. No entanto, não é possível saber com antecedência se o Google Livros tem o livro com o qual você está vinculando.
- P: Quantos livros posso pesquisar ao mesmo tempo?
- R: O número de livros que você pode pesquisar é limitado pela duração das solicitações GET. No Microsoft Internet Explorer, o tamanho máximo do URL (2.083 caracteres) limita o comprimento das solicitações GET.
- P: O Google Livros retornava os resultados de um livro há pouco tempo. Por que ela não retorna os resultados agora?
- R: Como os desenvolvedores geralmente emitem uma quantidade atípica de solicitações, pode acidentalmente, por acidente, dar uma olhada nas precauções de segurança encontradas no Google Livros. Para verificar se isso está acontecendo, veja o que está sendo retornado pela API. Se for uma solicitação para preencher um captcha, você emitiu muitas consultas. Recomendamos fazer login no Google Livros e tentar novamente.
- P: E quanto à privacidade?
- R: Em resposta às consultas de visibilidade de livros, o Google recebe os dados de registro do servidor que não são de identificação pessoal. Levamos a privacidade do usuário a sério e tratamos esses dados como descrito em nossa Política de Privacidade. Caso você ofereça aos usuários um serviço que inclua a visibilidade de livros, informe a eles que seu serviço também envia consultas ao Google por meio de links dinâmicos.
- Botão de visualização para uma página de livro
Se você pretende usar links dinâmicos para adicionar botões "preview" a páginas de livros individuais no seu site, veja este exemplo. Essa implementação usa uma chamada síncrona para o Google Livros. - Lista de leitura do curso
Este exemplo mostra uma lista típica de livros de um curso acadêmico. Usamos uma única chamada síncrona para vincular páginas de livros no Google Livros, adicionar imagens de capa e indicar a disponibilidade de visualização. - Lista de livros alternativos
Semelhante ao exemplo anterior, este exemplo adiciona links à Pesquisa de livros usando um callback de API assíncrono. - AJAX interativo
Talvez você se interesse por usar Dynamic Links em um aplicativo AJAX altamente interativo. Este exemplo mostra como emitir várias chamadas diferentes sem atualizar a página.
A resposta é um objeto JSON com dois campos, "books" que tem o valor de um mapa de objetos de livro e "options" que contém uma lista das opções ativadas para a solicitação em questão. Se nenhuma opção tiver sido especificada, o campo "options" poderá ser omitido na resposta. Exemplo:
Request:
https://books.google.com/books?jscmd=viewapi&bibkeys=0596000278,00-invalid-isbn,ISBN0765304368,0439554934&callback=ProcessGBSBookInfo
Response:
ProcessGBSBookInfo({
"0596000278":{
"bib_key":"0596000278",
"info_url":"https://books.google.com/books?id=ezqe1hh91q4C&source=gbs_ViewAPI",
"preview_url":"https://books.google.com/books?id=ezqe1hh91q4C&printsec=frontcover&sig=zSQ5gwlX1NZl_24M86KS8Rbj33Q&source=gbs_ViewAPI",
"thumbnail_url":"https://books.google.com/books?id=ezqe1hh91q4C&pg=PR3&img=1&zoom=5&sig=bBmzIAIiCtMcM7Ii7TUHycqqEWg",
"preview":"partial"
},
"ISBN0765304368":{
"bib_key":"ISBN0765304368",
"info_url":"https://books.google.com/books?id=gfg13CM_kU8C&source=gbs_ViewAPI",
"preview_url":"https://books.google.com/books?id=gfg13CM_kU8C&printsec=frontcover&sig=jIrSb_SkcQRhy_VvtnKbTXjmvos&source=gbs_ViewAPI",
"thumbnail_url":"https://books.google.com/books?id=gfg13CM_kU8C&pg=PP1&img=1&zoom=5&sig=LsTwGVAsy_qWYMPM6HVDTPAMokg",
"preview":"full"
},
"0439554934":{
"bib_key":"0439554934",
"info_url":"https://books.google.com/books?id=iwiYGwAACAAJ&source=gbs_ViewAPI",
"preview_url":"https://books.google.com/books?id=iwiYGwAACAAJ&source=gbs_ViewAPI",
"thumbnail_url":"https://books.google.com/books?id=iwiYGwAACAAJ&printsec=frontcover&img=1&zoom=5&sig=_L6ySKDAs-8gNK28c3NyFdO22ZM",
"preview":"noview"}
});
Os desenvolvedores podem mudar o conteúdo e a aparência das páginas da Web com base nos resultados JSON recuperados do servidor de GBS. No momento, o GBS não fornece bibliotecas para a modificação do DOM.
Parâmetros e campos adicionais
Modo síncrono x assíncrono
Modo assíncrono
No modo assíncrono, o desenvolvedor coloca a tag <script> no <head> do documento e constrói o URL com todos os identificadores necessários para renderizar a página. Os dados são recebidos da chamada em uma variável. Isso disponibiliza as informações do livro para o restante do documento e pode ser acessada imediatamente no HTML e JavaScript.
Modo síncrono
No modo síncrono, o desenvolvedor usa o URL no meio do <body> HTML. A resposta é processada usando um callback JavaScript.
Perguntas frequentes
Amostras de código
Nesta seção, apresentamos exemplos que ilustram diferentes maneiras de usar o Dynamic Links. Clique em qualquer exemplo para vê-lo em ação. Para ver o código em questão, "veja a fonte" no seu navegador.