Intégration d'un widget

Cette documentation offre une description détaillée sur la manière d'intégrer un widget CityScan sur le site de votre choix, par exemple sur un site d'annonces. Elle contient notamment la description des deux méthodes d'intégration possibles et un tableau récapitulatif de tous les paramètres d'intégration.

Avant de commencer

Il y a deux manières d'intégrer le widget sur votre site : via notre librairie javascript ou directement dans une iframe.
Nous recommandons d'utiliser la librairie javascript qui offre plus de facilité en terme d'utilisation et de maintenance.

Avant de commencer, vérifiez que le nom de domaine du site qui va héberger le widget a été déclaré auprès de CityScan. En effet le widget ne peut être intégré QUE dans un site enregistré auprès de CityScan. Si vous avez le moindre doute ou que vous souhaitez enregistrer de nouveaux sites, veuillez contacter le service client CityScan.
Exemple : Votre site web www.monsiteweb.fr a été enregistré chez CityScan au moment de la configuration de votre widget. Vous pouvez intégrer votre widget sur www.monsiteweb.fr mais pas sur www.monsite-d-annonce.fr.

Pour l'intégration du widget sur votre site web, deux paramètres sont obligatoires :

  • L'identifiant de l'évaluation : soit l'id CityScan soit votre propre id
    L'évaluation doit être active. Pour plus de détail sur la création d'une évaluation, voir la documentation.
  • La clé de configuration
    La clé de configuration contrôle la personnalisation de votre widget. Selon la clé de configuration il est possible d'avoir un menu de couleur verte ou rouge par exemple. Le ou les clés de configuration vous sont fournies en début de contrat. Attention, la clé de configuration (clientKey) est différente de la clé API (apiKey) qui permet l'activation ou la désactivation des évaluations.

Intégration via notre librairie JavaScript

Notre librairie JavaScript permet de générer automatiquement le code de l'iframe contenant le widget. Commencez par inclure la librairie sur votre page web : 

<script type="text/javascript" src="https://www.cityscan.fr/assets/build/js/lib/cityscan-widget.js"></script>

Ensuite à l'endroit où vous souhaitez que votre widget apparaisse, intégrez par exemple le code suivant : 

<div id="cityscan-widget" data-ext-address-id="VOTRE_IDENTIFIANT_ADRESSE" data-client-key="VOTRE_CLIENT_KEY"></div>

Il s'agit ici de l'intégration la plus basique possible, en prenant l'hypothèse que vous utilisez votre propre identifiant adresse (data-ext-address-id). Si vous préfèrez utiliser l'identifiant CityScan, il vous suffit d'utiliser le paramètre data-id à la place du paramètre data-ext-address-id.

Libre à vous de styliser la fenêtre pour modifier sa taille ou autre. Vous pouvez également ajouter des options au widget, comme par exemple :

  • Choisir la langue du widget : français (fr-FR) ou anglais (en-US) via le paramètre data-language.
  • Modifier la taille du widget via les paramètres data-height et data-width .

Pour plus de détails et d'exemples, voir la section "Pour aller plus loin" qui récapitule tous les paramètres d'intégration. En cas d'erreur au moment de l'intégration, vous pouvez consulter la section FAQ - Mon widget ne s'affiche pas correctement, comment faire ?

Pour aller plus loin

Cette section offre une liste exhaustive des paramètres d'intégration et quelques exemples.

Intégration iframe Intégration librairie JavaScript Exemple Valeur par défaut Statut Remarques
- id "cityscan-widget" - Obligatoire Doit avoir pour valeur "cityscan-widget" pour fonctionner dans le cas d'une intégration avec librairie js.
id data-id 784512 - Conditionnel Identifiant CityScan de l'évaluation que vous souhaitez afficher
Un seul identifiant peut être renseigné dans la requête : soit l'identifiant CityScan soit le vôtre. Voir aussi l'exemple 1.
extAddressId data-ext-address-id "annonce1478483" - Conditionnel Votre propre identifiant pour le bien ou adresse que vous souhaitez afficher
Un seul identifiant peut être renseigné dans la requête : soit l'identifiant CityScan soit le vôtre.
clientKey data-client-key "xYz75g!sd(hD" - Obligatoire Clé de configuration client
La clé de configuration contrôle la personnalisation de votre widget.
- data-env "prod" ou "preprod" prod Optionnel Environnement du widget
Utile pour tester dans l'environnement de pré-production, voir aussi l'exemple 4.
Dans le cas d'une intégration via librairie js : data-env="preprod"
Dans le cas d'une intégration iframe : https://preprod.cityscan.fr au lieu de https://www.cityscan.fr dans src.
Par défaut, si ce paramètre n'est pas rempli, l'environnement considéré est la production.
language data-language "fr-FR" ou "en-US" Possible de définir votre propre valeur par défaut Optionnel Langue du widget
Pour le moment uniquement deux langues sont disponibles : fr-FR pour français et en-US pour l'anglais.
noLoc data-no-loc - - Optionnel Ne plus afficher le marqueur adresse
Cette option permet de ne plus afficher le marqueur d'adresse sur le widget. Elle est en particulier intéressante pour ne pas divulguer la position exacte de certaines adresses. Rappel : l'affichage ou non du marqueur adresse (option location) fait partie de la configuration du widget. Le paramètre noLoc permet de supplanter cette configuration à "sens unique", c'est à dire uniquement dans le sens du masquage de l'adresse. Voir aussi l'exemple 2.

