Enriched Transactions

Descripción general

Usa esta guía para aprender a vincular una ubicación con un comercio específico y mostrar información detallada sobre él.

Cuando emites resúmenes de transacciones abreviados, como "ACMEHCORP", es posible que a tus clientes les resulte difícil entenderlos. Esto puede generar cargos disputados y costos de asistencia adicionales para ti. En su lugar, es mejor proporcionar el nombre completo del comercio, como Acme Housewares.

Enriched Transactions te facilita proporcionar información intuitiva sobre las transacciones, incluidos el nombre completo del comercio, la categoría de la empresa, la imagen de la vidriera y los detalles de contacto y ubicación. Esto aumenta la transparencia, mejora el Net Promoter Score (NPS) y hace que los usuarios pasen más tiempo en tu app.

Habilita las APIs

Para implementar Enriched Transactions, debes habilitar las siguientes APIs en la consola de Google Cloud. Los siguientes vínculos abren la consola de Google Cloud para que puedas habilitar cada API en el proyecto que hayas seleccionado:

• API de Places (nueva)
• API de Geocoding
• API de Maps JavaScript, API de Maps Static, SDK de Maps para Android o SDK de Maps para iOS

Para obtener más información sobre la configuración, consulta Cómo comenzar a utilizar Google Maps Platform.

Secciones de la guía de implementación

En esta guía, se abordan las siguientes implementaciones y personalizaciones:

En el siguiente diagrama de flujo, se muestra cómo tu aplicación establece coincidencias con las transacciones de un comercio para mostrar un resultado utilizando Place Details de una base de datos existente de comercios o con una solicitud a Text Search:

Obtén los IDs de lugar de Google Maps Platform

Posiblemente tengas una base de datos de comercios con información básica, como el nombre de la empresa y su dirección. Para recuperar la información que Google Maps Platform tiene sobre ese lugar, incluidos los datos de contacto y las calificaciones aportadas por los clientes, debes encontrar el ID de lugar correspondiente a cada comercio en tu base de datos.

Para obtener el ID de lugar de una empresa, realiza una llamada al extremo de Text Search (nuevo) en la API de Places (nueva) y solicita solo el campo places.id en la máscara de campo, lo que activa el SKU de Text Search Essentials (solo IDs). Si el comercio tiene varias ubicaciones, incluye la ciudad o el nombre de la calle junto con el nombre del comercio en tu consulta. Valida los resultados que se devuelven para confirmar que coincidan con el comercio.

En el siguiente ejemplo, se solicita el ID de lugar de la oficina de Google en Taipéi con el nombre y la ciudad del comercio:

curl -X POST -d '{
  "textQuery" : "Google Taipei"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: places.id' \
'https://places.googleapis.com/v1/places:searchText'

Cómo almacenar IDs de lugar

Si deseas almacenar información de Google Maps Platform sobre el comercio para solicitudes futuras, puedes guardar el ID de lugar de forma indefinida en tu base de datos como un atributo del registro del comercio. Solo necesitas ejecutar la solicitud de Text Search (New) una vez para cada comercio, o bien puedes buscar el ID de lugar cada vez que un cliente solicite los detalles de la transacción.

Para mantener la precisión de los IDs de lugar almacenados, actualízalos cada 12 meses con una solicitud de Place Details (nuevo) que especifique solo el campo id en la máscara de campo.

Si los detalles del lugar que muestras no coinciden con el comercio en el que el cliente completó la transacción, Google recomienda permitir que los clientes envíen comentarios sobre la calidad de la coincidencia del comercio.

Puedes compartir los detalles del lugar que los clientes necesitan después de visitar la ubicación de un comercio. Después de llamar al extremo de Place Details (nuevo) en la API de Places (nueva), puedes filtrar y renderizar la respuesta en una ventana de información, una barra lateral web o una vista de detalles para dispositivos móviles dentro de los límites de las Condiciones del Servicio de Google Maps Platform.

Para emitir una solicitud al extremo de Place Details, necesitas el ID de lugar de cada ubicación. Consulta Obtén los IDs de lugar de Google Maps Platform para recuperar el ID de lugar de la ubicación de un comercio.

La siguiente solicitud a Place Details (nuevo) devuelve el nombre visible, la dirección con formato, las coordenadas, el sitio web, el número de teléfono, el ícono, el horario de atención y la calificación en formato JSON para el ID de lugar de Google Taipei 101:

curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: displayName,formattedAddress,location,websiteUri,nationalPhoneNumber,iconMaskBaseUri,regularOpeningHours,rating' \
'https://places.googleapis.com/v1/places/ChIJraeA2rarQjQRyAqIxkx2vN8'

