O recurso Dynamic Links do Google Livros permite que você crie links mais personalizáveis e confiá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á no nosso índice ou exibir links que indicam aos usuários se um livro pode ser visualizado no Google Livros. O recurso Dynamic Links também permite incluir uma imagem de miniatura no seu link para o Google Livros. Este documento foi criado para permitir que você adicione rapidamente essa funcionalidade ao seu site.
Observação: esse recurso era conhecido como API Book Visibilidade.
O assistente de visualização é uma ferramenta criada com base em Dynamic Links que facilita ainda mais a vinculação de visualizações de livros no site copiando algumas linhas de código. Este documento é destinado a desenvolvedores mais avançados que procuram personalizar a forma como criam links para a Pesquisa de Livros do Google.
Conteúdo
- Público
- Terminologia da Pesquisa de Livros do Google
- 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 desejam criar aplicativos da web que vinculam a livros no Google Livros. Esta documentação pressupõe que você esteja familiarizado com o protocolo HTTP e JavaScript básico.
Terminologia da Pesquisa de Livros
O Google Livros respeita as restrições de direitos autorais locais do usuário e, como resultado, as visualizações ou 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 está visível. Esses livros podem estar em domínio público.
- Visualização limitada
- Uma parte do livro está visível. Este livro está protegido por 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 da Visualização de trechos, já que os usuários podem visualizar páginas inteiras.
- Visualização de trechos e sem visualização
- Os usuários veem apenas uma página "Sobre o livro". No máximo, apenas pequenos trechos do livro estão disponíveis. Este livro não foi digitalizado ou está protegido por direitos autorais, e o Google Livros não recebeu permissão para expor mais do que alguns "snippets" relacionados ao termo de pesquisa de um 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. Infelizmente, às vezes, um determinado livro não está no índice do Google Livros ou a visualização não está disponível para um usuário em uma determinada localização geográfica. Como os links estáticos são "cegos", às vezes eles não conseguem ter o efeito pretendido.
O Dynamic Links oferece um método alternativo e programático no lado do cliente para consultar a visibilidade de um livro usando JavaScript. Isso permite que você inclua links mais confiáveis e previsíveis para a Pesquisa de Livros do Google, levando a uma experiência mais consistente para seus usuários. Como a visibilidade varia de acordo com a localização do usuário final, a interface de link dinâmico não foi projetada para consultas off-line ou do lado do servidor.
Para ter uma ideia do que o Dynamic Links pode fazer, pule para os exemplos de código no final deste documento.
Diretrizes da promoção de marca
Ao renderizar Dynamic Links, você precisa seguir as diretrizes de branding que regem a família da API Google Books. Especificamente, vamos programar
- Você precisa manter a atribuição e os links para o Google Livros.
- Use somente o botão aprovado da Visualização do Google ao criar links para visualizações no Google Livros.
- Todos os links de texto, botões, documentação ou texto descritivo devem obedecer às convenções de nomenclatura aprovadas. Por exemplo, você não deve usar os verbos "download" ou "ler" ao criar links para visualizações do Google Livros, já que somente é possível fazer o download de obras de domínio público na íntegra.
Exemplo de branding
A seção "Amostras" no final deste documento apresenta mais exemplos em conformidade com as diretrizes de branding atuais.
API do lado do cliente
No centro do link dinâmico do lado do cliente está um formato de URL que permite que os desenvolvedores criem URLs solicitando 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 do URL usada para vincular a livros. No entanto, o campo de código do livro pode conter vários códigos de livros separados por vírgula, e há outros parâmetros "jscmd" e "callback". Opcionalmente, argumentos adicionais podem estar presentes 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 com até o tamanho máximo de uma solicitação GET.
- ISBN
&bibkeys=ISBN:0451526538(A API aceita os ISBNs 10 e 13).- OCLC
&bibkeys=OCLC:36792831- LCCN
&bibkeys=LCCN:96072233
Formato de resultados JSON
A resposta dessa chamada será informações sobre os livros solicitados que foram 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 fornecem as seguintes informações:
- bib_key
- O identificador usado para consultar este livro.
- info_url
- Um URL para uma página no Google Livros com informações sobre o livro (a página "Sobre este livro").
- preview_url
- É um URL para a visualização do livro, que leva o usuário diretamente para a capa dele. Se apenas a Visualização de trechos ou a opção "Nenhuma visualização de livros" estiverem disponíveis para uma solicitação, nenhum URL de visualização será retornado.
- thumbnail_url
- É um URL para uma miniatura da capa do livro.
- visualização
- Um valor que indica o estado de visibilidade do livro:
full(para livros com visualização completa),partial(para livros com visualização limitada) ounoview(para livros com visualização completa ou com snippet). - incorporável
- Esse booleano será
truese o livro puder ser incorporado a páginas de terceiros usando o visualizador incorporado da Pesquisa de Livros do Google. - jscmd
- A solicitação ao 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 os links dinâmicos. Para começar, basta copiar e colar um dos nossos exemplos e começar a mexer.
- P: E os navegadores que não são compatíveis com JavaScript ou o estão desativados?
- R: Não será possível testar se o Google Livros tem ou não um livro se o navegador do usuário não tiver o JavaScript ativado. Recomendamos o uso da estrutura de links estáticos do Google Livros para navegadores sem JavaScript, mas não é possível saber com antecedência se o Google Livros tem o livro para o qual você está criando um link.
- P: Quantos livros posso pesquisar de uma vez?
- R: O número de livros que é possível pesquisar só é limitado pelo tamanho das solicitações GET. No Microsoft Internet Explorer, o tamanho máximo de um URL (2.083 caracteres) limita o tamanho das solicitações GET.
- P: O Google Livros estava retornando resultados para um livro há pouco tempo. Por que ele não está retornando resultados agora?
- R: Como os desenvolvedores costumam emitir uma quantidade atípica de solicitações, você pode acidentalmente dar dicas sobre as precauções de segurança encontradas no Google Livros. Para verificar se isso está acontecendo, confira o que está sendo retornado pela API. Se for uma solicitação para preencher um captcha, você fez muitas consultas. Recomendamos que você faça login no Google Livros e tente novamente.
- P: E quanto à privacidade?
- R: Ao responder a consultas sobre visibilidade do livro, o Google recebe dados de registro do servidor sem identificação pessoal. Levamos a privacidade do usuário a sério e tratamos esses dados conforme descrito na nossa Política de Privacidade. Se você estiver oferecendo aos usuários um serviço que inclui a visibilidade de livros, informe que seu serviço também envia consultas ao Google por meio de links dinâmicos.
- Botão "Visualizar" em uma página de livro
Se você pretende usar o Dynamic Links para adicionar botões "Visualizar" a páginas de livros individuais no seu site, este é o exemplo ideal. Esta 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 para um curso acadêmico. Usamos uma única chamada síncrona para criar links para páginas de livros no Google Livros, adicionar imagens de capa e indicar a disponibilidade da 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ê tenha interesse em usar o 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 um valor de um mapa de objetos de livro, e "options", que contém uma lista das opções ativadas para essa solicitação. Se nenhuma opção for 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 alterar o conteúdo e a aparência das páginas da Web com base nos resultados JSON recuperados do servidor GBS. No momento, o GBS não fornece bibliotecas para modificar o DOM para fazer isso.
Parâmetros e campos adicionais
Modo síncrono vs. 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 em 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
Exemplos de código
Esta seção fornece exemplos que ilustram diferentes maneiras de usar o Dynamic Links. É possível clicar em qualquer exemplo para vê-lo em ação. Para acessar o código subjacente, clique em "Exibir código-fonte" no navegador.