Avec marqueur

Visuel Widget

Sans marqueur

Visuel Widget
A savoir :
  • Cette option a pour effet de désactiver toutes les fonctionnalités liées aux itinéraires.
  • En cas de téléchargement de rapport, le marqueur adresse sera également masqué dans le rapport.
  • Si vous pensez masquer systématiquement le marqueur adresse pour toutes vos adresses, il est recommandé d'utiliser une configuration de widget sans marqueur adresse plutôt que le paramètre URL noLoc.
Pour en savoir plus à ce sujet, consultez le guide Masquer la localisation exacte d'un bien sur un widget CityScan.
lat data-lat 47.267302 - Optionnel Options de décentrage
Les options lat et lon permettent de centrer la carte du widget sur la position (latitude/longitude) de votre choix. Une précision de 6 décimales est conseillée. Par défaut la carte du widget est centrée sur l'adresse. Voir aussi l'exemple 3.
Ces options sont utiles en particulier si vous ne voulez pas divulguer la localisation exacte du bien. Pour en savoir plus à ce sujet, consultez le guide Masquer la localisation exacte d'un bien sur un widget CityScan.

Un exemple de visuel widget est montré ci-dessous. La carte est centrée sur un point à proximité de la position exacte du bien. Le marqueur bleu de l'adresse véritable a été apposé sur la carte pour cet exemple mais il n'apparait pas dans le widget.

Visuel Widget

lon data-lon -1.518214 - Optionnel
minZoom data-min-zoom 12 Possible de définir votre propre valeur par défaut. Optionnel Niveaux de zoom :
  • Zoom minimum (on ne peut pas dézoomer plus)
  • Zoom par défaut (quand on arrive sur le widget)
  • Zoom maximum (on ne peut pas zoomer plus)
Les niveaux de zoom doivent respecter la règle suivante :
11 ≤ Zoom minimum ≤ Zoom par défaut ≤ Zoom maximum ≤ 18
De plus les trois niveaux de zoom doivent être précisés. Par exemple il n'est pas possible de modifier uniquement le niveau de zoom minimum.
Voir aussi l'exemple 5.

Quelques exemples sur Paris pour illuster les différents niveaux de zoom :

Zoom 11 (Minimum)

Visuel Widget

Zoom 16

Visuel Widget

Zoom 18 (Maximum)

Visuel Widget


landingZoom data-landing-zoom 16 Possible de définir votre propre valeur par défaut. Optionnel
maxZoom data-max-zoom 18 Possible de définir votre propre valeur par défaut. Optionnel
radius data-radius 150 - Optionnel Disque de localisation
Le rayon du disque (en m) est donné en paramètre. Ex : data-radius=150 pour un disque de 150 m de rayon. Voir aussi l'exemple 3.
Cette option est utile en particulier si vous ne voulez pas divulguer la localisation exacte du bien. Pour en savoir plus à ce sujet, consultez le guide Masquer la localisation exacte d'un bien sur un widget CityScan.
Visuel Widget

height data-height 600 - Optionnel Hauteur du widget en relatif ou en pixel. Voir aussi l'exemple 2.
width data-width 1200 - Optionnel Largeur du widget en relatif ou en pixel.
primaryColor data-primary-color %23FEFEFE %23E84242 Optionnel Couleur principale précédée d'un hashtag encodé pour les url (%23).
secondaryColor data-secondary-color %23333333 %23FFFFFF Optionnel Couleur secondaire précédée d'un hashtag encodé pour les url (%23).
pinpointColor data-pinpoint-color %23000000 %23E84242 Optionnel Couleur du marqueur précédée d'un hashtag encodé pour les url (%23).
font data-font Roboto:ital,wght@0,100;1,100 - Optionnel Police d'écriture qui doit faire partie des polices Google Fonts. Le paramètre doit être formaté tel qu'il l'est dans le paramètre family de Google Fonts : 
<link href="https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,100;1,100&display=swap" rel="stylesheet">
.

Exemple 1 : Intégration en utilisant l'identifiant CityScan

Si vous préférez utiliser l'identifiant CityScan plutôt que votre propre identifiant :

Avec la librairie JavaScript 
<div id="cityscan-widget" data-id="784512" data-client-key="VOTRE_CLIENT_KEY"></div>
Iframe 
<iframe src="https://www.cityscan.fr/widget?clientKey=VOTRE_CLIENT_KEY&id=784512"></iframe>

Exemple 2 : Intégration en masquant le marqueur adresse

Votre configuration de widget permet l'affichage du marqueur adresse par défaut. Cependant pour certaines adresse en particulier, vous ne souhaitez pas afficher le marqueur, vous pouvez donc utiliser le paramètre noLoc :

Avec la librairie JavaScript 
<div id="cityscan-widget" data-ext-address-id="VOTRE_IDENTIFIANT_ADRESSE" data-client-key="VOTRE_CLIENT_KEY" data-height=700 data-width=1200 data-no-loc></div>
Iframe 
<iframe src="https://www.cityscan.fr/widget?clientKey=VOTRE_CLIENT_KEY&extAddressId=VOTRE_IDENTIFIANT_ADRESSE&noLoc" height=500 width=1200></iframe>

Exemple de widget sans marqueur adresse

Visuel Widget

Exemple 3 : Intégration en utilisant les options décentrage et disque de localisation

Pour masquer la position exacte du bien, vous pouvez utiliser le duo d'options décentrage + disque de location.

Avec la librairie JavaScript 
<div id="cityscan-widget" data-ext-address-id="VOTRE_IDENTIFIANT_ADRESSE" data-client-key="VOTRE_CLIENT_KEY" data-radius=150 data-lat=47.267302 data-lon=-1.518214></div>
Iframe 
<iframe src="https://www.cityscan.fr/widget?clientKey=VOTRE_CLIENT_KEY&extAddressId=VOTRE_IDENTIFIANT_ADRESSE&radius=150&lat=47.267302&lon=-1.518214"></iframe>

Exemple de visuel widget (le marqueur bleu de l'adresse véritable a été apposé sur la carte pour cet exemple mais il n'apparait pas dans le widget):

Visuel Widget

Exemple 4 : Intégration d'un widget preprod

Si vous avez besoin d'intégrer un widget sur votre site de test, l'environnement à choisir est la pré-production :

Avec la librairie JavaScript 
<div id="cityscan-widget" data-ext-address-id="VOTRE_IDENTIFIANT_ADRESSE" data-client-key="VOTRE_CLIENT_KEY" data-env="preprod" ></div>
Iframe 
<iframe src="https://preprod.cityscan.fr/widget?clientKey=VOTRE_CLIENT_KEY&extAddressId=VOTRE_IDENTIFIANT_ADRESSE"></iframe>

Exemple 5 : Intégration en imposant les niveaux de zoom

Pour pouvoir personnaliser les niveaux de zoom du widget dans la requête :

Avec la librairie JavaScript 
<div id="cityscan-widget" data-ext-address-id="VOTRE_IDENTIFIANT_ADRESSE" data-client-key="VOTRE_CLIENT_KEY" data-min-zoom=15 data-landing-zoom=16 data-max-zoom=18></div>
Iframe 
<iframe src="https://www.cityscan.fr/widget?clientKey=VOTRE_CLIENT_KEY&extAddressId=VOTRE_IDENTIFIANT_ADRESSE&minZoom=15&landingZoom=16&maxZoom=18"></iframe>

FAQ - Mon widget ne s'affiche pas correctement, comment faire ?

Erreur "Pour obtenir une évaluation de cet emplacement, merci de bien vouloir nous contacter"

Cette erreur signifie que l'identifiant (soit l'id CityScan soit votre propre id) n'est pas valide par rapport à la clé de configuration utilisée.

