Transazioni avanzate

Panoramica

Utilizza questa guida per scoprire come abbinare una località a un commerciante specifico e visualizzare informazioni dettagliate sul commerciante.

Quando emetti estratti conto abbreviati come "ACMEHCORP", i tuoi clienti potrebbero avere difficoltà a comprenderli. Ciò può comportare contestazioni degli addebiti e costi di assistenza aggiuntivi per te. È meglio fornire il nome completo del commerciante, ad esempio Acme Housewares.

Enriched Transactions ti consente di fornire più facilmente informazioni intuitive sulle transazioni, tra cui il nome completo del commerciante, la categoria dell'attività, l'immagine della vetrina e i dettagli di contatto e della posizione. In questo modo, aumenti la trasparenza, migliori i Net Promoter Score (NPS) e fai sì che gli utenti trascorrano più tempo nella tua app.

Esempi di schermate mobile che confrontano estratti conto delle transazioni non elaborati con dettagli dei commercianti arricchiti
Schermate di esempio delle transazioni arricchite (fai clic per ingrandire)

Abilita API

Per implementare le transazioni arricchite, devi abilitare le seguenti API nella console Google Cloud. I seguenti link aprono la console Google Cloud per consentirti di abilitare ogni API per il progetto selezionato:

Per saperne di più sulla configurazione, consulta Inizia a utilizzare Google Maps Platform.

Sezioni della guida all'implementazione

Questa guida illustra le seguenti implementazioni e personalizzazioni:

Abbina i commercianti con Google Maps Platform Associa un commerciante nella cronologia delle transazioni a un luogo in Google Maps Platform.
Visualizza i dettagli del commerciante Mostra transazioni ricche di dati con informazioni utili sul commerciante, in modo che i clienti possano riconoscere rapidamente la transazione.
Aggiungi una mappa della sede del commerciante Aggiungi una mappa della sede del commerciante con un indicatore avanzato.

Abbina i commercianti con Google Maps Platform

Questo esempio utilizza: API Places (nuova) Disponibile anche: JavaScript

Il seguente diagramma di flusso mostra in che modo la tua applicazione abbina le transazioni dei commercianti per restituire un risultato utilizzando i dettagli dei luoghi di un database di commercianti esistente o tramite una richiesta di Ricerca testuale:

Diagramma di flusso per la corrispondenza dei record delle transazioni dei commercianti con gli ID luogo e i dettagli dei luoghi
Matrice del flusso di abbinamento dei commercianti (fai clic per ingrandire)

Ottieni gli ID luogo di Google Maps Platform

Potresti avere un database di commercianti con informazioni di base come il nome e l'indirizzo dell'attività. Per ottenere le informazioni di Google Maps Platform su quel luogo, inclusi i dati di contatto e le valutazioni fornite dai clienti, trova l'ID luogo corrispondente a ogni commerciante nel tuo database.

Per ottenere l'ID luogo di un'attività, effettua una chiamata all'endpoint Ricerca testuale (nuova) nell'API Places (nuova) e richiedi solo il campo places.id nella maschera di campo, che attiva lo SKU Text Search Essentials (IDs Only). Se il commerciante ha più sedi, includi il nome della città o della via insieme al nome del commerciante nella query. Convalida i risultati restituiti per confermare che corrispondano al commerciante.

L'esempio seguente richiede l'ID luogo dell'ufficio di Google Taipei utilizzando il nome del commerciante e la città:

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'

ID luogo del negozio

Per memorizzare le informazioni di Google Maps Platform sul commerciante per richieste future, puoi memorizzare l'ID luogo a tempo indeterminato nel tuo database come attributo del record del commerciante. Devi eseguire la richiesta di Ricerca testuale (nuova) una sola volta per ogni commerciante oppure puoi cercare l'ID luogo ogni volta che un cliente richiede i dettagli della transazione.

Per mantenere accurati gli ID luogo memorizzati, aggiornali ogni 12 mesi effettuando una richiesta Place Details (New) che specifichi solo il campo id nella maschera di campo.

Se i dettagli del luogo visualizzati non corrispondono al commerciante presso cui il cliente ha completato la transazione, Google consiglia di consentire ai clienti di inviare un feedback sulla qualità della corrispondenza del commerciante.

Visualizza i dettagli del commerciante

Questo esempio utilizza: API Places (nuova) Disponibile anche: Places SDK for Android | Places SDK for iOS | Libreria Places, API Maps JavaScript

