Erweiterte Transaktionsaufstellungen

Übersicht

In diesem Leitfaden erfahren Sie, wie Sie einen Standort mit einem bestimmten Händler abgleichen und detaillierte Informationen zu ihm anzeigen lassen können.

Wenn Sie abgekürzte Transaktionsaufstellungen wie „ACMEHCORP“ ausstellen, kann dies für Ihre Kunden schwer verständlich sein. Das kann zu angefochtenen Belastungen und zusätzlichen Supportkosten für Sie führen. Geben Sie stattdessen den vollständigen Namen des Händlers an, z. B. Acme Housewares.

Mit erweiterten Transaktionsaufstellungen können Sie intuitive Transaktionsinformationen bereitstellen, darunter den vollständigen Namen des Händlers, die Unternehmenskategorie, ein Bild der Außenansicht sowie Kontakt- und Standortdetails. Dies erhöht die Transparenz, verbessert den Net Promoter Score (NPS) und führt dazu, dass Nutzer mehr Zeit in Ihrer App verbringen.

APIs aktivieren

Für die Implementierung von erweiterten Transaktionsaufstellungen müssen in der Google Cloud Console die unten stehenden APIs aktiviert werden. Über die folgenden Links können Sie die Google Cloud Console öffnen und die einzelnen APIs für das ausgewählte Projekt aktivieren:

• Places API (New)
• Geocoding API
• Maps JavaScript API, Maps Static API, Maps SDK for Android oder Maps SDK for iOS

Weitere Informationen zur Einrichtung finden Sie unter Erste Schritte mit der Google Maps Platform.

Abschnitte des Implementierungsleitfadens

In diesem Leitfaden werden die folgenden Implementierungen und Anpassungen behandelt:

Im folgenden Flussdiagramm sehen Sie, wie Händlertransaktionen in Ihrer Anwendung abgeglichen werden, um mithilfe einer „Place Details“-Anfrage aus einer bestehenden Händlerdatenbank oder über eine „Text Search“-Anfrage ein Ergebnis abzurufen:

Orts-IDs von der Google Maps Platform abrufen

Angenommen, Sie haben eine Händlerdatenbank mit grundlegenden Informationen wie dem Namen des Unternehmens und der Adresse. Wenn nun Daten zu einem entsprechenden Ort von der Google Maps Platform abgerufen werden sollen, einschließlich Kontaktdaten und von Kunden zur Verfügung gestellter Bewertungen, müssen Sie nach der Orts-ID suchen, die dem jeweiligen Händler in Ihrer Datenbank entspricht.

Um die Orts-ID eines Unternehmens abzurufen, müssen Sie den Endpunkt Text Search (New) in der Places API (New) aufrufen und nur das Feld places.id in der Feldmaske anfordern. Dadurch wird die SKU Text Search Essentials (IDs Only) ausgelöst. Wenn der Händler mehrere Standorte hat, geben Sie in Ihrer Anfrage den Ort oder die Straße zusammen mit dem Händlernamen an. Prüfen Sie die zurückgegebenen Ergebnisse, um sicherzustellen, dass sie mit dem Händler übereinstimmen.

Im folgenden Beispiel werden der Händlername und die Stadt verwendet, um die Orts-ID der Google-Niederlassung in Taipeh anzufordern:

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'

Orts-IDs speichern

Wenn Sie Google Maps Platform-Informationen zum Händler für zukünftige Anfragen speichern möchten, können Sie die entsprechende Orts-ID unbegrenzt als Attribut des Händler-Datensatzes in Ihrer Datenbank speichern. Sie müssen die Anfrage „Text Search (New)“ nur einmal pro Händler ausführen. Alternativ können Sie auch jedes Mal nach der Orts-ID suchen, wenn ein Kunde Transaktionsdetails anfordert.

Damit Ihre gespeicherten Orts-IDs korrekt bleiben, sollten Sie sie alle 12 Monate aktualisieren. Stellen Sie dazu eine Place Details (New)-Anfrage, in der Sie nur das Feld id in der Feldmaske angeben.

Die über eine „Place Details“-Anfrage abgerufenen Ortsdetails stimmen nicht immer mit dem Händler überein, bei dem die Transaktion durchgeführt wurde. Daher empfiehlt es sich, Nutzern die Möglichkeit zu geben, Feedback zur Qualität der Händlerübereinstimmung zu hinterlassen.

Sie können die über eine „Place Details“-Anfrage abgerufenen Ortsdetails freigeben, die Kunden nach dem Besuch eines Händlerstandorts benötigen. Nachdem Sie den Endpunkt „Place Details (New)“ in der Places API (New) aufgerufen haben, können Sie die Antwort filtern und in einem Infofenster, einer Web-Seitenleiste oder einer mobilen Detailansicht darstellen. Dabei müssen Sie die Nutzungsbedingungen der Google Maps Platform einhalten.

