Dynamic Links

La función Dynamic Links de Google Libros te permite crear vínculos más personalizables y confiables a Google Libros desde tu sitio. Por ejemplo, esta herramienta te permite generar vínculos "inteligentes" que aparecen solo cuando un libro está en nuestro índice o mostrar vínculos que les indican a los usuarios si se puede obtener una vista previa de un libro en Google Libros. La función Dynamic Links también te permite incluir una imagen en miniatura en tu vínculo a Google Libros. El objetivo de este documento es que puedas agregar rápidamente esta función a tu sitio.

Nota: Esta función antes se conocía como la API de visibilidad de libros.

El asistente de vista previa es una herramienta compilada en Dynamic Links que facilita aún más la vinculación a vistas previas de libros desde el sitio con solo copiar algunas líneas de código. Este documento está dirigido a desarrolladores más avanzados que deseen personalizar la forma en que se vinculan a la Búsqueda de libros.

Contenido

  1. Público
  2. Terminología de la Búsqueda de libros
  3. Introducción
  4. Lineamientos sobre el desarrollo de la marca
  5. La API del cliente
    1. Cómo solicitar el formato de la URL
    2. Formato de resultados JSON
  7. Modos síncrono y asíncrono
  8. Preguntas frecuentes
  9. Muestras de código

Público

La documentación sobre vínculos dinámicos está dirigida a los programadores que desean crear aplicaciones web que se vinculen a libros dentro de Google Libros. Esta documentación supone que estás familiarizado con el protocolo HTTP y con JavaScript básico.

Terminología de la Búsqueda de libros

Google Libros respeta las restricciones locales de derechos de autor del usuario y, como resultado, las vistas previas o las vistas completas de algunos libros no están disponibles en todas las ubicaciones. La visibilidad se agrupa en clústeres en las siguientes clases:

Vista completa
Se puede ver todo el libro. Es posible que estos libros sean de dominio público.
Vista previa limitada
Una parte del libro es visible. Este libro está protegido por derechos de autor, y Google Libros recibió permiso para permitir que los usuarios accedan a estas páginas. Estos libros se diferencian de los libros con vista de fragmento en que los usuarios pueden ver páginas completas.
Vista de fragmentos y sin vista previa
Los usuarios solo ven una página "Acerca del libro". Como máximo, solo están disponibles extractos breves del libro. Este libro no se escaneó o está protegido por derechos de autor, y Google Libros no recibió permiso para exponer más de unos pocos "fragmentos" relacionados con el término de búsqueda del usuario.

Introducción

En la documentación sobre Vínculos estáticos, se describe una manera muy simple de generar URL que dirigen a la página de un libro específico en Google Libros. Lamentablemente, a veces se produce que un libro en particular no se encuentra en el índice de Google Libros o que una vista previa no está disponible para un usuario en una ubicación geográfica en particular. Debido a que los Static Links son "ciegos", a veces no tienen el efecto deseado.

Dynamic Links proporciona un método programático y alternativo del cliente para consultar la visibilidad de un libro con JavaScript. Esto te permite incluir vínculos más confiables y predecibles a la Búsqueda de libros, lo que genera una experiencia más coherente para tus usuarios. Debido a que la visibilidad varía según la ubicación del usuario final, la interfaz de vínculo dinámico no está diseñada para búsquedas sin conexión o del servidor.

Para tener una idea de lo que puede hacer Dynamic Links, ve a las muestras de código que se encuentran al final de este documento.

Lineamientos sobre el desarrollo de la marca

Para renderizar Dynamic Links, debes cumplir con los lineamientos de desarrollo de la marca que rigen la familia de API de Google Libros. En particular,

  • Debe mantener la atribución y los vínculos a Google Libros.
  • Cuando vincules a vistas previas en Google Libros, solo debes usar el botón Vista previa de Google aprobado.
  • Los vínculos de texto, los botones, la documentación o el texto descriptivo deben cumplir con las convenciones de nomenclatura aprobadas. Por ejemplo, no debes usar los verbos "descargar" o "leer" cuando vinculas las vistas previas de Google Libros, ya que solo las obras de dominio público se pueden descargar por completo.

Ejemplo de desarrollo de la marca

Freakonomics: An Rogue Economist Explora el lado oculto de todo
Por Steven Levitt y Stephen Dubner

En la sección de muestras al final de este documento, se proporcionan ejemplos adicionales que cumplen con los lineamientos actuales de desarrollo de la marca.

API del cliente

En el centro del vínculo dinámico del cliente, se encuentra un formato de URL que permite a los desarrolladores crear URLs que soliciten información sobre uno o más libros y enviar las solicitudes a Google Libros con la etiqueta <script>.

Ejemplo de sintaxis:
<script src="https://books.google.com/books?bibkeys=ISBN:0451526538&jscmd=viewapi&callback=mycallback"></script>

Formato de la solicitud

El formato de la URL es similar al de la sintaxis de la URL que se utiliza para vincular a libros, pero el campo ID del libro puede contener varios IDs de libros separados por comas y hay parámetros "jscmd" y "callback" adicionales. De manera opcional, se pueden incluir argumentos adicionales para controlar los filtros de visibilidad.

Dynamic Links admite varios métodos diferentes para identificar libros: ISBN, números OCLC y claves LCCN. La API permite consultas por lotes de hasta el tamaño máximo de una solicitud GET.

ISBN
&bibkeys=ISBN:0451526538 (La API admite los ISBN 10 y 13).
OCLC
&bibkeys=OCLC:36792831
LCCN
&bibkeys=LCCN:96072233