Puoi condividere i Place Details di cui i clienti hanno bisogno dopo aver visitato la sede di un commerciante. Dopo aver chiamato l'endpoint Place Details (New) nell'API Places (New), puoi filtrare ed eseguire il rendering della risposta in una finestra informativa, in una barra laterale web o in una visualizzazione dei dettagli mobile entro i limiti dei Termini di servizio di Google Maps Platform.

Visualizzazione dei dettagli della transazione su dispositivo mobile che mostra il nome, l'indirizzo, la mappa e i dati di contatto del commerciante
Esempio di schermata dei dettagli del commerciante (fai clic per ingrandire)

Per inviare una richiesta all'endpoint Place Details, devi avere l'ID luogo di ogni località. Consulta Ottieni gli ID luogo di Google Maps Platform per recuperare l'ID luogo di una sede del commerciante.

La seguente richiesta Place Details (New) restituisce il nome visualizzato, l'indirizzo formattato, le coordinate, il sito web, il numero di telefono, l'icona, l'orario di apertura e la valutazione in formato JSON per l'ID luogo di 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'

Se stai creando un'applicazione web con l'API Maps JavaScript, puoi anche utilizzare la classe Place per recuperare gli stessi campi sul client:

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

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

Aggiungi una mappa della sede del commerciante

Questo esempio utilizza: API Maps JavaScript | API Geocoding | API Maps Static Disponibile anche per: Android | iOS

Determinare la sede del commerciante

Puoi posizionare un indicatore su una mappa utilizzando le coordinate geografiche dei Place Details. Se il tuo database dei commercianti contiene indirizzi senza coordinate geografiche e non richiedi i dettagli dei luoghi, puoi utilizzare l'API Geocoding per convertire gli indirizzi in coordinate di latitudine e longitudine sul lato server, memorizzarle nel tuo database e aggiornarle almeno una volta ogni 30 giorni.

L'esempio seguente utilizza l'API Geocoding per ottenere la latitudine e la longitudine dell'ID luogo dell'ufficio di Google Taipei:

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

Aggiungi un indicatore avanzato su una mappa web

Poiché i clienti visualizzano la mappa per confermare le transazioni anziché per sfogliare o navigare, configura la mappa con un'interattività limitata e posiziona un indicatore avanzato nella posizione del commerciante. Gli indicatori avanzati richiedono un ID mappa e la libreria marker (libraries=marker).

Innanzitutto, carica l'API Maps JavaScript con libraries=marker e aggiungi un contenitore div per la mappa:

<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>

Successivamente, inizializza la mappa con gestureHandling: "none" e zoomControl: false per limitare l'interattività, fornisci il tuo mapId e crea un google.maps.marker.AdvancedMarkerElement in corrispondenza delle coordinate del commerciante:

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

Puoi anche personalizzare gli indicatori avanzati modificando lo sfondo, il bordo o il colore del glifo del segnaposto oppure fornendo un'immagine grafica personalizzata per la categoria del commerciante.

Aggiungi un'immagine di mappa statica

Se preferisci un'immagine della mappa non interattiva per il web mobile o desktop, crea un URL dell'API Maps Static con un singolo indicatore in corrispondenza delle coordinate di latitudine e longitudine o dell'indirizzo del commerciante. L'API Maps Static restituisce una versione immagine di una mappa utilizzando i parametri specificati.

La seguente richiesta restituisce una mappa stradale con dimensioni di 640 x 480 pixel, centrata su un indicatore rosso presso l'ufficio di Google Taipei con uno stile di mappa basato su 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
```

La tabella seguente descrive ogni sezione della richiesta:

URL API https://maps.googleapis.com/maps/api/staticmap?
Dimensioni delle immagini size=640x480
Indicatori di posizione del commerciante (utilizzando la codifica URL) markers=color:red%7C25.033976%2C121.5645389
Personalizzazione delle mappe basata su cloud map_id=b224095f76859890
Chiave API key=YOUR_API_KEY
Firma digitale (scopri come firmare digitalmente la tua richiesta) signature=BASE64_SIGNATURE

La richiesta produce la seguente immagine della mappa statica:

Mappa centrata sull'ufficio di Google Taipei con un indicatore di posizione rosso

Puoi anche passare un indirizzo come posizione dell'indicatore:

```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
```

Per altre opzioni dei parametri, consulta la documentazione dell'API Maps Static.

Aggiungi una mappa alla tua app mobile

Se utilizzi Maps SDK for Android o Maps SDK for iOS, puoi posizionare un indicatore avanzato utilizzando le coordinate dei dettagli del luogo.

Poiché i clienti visualizzano la mappa per confermare le transazioni anziché per sfogliare o navigare, configura una mappa con interattività limitata: