Transactions enrichies

Présentation

Ce guide vous explique comment mettre en correspondance un établissement avec un marchand spécifique et afficher ses informations détaillées.

Lorsque vous émettez des relevés de transaction abrégés tels que "DACMECORP", vos clients peuvent avoir du mal à les comprendre. Cela peut entraîner des contestations de débit et des frais d'assistance supplémentaires pour vous. Il est préférable de fournir le nom complet du marchand, par exemple "Acme Housewares".

La fonctionnalité Transactions enrichies vous permet de fournir plus facilement des informations intuitives sur les transactions, y compris le nom complet du marchand, sa catégorie d'activité, une image de la vitrine, ainsi que ses coordonnées et son emplacement. Cela améliore la transparence et le Net Promoter Score (NPS), et augmente le temps passé dans votre application.

Exemples d'écrans mobiles comparant des relevés de transactions bruts avec des détails enrichis sur les marchands
Exemples d'écrans utilisant les transactions enrichies (cliquez pour agrandir)

Activer les API

Pour implémenter les transactions enrichies, vous devez activer les API suivantes dans la console Google Cloud. Les liens suivants ouvrent la console Google Cloud pour vous permettre d'activer chaque API pour le projet sélectionné :

Pour en savoir plus sur la configuration, reportez-vous à Premiers pas avec Google Maps Platform.

Sections du guide d'implémentation

Les implémentations et personnalisations suivantes sont abordées dans ce guide :

Mettre en correspondance des marchands avec Google Maps Platform Associer un marchand dans l'historique des transactions à un lieu dans Google Maps Platform
Afficher des informations sur le marchand Afficher des transactions accompagnées de données enrichies sur le marchand afin que les clients puissent rapidement reconnaître la transaction
Afficher la position du marchand sur une carte Afficher la position du marchand sur une carte avec un repère avancé

Mettre en correspondance des marchands avec Google Maps Platform

Cet exemple utilise : API Places (nouvelle version) Également disponible : JavaScript

L'organigramme suivant montre comment votre application met en correspondance les transactions avec les marchands pour renvoyer un résultat à l'aide de Place Details à partir d'une base de données de marchands existante ou via une requête Text Search :

Organigramme pour faire correspondre les enregistrements de transactions des marchands avec les ID de lieu et les détails des lieux
Matrice du flux de mise en correspondance des marchands (cliquez pour agrandir)

Obtenir des ID de lieu Google Maps Platform

Vous possédez peut-être une base de données de vos établissements contenant des informations de base telles que leur nom et leur adresse. Pour récupérer les informations dont Google Maps Platform dispose sur cet établissement (y compris ses coordonnées et les notes fournies par les clients), recherchez l'ID de lieu correspondant à chaque marchand dans votre base de données.

Pour obtenir l'ID de lieu d'un établissement, appelez le point de terminaison Text Search (New) dans l'API Places (New) et ne demandez que le champ places.id dans le masque de champ, ce qui déclenche le SKU Text Search Essentials (IDs Only). Si le marchand possède plusieurs établissements, incluez le nom de la ville ou de la rue, ainsi que le nom du marchand dans votre requête. Validez les résultats renvoyés pour confirmer qu'ils correspondent au marchand.

L'exemple suivant demande l'ID de lieu pour le bureau Google de Taipei à l'aide du nom du marchand et de la ville :

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'

Stocker les ID de lieu

Pour stocker des informations Google Maps Platform sur le marchand pour les requêtes futures, vous pouvez stocker l'ID de lieu indéfiniment dans votre base de données en tant qu'attribut du marchand. Vous ne devez exécuter la requête Text Search (New) qu'une seule fois pour chaque marchand. Vous pouvez également rechercher l'ID de lieu chaque fois qu'un client demande les détails de la transaction.

Pour que les ID de lieu stockés restent exacts, actualisez-les tous les 12 mois en envoyant une requête Place Details (New) qui ne spécifie que le champ id dans le masque de champ.

Si les informations Place Details que vous affichez ne correspondent pas au marchand auprès duquel le client a effectué la transaction, Google vous recommande de permettre aux clients d'envoyer des commentaires sur la qualité de la mise en correspondance.

Afficher des informations sur le marchand

Cet exemple utilise : API Places (nouvelle version) Également disponible : SDK Places pour Android | SDK Places pour iOS | Bibliothèque Places, API Maps JavaScript

Vous pouvez partager les données Place Details dont les clients ont besoin après s'être rendus dans l'un de vos établissements. Après avoir appelé le point de terminaison Place Details (New) dans l'API Places (New), vous pouvez filtrer et afficher la réponse dans une fenêtre d'informations, une barre latérale Web ou une vue détaillée mobile, dans les limites des conditions d'utilisation de Google Maps Platform.

Vue détaillée d'une transaction sur mobile affichant le nom, l'adresse, la carte et les coordonnées du marchand
Exemple d'écran affichant les détails sur le marchand (cliquez pour agrandir)

Pour envoyer une requête au point de terminaison Place Details, vous avez besoin de l'ID de lieu de chaque établissement. Consultez Obtenir des ID de lieu Google Maps Platform pour récupérer l'ID de lieu d'un établissement marchand.

La requête Place Details (New) suivante renvoie le nom à afficher, l'adresse mise en forme, les coordonnées, le site Web, le numéro de téléphone, l'icône, les horaires d'ouverture et la note au format JSON pour l'ID de lieu 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 vous créez une application Web avec l'API Maps JavaScript, vous pouvez également utiliser la classe Place pour récupérer les mêmes champs sur le client :

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

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

Ajouter une carte indiquant la position du marchand

Cet exemple utilise : API Maps JavaScript | API Geocoding | API Maps Static Également disponible : Android | iOS

Déterminer la position du marchand

Vous pouvez placer un repère sur une carte en utilisant les coordonnées géographiques issues de Place Details. Si votre base de données de marchands contient des adresses postales sans coordonnées géographiques et que vous ne demandez pas de détails sur les lieux, vous pouvez utiliser l'API Geocoding pour convertir les adresses postales en coordonnées de latitude et de longitude côté serveur, stocker ces coordonnées dans votre base de données et les actualiser au moins une fois tous les 30 jours.

L'exemple suivant utilise l'API Geocoding pour obtenir la latitude et la longitude de l'ID de lieu du bureau Google de Taipei :

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

Ajouter un repère avancé sur une carte Web

Étant donné que, pour vérifier les transactions, vos clients vont simplement regarder la carte (et non la parcourir ni lancer la navigation), configurez votre carte avec une interactivité limitée et placez un repère avancé à l'emplacement du marchand. Les repères avancés nécessitent un ID de carte et la bibliothèque marker (libraries=marker).

Commencez par charger l'API Maps JavaScript avec libraries=marker et ajoutez un conteneur div pour la carte :

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

Ensuite, initialisez la carte avec gestureHandling: "none" et zoomControl: false pour limiter l'interactivité, fournissez votre mapId et créez un google.maps.marker.AdvancedMarkerElement aux coordonnées du marchand :

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

Vous pouvez également personnaliser vos repères avancés en modifiant la couleur de l'arrière-plan, de la bordure ou du glyphe du repère, ou en fournissant une image personnalisée pour la catégorie du marchand.

Ajouter une image de carte statique

Si vous préférez une image de carte non interactive pour le Web sur ordinateur ou mobile, créez une URL d'API Maps Static avec un seul repère correspondant à la latitude/longitude ou à l'adresse du marchand. L'API Maps Static renvoie une image d'une carte en fonction des paramètres que vous spécifiez.

La requête suivante renvoie une carte routière de 640 x 480 pixels, centrée sur un repère rouge au bureau Google de Taipei, avec un style de carte basé dans le 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
```

Le tableau suivant décrit chaque section de la requête :

URL de l'API https://maps.googleapis.com/maps/api/staticmap?
Taille d'image size=640x480
Repères de position du marchand (avec encodage URL) markers=color:red%7C25.033976%2C121.5645389
Style de carte dans Google Cloud map_id=b224095f76859890
Clé API key=YOUR_API_KEY
Signature numérique (découvrez comment ajouter une signature numérique à votre requête) signature=BASE64_SIGNATURE

La requête produit l'image de carte statique suivante :

Carte centrée sur le bureau Google de Taipei avec un repère rouge

Vous pouvez également transmettre une adresse pour positionner le repère :

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

Pour en savoir plus sur les options de paramètres, consultez la documentation de l'API Maps Static.

Ajouter une carte à votre application mobile

Si vous utilisez le SDK Maps pour Android ou le SDK Maps pour iOS, vous pouvez placer un repère avancé en utilisant les coordonnées issues de Place Details.

Étant donné que, pour vérifier les transactions, vos clients vont simplement regarder la carte (et non la parcourir ni lancer la navigation), configurez une carte avec des interactions limitées :