Wenn Sie eine Anfrage an den Place Details-Endpunkt senden möchten, benötigen Sie die Orts-ID für jeden Standort. Informationen zum Abrufen der Orts-ID eines Händlerstandorts finden Sie unter Orts-IDs von der Google Maps Platform abrufen.

Die folgende „Place Details (New)“-Anfrage gibt den Anzeigenamen, die formatierte Adresse, die Koordinaten, die Website, die Telefonnummer, das Symbol, die Öffnungszeiten und die Bewertung der Orts-ID der Google-Niederlassung in Taipei 101 im JSON-Format zurück:

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'

Wenn Sie eine Webanwendung mit der Maps JavaScript API erstellen, können Sie auch die Place-Klasse verwenden, um dieselben Felder auf dem Client abzurufen:

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

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

Standort des Händlers ermitteln

Sie können eine Markierung auf einer Karte platzieren, indem Sie die geografischen Koordinaten aus den Place Details verwenden. Wenn in Ihrer Händlerdatenbank Adressen ohne geografische Koordinaten enthalten sind und Sie keine Ortsdetails anfordern, können Sie die Geocoding API verwenden, um Adressen auf Serverseite in Längen- und Breitengrade umzuwandeln. Diese Koordinaten können Sie dann in Ihrer Datenbank speichern und mindestens alle 30 Tage aktualisieren.

Im folgenden Beispiel werden Breiten- und Längengrad der Google-Niederlassung in Taipeh mit der Geocoding API anhand der Orts-ID abgefragt:

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

Erweiterte Markierung auf einer Webkarte hinzufügen

Da Kunden die Karte nur zur Bestätigung von Transaktionen verwenden und nicht zum Suchen oder Navigieren, sollten Sie die Karte mit eingeschränkter Interaktivität konfigurieren und eine erweiterte Markierung am Standort des Händlers platzieren. Für erweiterte Markierungen sind eine Karten-ID und die marker-Bibliothek (libraries=marker) erforderlich.

Laden Sie zuerst die Maps JavaScript API mit libraries=marker und fügen Sie einen Container div für die Karte hinzu:

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

Als Nächstes initialisieren Sie die Karte mit gestureHandling: "none" und zoomControl: false, um die Interaktivität einzuschränken, geben Ihren mapId an und erstellen eine google.maps.marker.AdvancedMarkerElement an den Koordinaten des Händlers:

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

Sie können Ihre erweiterten Markierungen auch anpassen, indem Sie den Hintergrund, den Rahmen oder die Symbolfarbe der Markierung ändern oder ein benutzerdefiniertes Bild für die Kategorie des Händlers angeben.

Statisches Kartenbild hinzufügen

Wenn Sie für Computer oder mobiles Web ein nicht interaktives Kartenbild bevorzugen, erstellen Sie eine Maps Static API-URL mit einer einzelnen Markierung am Breiten- und Längengrad bzw. an der Adresse des Händlers. Die Maps Static API gibt anhand der von Ihnen angegebenen Parameter eine Bildversion einer Karte zurück.

Mit der folgenden Anfrage wird eine Straßenkarte mit einer Größe von 640 × 480 Pixeln zurückgegeben. In der Mitte ist eine rote Markierung für die Google-Niederlassung in Taipeh zu sehen. Die Karte hat einen cloudbasierten Kartenstil:

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

In der folgenden Tabelle werden die einzelnen Abschnitte der Anfrage beschrieben:

Die Anfrage erzeugt das folgende statische Kartenbild:

Sie können auch eine Adresse als Markierungsposition übergeben:

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

Weitere Parameteroptionen finden Sie in der Dokumentation zur Maps Static API.

Karte in eine App einfügen

Wenn Sie das Maps SDK for Android oder Maps SDK for iOS verwenden, können Sie die Koordinaten aus den Place Details-Anfragen verwenden, um eine erweiterte Markierung zu setzen.

Da Kunden ihre Transaktionen anhand der Karte bestätigen, sollte diese nur begrenzt interaktiv sein und keine Optionen zum Suchen und Navigieren enthalten:

• Entsprechende Informationen zu Android-Apps finden Sie unter Erweiterte Markierungen für Android und Karte mit einer Markierung hinzufügen. Für eingeschränkte Interaktivität sollten Sie den Lite-Modus aktivieren.
• Für iOS-Apps sollten Sie sich die Artikel Erweiterte Markierungen für iOS und Karte mit einer Markierung hinzufügen ansehen und mit der Klasse GMSUISettings Steuerelemente und Touch-Gesten deaktivieren.