Si estás creando una aplicación web con la API de Maps JavaScript, también puedes usar la clase Place para recuperar los mismos campos en el cliente:

const place = new google.maps.places.Place({
  id: "ChIJraeA2rarQjQRyAqIxkx2vN8",
});

await place.fetchFields({
  fields: [
    "displayName",
    "formattedAddress",
    "location",
    "websiteURI",
    "nationalPhoneNumber",
    "regularOpeningHours",
    "rating",
  ],
});

Determina la ubicación del comercio

Puedes colocar un marcador en un mapa con las coordenadas geográficas de los detalles del lugar. Si tu base de datos de comercios tiene direcciones, pero no coordenadas geográficas, y no solicitas detalles de lugares, puedes usar la API de Geocoding para convertir las direcciones en coordenadas de latitud y longitud en el servidor, almacenar esas coordenadas en tu base de datos y actualizarlas al menos una vez cada 30 días.

En el siguiente ejemplo, se usa la API de Geocoding para obtener la latitud y la longitud del ID de lugar de la oficina de Google Taipei:

```html
https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJraeA2rarQjQRyAqIxkx2vN8&key=YOUR_API_KEY
```

Cómo agregar un marcador avanzado en un mapa web

Dado que los clientes ven el mapa para confirmar las transacciones en lugar de explorar o navegar, configura tu mapa con interactividad limitada y coloca un marcador avanzado en la ubicación del comercio. Los marcadores avanzados requieren un ID de mapa y la biblioteca marker (libraries=marker).

Primero, carga la API de Maps JavaScript con libraries=marker y agrega un contenedor div para el mapa:

<script defer src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=marker&callback=initMap"></script>
<div id="map" style="height: 300px; width: 100%;"></div>

A continuación, inicializa el mapa con gestureHandling: "none" y zoomControl: false para limitar la interactividad, proporciona tu mapId y crea un google.maps.marker.AdvancedMarkerElement en las coordenadas del comercio:

function initMap() {
  const merchantLocation = { lat: 25.033976, lng: 121.5645389 };
  const map = new google.maps.Map(document.getElementById("map"), {
    center: merchantLocation,
    zoom: 16,
    mapId: "DEMO_MAP_ID",
    gestureHandling: "none",
    zoomControl: false,
  });

  new google.maps.marker.AdvancedMarkerElement({
    map,
    position: merchantLocation,
    title: "Google Taipei",
  });
}

También puedes personalizar tus marcadores avanzados cambiando el color del fondo, el borde o el glifo del pin, o bien proporcionando una imagen gráfica personalizada para la categoría del comercio.

Agrega una imagen de mapa estático

Si prefieres una imagen de mapa no interactiva para computadoras de escritorio o la Web móvil, crea una URL de la API de Maps Static con un solo marcador en la dirección o las coordenadas de latitud y longitud que coincidan con el comercio. La API de Maps Static devuelve una versión de imagen de un mapa con los parámetros que especifiques.

La siguiente solicitud devuelve un mapa de ruta de 640 × 480 píxeles, centrado en un marcador rojo en la oficina de Google Taipei con un diseño de mapa basado en Cloud:

```html
https://maps.googleapis.com/maps/api/staticmap?size=640x480&markers=color:red%7C25.033976%2C121.5645389&map_id=b224095f76859890&key=YOUR_API_KEY&signature=BASE64_SIGNATURE
```

En la siguiente tabla, se describe cada sección de la solicitud:

La solicitud produce la siguiente imagen de mapa estático:

También puedes pasar una dirección como ubicación del marcador:

```html
https://maps.googleapis.com/maps/api/staticmap?size=640x480&markers=color:green%7CTaipei%20101%20Tower%2CNo.%207信義路五段信義區台北市%20Taiwan%20110&map_id=b224095f76859890&key=YOUR_API_KEY&signature=BASE64_SIGNATURE
```

Para ver opciones de parámetros adicionales, consulta la documentación de la API de Maps Static.

Agrega un mapa en tu aplicación para dispositivos móviles

Si usas el SDK de Maps para Android o el SDK de Maps para iOS, puedes colocar un marcador avanzado con las coordenadas de Place Details.

Dado que los clientes ven el mapa para confirmar las transacciones en lugar de explorar o navegar, configura un mapa con interactividad limitada:

• En el caso de las aplicaciones para Android, consulta Marcadores avanzados para Android y Cómo agregar un mapa con un marcador, y habilita el modo lite para proporcionar interactividad limitada.
• En las aplicaciones para iOS, consulta Marcadores avanzados para iOS y Cómo agregar un mapa con un marcador, y, luego, inhabilita los controles y los gestos con la clase GMSUISettings.