Les questions à poser sont :
  • Avez-vous activé l'évaluation ?
    → Vérifier que l'évaluation a été correctement activée. En particulier si vous utilisez votre propre identifiant adresse vérifiez que celui-ci a été déclaré au moment de l'activation.
    Pour plus d'information sur l'activation voir la documentation sur l'API de Création.
  • Est-ce que l'évaluation est toujours active ?
    → Vérifier que l'évaluation n'a pas été désactivée. Pour connaître la liste des évaluations actuellement actives, voir la documentation sur les APIs de Recherche et Filtrage.
  • Est-ce que l'évaluation a été activée pour le bon produit CityScan ? Une évaluation pour un pack "Expert" ne peut pas être utilisée dans un widget du pack "Annonce".
    → Vérifier que l'évaluation a été activée avec une clé API (apiKey) correspondant à la clé de configuration (clientKey) présente dans l'appel.
  • Est-ce que l'évaluation a été créée dans le bon environnement ?
    → Si vous êtes en preprod par exemple, vérifier que l'évaluation a bien été créée en preprod.


Visuel Widget

Une fenêtre grise s'affiche à la place du widget

Deux raisons peuvent expliquer l'affichage d'une fenêtre grise :
  • La clé de configuration (clientKey) n'est pas valide
  • Le nom de domaine n'a pas été déclaré auprès de CityScan
Les questions à se poser sont :
  • Est-ce que j'ai bien déclaré à CityScan le nom de domaine du site sur lequel je veux intégrer le widget en production ?
    → Pour vérifier si votre nom de domaine a été déclaré ou pas, vous pouvez utiliser l'API Referers. Pour ajouter un nom de domaine, veuillez contacter le service client CityScan.
  • Est-ce qu'il n'y a pas une faute de frappe dans la clé de configuration ?
  • Est-ce que la clé de configuration existe en production?
    → Pour créer une nouvelle clé de configuration veuillez contacter le service client CityScan.
A noter : L'affichage d'une fenêtre grise en place du widget n'est possible qu'en production dans le cadre d'une intégration par iframe. C'est d'ailleurs l'un des avantages de passer par notre librairie JavaScript : dans la même situation, à la place d'une fenêtre disgracieuse, le widget ne serait tout simplement pas affiché du tout.

Visuel Widget

Erreur "ClientKey or referer error"

Cette erreur apparait uniquement en preprod dans le cadre d'une intégration iframe si on a au moins une des erreurs suivantes :
  • La clé de configuration (clientKey) n'est pas valide
  • Le nom de domaine n'a pas été déclaré auprès de CityScan
Les questions à se poser sont :
  • Est-ce que j'ai bien déclaré à CityScan le nom de domaine du site (probablement un site de test) sur lequel je veux intégrer le widget en preprod?
    → Pour vérifier si votre nom de domaine a été déclaré ou pas, vous pouvez utiliser l'API Referers. Attention utilisez bien l'environnement de preprod pour utiliser l'API : www.preprod.cityscan.fr au lieu de www.cityscan.fr. Pour ajouter un nom de domaine, veuillez contacter le service client CityScan.
  • Est-ce qu'il n'y a pas une faute de frappe dans la clé de configuration ?
  • Est-ce que la clé de configuration existe en pré-production ?
    → Pour créer une nouvelle clé de configuration veuillez contacter le service client CityScan.


Visuel Widget

Mon widget ne s'affiche pas du tout

Dans le cas de l'intégration via la librairie JavaScript, le widget ne s'affiche pas (l'iframe calculée a une hauteur nulle) si on a au moins une des erreurs suivantes :
  • La clé de configuration (clientKey) n'est pas valide
  • Le nom de domaine n'a pas été déclaré auprès de CityScan
Les questions à se poser sont :
  • Est-ce que j'ai bien déclaré à CityScan le nom de domaine du site sur lequel je veux intégrer le widget ?
    → Pour vérifier si votre nom de domaine a été déclaré ou pas, vous pouvez utiliser l'API Referers. Attention s'il agit d'un environnement preprod utilisez l'API : www.preprod.cityscan.fr au lieu de www.cityscan.fr. Pour ajouter un nom de domaine, veuillez contacter le service client CityScan. Attention à l'environnement, les configurations de production et pré-production sont indépendantes.
  • Est-ce qu'il n'y a pas une faute de frappe dans la clé de configuration ?
  • Est-ce que la clé de configuration existe dans l'environnement choisi ?
    → Pour créer une nouvelle clé de configuration veuillez contacter le service client CityScan.