Objetivo
En este documento, se describen los pasos clave para desarrollar una aplicación interactiva de buscador de tiendas con Google Maps Platform, específicamente la API de Maps JavaScript y el kit de IU de Places: Elemento Place Details. Aprenderás a crear un mapa que muestre las ubicaciones de las tiendas, actualizar de forma dinámica una lista de tiendas visibles y mostrar información enriquecida de cada tienda.
Requisitos previos
Se recomienda tener conocimientos sobre lo siguiente:
- API de Maps JavaScript: Se usa para mostrar un mapa en tu página y para importar el kit de IU de Places.
- Marcadores avanzados: Se usan para mostrar marcadores en el mapa.
- Kit de IU de Places: Se usa para mostrar información sobre tus tiendas en la IU.
Habilita la API de Maps JavaScript y el kit de IU de Places en tu proyecto.
Antes de comenzar, verifica que hayas cargado la API de Maps JavaScript y que hayas importado las bibliotecas necesarias para los marcadores avanzados y el kit de IU de Places. En este documento, también se supone que tienes conocimientos prácticos de desarrollo web, incluidos HTML, CSS y JavaScript.
Configuración inicial
El primer paso es agregar un mapa a la página. Este mapa se usará para mostrar pines relacionados con las ubicaciones de tus tiendas.
Existen dos maneras de agregar un mapa a una página:
- Usa un componente web HTML gmp-map
- Usa JavaScript
Elige el método que mejor se adapte a tu caso de uso. Ambas formas de implementar el mapa funcionarán con esta guía.
Carga y muestra ubicaciones de tiendas
En esta sección, cargaremos y mostraremos los datos de tu tienda en el mapa. En esta guía,
se supone que tienes un repositorio de información sobre tus tiendas existentes del que
puedes extraer datos. Los datos de tu tienda pueden provenir de varias fuentes, como tu base de datos.
Para este ejemplo, supondremos que hay un archivo JSON local (stores.json) con un array de objetos de tienda, cada uno de los cuales representa una ubicación de tienda. Cada objeto debe contener,
como mínimo, un name, un location (con lat y lng) y un place_id.
Existen varias formas de recuperar los IDs de lugar de las ubicaciones de tus tiendas si aún no los tienes. Consulta la documentación sobre los IDs de lugar para obtener más información.
Un ejemplo de entrada de detalles de la tienda en tu archivo stores.json podría verse de la siguiente manera.
Hay campos para el nombre, la ubicación (latitud y longitud) y el ID de lugar. Hay un objeto
para contener el horario de atención de la tienda (truncado). También hay dos valores booleanos para
ayudar a describir las características personalizadas de la ubicación de la tienda.
{
"name": "Example Store Alpha",
"location": { "lat": 51.51, "lng": -0.12 },
"place_id": "YOUR_STORE_PLACE_ID",
"opening_hours": { "Monday": "09:00 - 17:00", "...": "..." },
"new_store_design": true,
"indoor_seating": false
}
En tu código de JavaScript, recupera los datos de las ubicaciones de tus tiendas y muestra un pin en el mapa para cada una.
A continuación, se muestra un ejemplo de cómo hacerlo. Esta función toma un objeto que contiene los detalles de las tiendas y crea un marcador según la ubicación de cada una.
function displayInitialMarkers(storeLocations) {
if (!AdvancedMarkerElement || !LatLng || !mapElement) return;
storeLocations.forEach(store => {
if (store.location) {
const marker = new AdvancedMarkerElement({
position: new LatLng(store.location.lat, store.location.lng),
title: store.name
});
mapElement.appendChild(marker);
}
});
}
Una vez que hayas cargado tus tiendas y tengas marcadores que representen sus ubicaciones en el mapa, crea una barra lateral con HTML y CSS para mostrar detalles sobre cada una de ellas.
A continuación, se muestra un ejemplo de cómo podría verse tu localizador de tiendas en esta etapa:
Detecta cambios en el viewport del mapa
Para optimizar el rendimiento y la experiencia del usuario, actualiza tu aplicación para que muestre marcadores y detalles en la barra lateral solo cuando las ubicaciones correspondientes estén dentro del área visible del mapa (viewport). Esto implica escuchar los cambios en el viewport del mapa, eliminar los eventos duplicados y, luego, volver a dibujar solo los marcadores necesarios.
Adjunta un objeto de escucha de eventos al evento de inactividad del mapa. Este evento se activa después de que se completan las operaciones de desplazamiento lateral o zoom, lo que proporciona un viewport estable para tus cálculos.
map.addListener('idle', debounce(updateMarkersInView, 300));
En el fragmento de código anterior, se escucha el evento idle y se llama a una función debounce. El uso de una función de eliminación de rebotes garantiza que la lógica de actualización de los marcadores solo se ejecute después de que el usuario deje de interactuar con el mapa durante un período breve, lo que mejora el rendimiento.
function debounce(func, delay) {
let timeoutId;
return function(...args) {
const context = this;
clearTimeout(timeoutId);
timeoutId = setTimeout(() => {
func.apply(context, args);
}, delay);
};
}
El código anterior es un ejemplo de función de eliminación de rebotes. Toma una función y un argumento de retraso, que se pueden ver pasados en el objeto de escucha inactivo. Un retraso de 300 ms es suficiente para esperar a que el mapa deje de moverse, sin agregar un retraso notable a la IU.
Una vez que vence este tiempo de espera, se llama a la función pasada, en este caso,
updateMarkersInView.
La función updateMarkersInView debe realizar las siguientes acciones:
Borra todos los marcadores existentes del mapa.
Verifica si la ubicación de la tienda se encuentra dentro de los límites actuales del mapa, por ejemplo:
if (map.getBounds().contains(storeLatLng)) {
// logic
}
Dentro de la sentencia if anterior, escribe código para mostrar los marcadores y los detalles de la tienda en la barra lateral, si la ubicación de la tienda se encuentra dentro del viewport del mapa.
Muestra detalles enriquecidos de un lugar con el elemento Place Details
En esta etapa, la aplicación muestra todas las ubicaciones de las tiendas, y los usuarios pueden filtrarlas según el viewport del mapa. Para mejorar esto, se agregan detalles enriquecidos sobre cada tienda, como fotos, opiniones y datos de accesibilidad, con el elemento Place Details. En este ejemplo, se usa específicamente el elemento compacto de Place Details.
Cada ubicación de tienda en tu fuente de datos debe tener un ID de lugar correspondiente. Este ID identifica de forma exclusiva la ubicación en Google Maps y es esencial para recuperar sus detalles. Por lo general, debes adquirir estos IDs de lugar con anticipación y almacenarlos en cada uno de los registros de tus tiendas.
Integra el elemento Place Details Compact en la aplicación
Cuando se determina que una tienda se encuentra dentro del viewport actual del mapa y se renderiza en la barra lateral, puedes crear e insertar de forma dinámica un elemento compacto de Place Details para ella.
Para la tienda que se está procesando, recupera el ID de lugar de tus datos. El ID de lugar se usa para controlar qué lugar mostrará el elemento.
En JavaScript, crea de forma dinámica una instancia de PlaceDetailsCompactElement. También se crea un nuevo PlaceDetailsPlaceRequestElement, se le pasa el ID de lugar y se agrega al PlaceDetailsCompactElement. Por último, usa PlaceContentConfigElement para configurar el contenido que mostrará el elemento.
En la siguiente función, se supone que las bibliotecas necesarias del kit de IU de Places se importaron y están disponibles en el alcance en el que se llama a esta función, y que el objeto storeData que se pasa a la función contiene place_id.
Esta función devolverá el elemento, y el código de llamada será responsable de agregarlo al DOM.
function createPlaceDetailsCompactElement(storeData) {
// Create the main details component
const detailsCompact = new PlaceDetailsCompactElement();
detailsCompact.setAttribute('orientation', 'vertical'); // Or 'horizontal'
// Specify the Place ID
const placeRequest = new PlaceDetailsPlaceRequestElement();
placeRequest.place = storeData.place_id;
detailsCompact.appendChild(placeRequest);
// Configure which content elements to display
const contentConfig = new PlaceContentConfigElement();
// For this example, we'll render media, rating, accessibility, and attribution:
contentConfig.appendChild(new PlaceMediaElement({ lightboxPreferred: true }));
contentConfig.appendChild(new PlaceRatingElement());
contentConfig.appendChild(new PlaceAccessibleEntranceIconElement());
// Configure attribution
const placeAttribution = new PlaceAttributionElement();
placeAttribution.setAttribute('light-scheme-color', 'gray');
placeAttribution.setAttribute('dark-scheme-color', 'gray');
contentConfig.appendChild(placeAttribution);
detailsCompact.appendChild(contentConfig);
// Return the element
return detailsCompact;
}
En el código de ejemplo anterior, el elemento está configurado para mostrar las fotos del lugar, la calificación de las opiniones y la información de accesibilidad. Esto se puede personalizar agregando o quitando otros elementos de contenido disponibles. Consulta la documentación de PlaceContentConfigElement para conocer todas las opciones disponibles.
El elemento Place Details Compact admite el diseño con propiedades personalizadas de CSS. Esto te permite adaptar su apariencia (colores, fuentes, etc.) para que coincida con el diseño de tu aplicación. Aplica estas propiedades personalizadas en tu archivo CSS. Consulta
la documentación de referencia de
PlaceDetailsCompactElement
para conocer las propiedades de CSS compatibles.
A continuación, se muestra un ejemplo de cómo podría verse tu aplicación en esta etapa:
Mejora el buscador de tiendas
Creaste una base sólida para tu aplicación de localizador de tiendas. Ahora, considera varias formas de extender su funcionalidad y crear una experiencia aún más enriquecedora y centrada en el usuario.
Agrega autocompletar
Mejora la forma en que los usuarios encuentran áreas para buscar tiendas integrando una entrada de búsqueda con Place Autocomplete. Cuando los usuarios escriban una dirección, un vecindario o un lugar de interés y seleccionen una sugerencia, programa el mapa para que se centre automáticamente en esa ubicación, lo que activará una actualización de las tiendas cercanas. Para ello, agrega un campo de entrada y asóciale la funcionalidad de Place Autocomplete. Cuando se selecciona una sugerencia, el mapa se puede centrar en ese punto. Recuerda configurarlo para que sesgue o restrinja los resultados a tu área de operaciones.
Cómo detectar la ubicación
Ofrece relevancia inmediata, en especial para los usuarios de dispositivos móviles, implementando una funcionalidad que detecte su ubicación geográfica actual. Después de obtener el permiso del navegador para detectar su ubicación, centra automáticamente el mapa en su posición y muestra las tiendas más cercanas. Los usuarios valoran mucho esta función de Cerca de mí cuando buscan opciones inmediatas. Agrega un botón o un mensaje inicial para solicitar acceso a la ubicación.
Mostrar distancia e instrucciones sobre cómo llegar
Una vez que un usuario identifica una tienda de interés, mejora significativamente su recorrido integrando la API de Routes. Para cada tienda que incluyas, calcula y muestra la distancia desde la ubicación actual del usuario o desde la ubicación buscada. Además, proporciona un botón o vínculo que use la API de Routes para generar una ruta desde la ubicación del usuario hasta la tienda seleccionada. Luego, puedes mostrar esta ruta en tu mapa o vincularla a Google Maps para la navegación, lo que crea una transición fluida desde la búsqueda de una tienda hasta la llegada a ella.
Si implementas estas extensiones, puedes usar más funciones de Google Maps Platform para crear un localizador de tiendas más completo y conveniente que aborde directamente las necesidades comunes de los usuarios.
Conclusión
En esta guía, se mostraron los pasos principales para crear un localizador de tiendas interactivo. Aprendiste a mostrar las ubicaciones de tus tiendas en un mapa con la API de Maps JavaScript, a actualizar de forma dinámica las tiendas visibles según los cambios en el viewport y, lo que es más importante, a mostrar los datos de tus tiendas de acuerdo con el kit de IU de Places. Si usas la información existente de tus tiendas, incluidos los IDs de lugar, con el elemento Place Details, puedes presentar detalles enriquecidos y estandarizados para cada una de tus ubicaciones, lo que crea una base sólida para un localizador de tiendas fácil de usar.
Prueba la API de Maps JavaScript y el kit de IU de Places para ofrecer herramientas potentes basadas en componentes que permitan desarrollar rápidamente aplicaciones sofisticadas basadas en la ubicación. Si combinas estas funciones, puedes crear experiencias atractivas e informativas para tus usuarios.
Colaboradores
Henrik Valve | Ingeniero de DevX