Formato de resultados de JSON

La respuesta de esta llamada será información sobre los libros solicitados que se muestran como uno o más objetos JSON. Los objetos JSON usan la siguiente estructura:

JsonSearchResult {
    string bib_key;
    string info_url;
    string preview_url;
    string thumbnail_url;
    string preview;
};

Estos campos proporcionan la siguiente información:

bib_key
Es el identificador que se usa para consultar este libro.
info_url
Una URL a una página de Google Libros con información del libro (la página Acerca de este libro).
preview_url
Es una URL a la vista previa del libro, que lleva al usuario directamente a la portada del libro. Si solo hay vistas de fragmentos o no hay libros de vista previa disponibles para una solicitud, no se mostrará ninguna URL de vista previa.
thumbnail_url
Es una URL a una miniatura de la portada del libro.
versión preliminar
Un valor que indica el estado de visibilidad del libro: full (para libros de vista completa), partial (para libros con vista previa limitada) o noview (para libros con fragmentos o sin vista previa).
incorporables
Este valor booleano es true si el libro se puede incorporar en páginas de terceros a través del visualizador incorporado de Búsqueda de libros.

La respuesta es un objeto JSON con dos campos, "books", que tiene el valor de un mapa de objetos de libros, y "options", que contiene una lista de las opciones habilitadas para esa solicitud. Si no se especificaron opciones, el campo "options" se puede omitir en la respuesta. Por ejemplo:

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

Luego, los desarrolladores pueden cambiar el contenido y el aspecto de sus páginas web en función de los resultados JSON recuperados del servidor de GBS. En este momento, GBS no proporciona bibliotecas para modificar el DOM con el objetivo de hacerlo.

Parámetros y campos adicionales

jscmd
La solicitud a Google Libros.
callback
Nombre de la función de JavaScript a la que pasamos el resultado.

Modo síncrono frente a modo asíncrono

Modo asíncrono

En el modo asíncrono, el desarrollador coloca la etiqueta <script> en el elemento <head> del documento y construye la URL con todos los identificadores necesarios para renderizar la página. Los datos se reciben de la llamada en una variable. De esta manera, la información del libro estará disponible para el resto del documento y se podrá acceder a ella de inmediato en HTML y JavaScript.

Modo síncrono

En el modo síncrono, el desarrollador usa la URL en medio del elemento <body> de HTML; la respuesta se controla con una devolución de llamada de JavaScript.

Preguntas frecuentes

P.: ¿Necesito una clave de API o algún otro permiso para usar vínculos dinámicos?
R.: No se necesita una clave de API ni otra autorización para usar vínculos dinámicos. Para comenzar, copia y pega uno de nuestros ejemplos y empieza a juguetear.
P.: ¿Qué sucede con los navegadores que no admiten JavaScript o que lo tienen inhabilitado?
R: No se puede probar si Google Libros tiene un libro cuando el navegador de un usuario no tiene habilitado JavaScript. Te recomendamos que uses la estructura de vínculos estáticos de Google Libros para navegadores sin JavaScript, pero recuerda que no puedes saber con anticipación si Google Libros tiene el libro que quieres vincular.
P.: ¿Cuántos libros puedo buscar a la vez?
R.: La cantidad de libros que puedes buscar está limitada por la longitud de las solicitudes GET. En Microsoft Internet Explorer, la longitud máxima de la URL (2,083 caracteres) limita la longitud de las solicitudes GET.
P: Hace un momento, Google Libros devolvió resultados para un libro. ¿Por qué no devuelve resultados ahora?
R.: Debido a que los desarrolladores suelen emitir una cantidad atípica de solicitudes, podrías inclinar accidentalmente las precauciones de seguridad que se incluyen en Google Libros. Para verificar si esto sucede, consulta lo que muestra la API. Si se trata de una solicitud para completar un captcha, significa que emitió demasiadas consultas. Te recomendamos que accedas a Google Libros y vuelvas a intentarlo.
P.: ¿Qué sucede con la privacidad?
A: Cuando responde consultas sobre la visibilidad de los libros, Google recibe datos de registro del servidor que no son de identificación personal. Nos tomamos muy en serio la privacidad del usuario y tratamos esos datos como se describe en nuestra Política de Privacidad. Si les brindas a los usuarios un servicio que incluye la visibilidad de los libros, te recomendamos que les avises que tu servicio también envía consultas a Google a través de vínculos dinámicos.

Muestras de código

En esta sección, se proporcionan ejemplos que ilustran las diferentes maneras de usar Dynamic Links. Puedes hacer clic en cualquier ejemplo para verlo en acción. Para ver el código subyacente, "vea el código fuente" en tu navegador.

  • Botón de vista previa de la página de un libro
    Si quieres usar Dynamic Links para agregar botones de “vista previa” a páginas individuales de libros en tu sitio, este es el ejemplo para ti. Esta implementación utiliza una llamada síncrona a Google Libros.
  • Lista de lectura del curso
    En este ejemplo, se muestra una lista de libros típica de un curso académico. Usamos una única llamada síncrona para vincular las páginas de los libros en Google Libros, agregar imágenes de portada y, además, indicar la disponibilidad de la vista previa.
  • Lista de libros alternativos
    Al igual que en el ejemplo anterior, esta muestra agrega vínculos a la Búsqueda de libros mediante una devolución de llamada asíncrona a la API.
  • AJAX interactivo
    Es posible que te interese usar Dynamic Links en una aplicación AJAX altamente interactiva. En este ejemplo, se muestra cómo emitir una cantidad de llamadas diferentes sin actualizar la página.