Utiliser les paramètres d’URL—ArcGIS Experience Builder

Remarque :

À compter de la version de février 2024 de Experience Builder, les délimiteurs d’URL conservés qui ne figurent pas dans les valeurs de paramètre doivent être en texte brut et ne peuvent pas être encodés. Les URL avec des délimiteurs encodés créés avant la version de février 2024 ne fonctionnent plus. Vous devez les transformer en texte brut.

Experience Builder permet d’ajouter des paramètres d’URL dans vos applications. Vous pouvez utiliser les paramètres d’URL pour améliorer une expérience en définissant une langue, renvoyant vers une page donnée, activant l’aperçu avant impression et bien plus.

Les paramètres sont ajoutés à la fin de l’URL et mis en forme en tant que paire clé-valeur connectée avec un signe égal. Les applications Experience Builder prennent en charge les paramètres qui sont des chaînes de requête et des fragments, c’est-à-dire qu’ils commencent par un point d’interrogation (?) ou un croisillon (#). Pour ajouter plusieurs paramètres, vous devez les séparer par des esperluettes (&). Les URL d’expérience avec des paramètres utilisent la structure suivante :

 https://<domain>/experience/<AppID>/[?<param1=value>&<param2=value>#<param3=value>...]

En voici un exemple :

https://experience.arcgis.com/experience/<AppId>?locale=fr#data_s=id%3AdataSource_3-World_Cities_8506%3A1

L’URL d’une expérience peut contenir un ou plusieurs paramètres parmi les suivants.

Attention :

Dans cette rubrique, les crochets ([]) indiquent que le paramètre ou la valeur à l’intérieur est facultatif. N’ajoutez pas de crochet à une URL.

Paramètres généraux

Les sous-sections ci-après décrivent les paramètres d’URL généraux.

Changer de langue

Pour modifier la langue de l’application, utilisez le paramètre locale et un code de langue ISO 639-1 de deux lettres. Experience Builder prend en charge les mêmes langues que ArcGIS Online, notamment les codes de langue suivants : ar, bg, bs, ca, cs, da, de-at, de-de, de-ch, el, en-au, en-ca, en-gb, en-us, es-es, es-mx, et, fi, fr-fr, fr-ch, he, hr, hu, id, it-it, it-ch, ja, ko, lt, lv, nb, nl, pl, pt-br, pt-pt, ro, ru, sk, sl, sr, sv, th, tr, uk, vi, zh-cn, zh-hk et zh-tw.

Pour utiliser une application Experience Builder en français et en français suisse, vous pouvez ajouter locale=fr à l’URL, comme dans les exemples suivants :

https://experience.arcgis.com/experience/<AppId>/?locale=fr

https://experience.arcgis.com/experience/<AppId>/?locale=fr-ch

Remarque :

Si vous attribuez une langue sans préciser les paramètres régionaux (par exemple, fr au lieu de fr-ch ou fr-fr), vous risquez de ne pas obtenir le format de date ou de nombre attendu. En effet, différents paramètres régionaux qui utilisent la même langue peuvent avoir différentes notations pour les dates et les nombres, comme aux États-Unis (en-us) et au Royaume-Unis (en-gb).

Définir la carte ou la scène Web

Pour afficher une carte ou une scène dans un widget Map (Carte), utilisez webmap ou webscene, suivi de l’ID de l’élément de la carte ou de la scène.

https://experience.arcgis.com/builder/?webmap=<ItemID>

https://experience.arcgis.com/builder/?webscene=<ItemID>

https://experience.arcgis.com/builder/?webmap=3582b744bba84668b52a16b0b6942544

Accéder à une page

Pour renvoyer vers une page spécifique, utilisez page suivi du nom de la page. Dans les applications ArcGIS Online Experience Builder, le paramètre de page ne fait pas partie d’une chaîne de requête et ne suit pas un point d’interrogation. Il est ajouté dans le chemin de l’URL, comme dans les exemples suivants :

https://experience.arcgis.com/experience/<AppId>/page/Page-4

https://experience.arcgis.com/experience/<AppId>/page/{xxxHome}/

Accéder à un bloc

Pour renvoyer vers un bloc spécifique, utilisez block suivi de l’ID de bloc. En voici un exemple :

https://experience.arcgis.com/experience/<AppId>/?block_id=layout1_block1

Pour trouver un ID de bloc, vous pouvez définir un lien vers le bloc sur un bouton, une image ou tout autre widget prenant en charge l’optionSet link (Définir un lien). Lorsque vous prévisualisez l’application et que vous cliquez sur le widget lié, l’ID de bloc apparaît dans l’URL.

Accéder à une vue

Pour renvoyer vers la vue d’une section active spécifique, utilisez views suivi d’une étiquette de vue comme v1 ou View 1.

https://experience.arcgis.com/experience/<AppId>/?views=View-2

https://experience.arcgis.com/experience/<AppId>/?views=v1

Ouvrir une fenêtre

Pour renvoyer vers une fenêtre active spécifique, utilisez dlg suivi d’un ID ou d’une étiquette de fenêtre.

https://experience.arcgis.com/experience/<AppId>/?dlg=Window-1

Contrôler l’activation des fenêtres

Pour imbriquer dans une application Experience Builder des fenêtres de présentation ou des fenêtres de page sans que cette application n’accède automatiquement à ces fenêtres, pour pouvez utiliser le paramètre disable_window_focus. Ajoutez l’URL suivante à la page Web hôte pour désactiver le comportement d’accès. Par défaut, disable_window_focus est défini sur False (Faux).

https://experience.arcgis.com/experience/<AppId>/?disable_window_focus=true

Pour contrôler l’activation des fenêtres pour une fenêtre spécifique, utilisez dlg, suivi d’un ID ou d’une étiquette de fenêtre et du paramètre disable_window_focus, comme dans l’exemple suivant :

https://experience.arcgis.com/experience/<AppId>/?dlg=Window-1&disable_window_focus=true

Afficher le mode brouillon

Lorsque vous prévisualisez une application, le paramètre draft est automatiquement ajouté. Il vous permet d’obtenir les ressources des applications non publiées.

https://experience.arcgis.com/experience/<AppId>/?draft=true

https://experience.arcgis.com/experience/<AppId>/?draft=1

Ouvrir l’aperçu avant impression

Pour activer le mode d’aperçu avant impression, utilisez print_preview.

https://experience.arcgis.com/experience/<AppId>/?print_preview=true

https://experience.arcgis.com/experience/<AppId>/?print_preview=1

Paramètres liés aux données

Les sous-sections ci-après décrivent les paramètres d’URL liés aux données.

Sélectionner des données

Pour sélectionner des enregistrements de données, utilisez le paramètre data_s, qui suit un croisillon (#).

Chaque source de données dans une application possède son propre ID de source de données. Lorsque vous sélectionnez un enregistrement de données, l’ID de la source de données est ajouté dans l’URL de l’application, ainsi que le type et la condition de la sélection. Si plusieurs sélections sont effectuées, elles sont séparées par des virgules (,). En voici un exemple :

https://experience.arcgis.com/experience/<AppId>/#data_s=<selection type>:<data source ID>:<selection condition>,<selection type>:<data source ID>:<selection condition>,...

Il existe trois types de sélection : id, geometry et where.

Lorsque le type de sélection est id, vous sélectionnez des entités à l’aide de leurs ID d’enregistrement. Si vous sélectionnez plusieurs enregistrements provenant de la même source de données, les ID d’enregistrement sont séparés par des signes plus (+). En voici un exemple :
```
https://experience.arcgis.com/experience/<AppId>/#data_s=id:widget_1-dataSource_1-1871234a785-layer-2:1+2+3
```
Lorsque le type de sélection est geometry, vous sélectionnez des entités en fonction de leur localisation par rapport aux autres entités. Utilisez des tildes (~) pour connecter plusieurs ID de source de données. En voici un exemple :
```
https://experience.arcgis.com/experience/<AppId>/#data_s=geometry:widget_1-dataSource_1-1871234a785-layer-2~widget_1-dataSource_1-1871234a785-layer-3:<the geometry JSON>
```
Lorsque le type de sélection est where, vous sélectionnez des entités en fonction de leurs attributs. En voici un exemple :
```
https://experience.arcgis.com/experience/<AppId>/#data_s=where:widget_1-dataSource_1-1871234a785-layer-2:a>1
```

Vous pouvez utiliser ce paramètre pour rechercher l’ID de la source de données spécifique d’une couche. Par exemple, vous pouvez ajouter un widget Liste et le connecter à une couche, prévisualiser l’application et sélectionner des enregistrements dans la liste. L’URL est renseignée comme dans l’exemple suivant :

https://experience.arcgis.com/experience/<AppID>/#data_s=id%3AdataSource_3-World_Cities_8506%3Axxxxxx

La valeur après id%3A et avant %3Axxxx est l’ID de la source de données de la couche. Muni de l’ID, vous pouvez l’utiliser avec d’autres paramètres pour filtrer la source de données ou changer les versions.

Remarque :

Experience Builder utilisait auparavant le paramètre ?data_id pour sélectionner des données. Ce paramètre est toujours pris en charge actuellement, mais sera bientôt obsolète.

Filtrer les sources de données.

Pour filtrer directement une source de données, utilisez data_filter. Le format de filtre est une syntaxe de clause WHERE standard. Pour filtrer plusieurs sources de données, utilisez le [<dsId:filter>,<dsId:filter>].

Attention :

Certains filtres peuvent inclure des caractères qui sont des délimiteurs d’URL conservés (par exemple, "&", "=", "'" et "?"). Pour que l’URL interprète correctement les valeurs, vous devez encoder dans l’URL les caractères non sécurisés en les remplaçant par un caractère % suivi de la valeur correspondant à son équivalent hexadécimal au format UTF-8.

La table suivante répertorie les caractères courants que vous devez encoder s’ils se trouvent dans des valeurs de paramètre :


Caractère non sécurisé	Valeur encodée
ESPACE	%20
#	%23
%	%25
&	%26
’	%27
,	%2C
:	%3A
=	%3D
?	%3F

Remarque :

Il vous suffit d’encoder les caractères non sécurisés dans des valeurs de paramètre. Si un caractère agit comme délimiteur d’URL, c’est-à-dire qu’il ne se trouve pas dans une valeur de paramètre, il doit être en texte brut et ne peut pas être encodé.

L’URL suivante est une URL avec un filtre décodé, qui ne génére pas le résultat attendu :

http://experience.arcgis.com/experience/<AppID>/?data_filter=dataSource_1:name='Even&Odd'

L’URL suivante est une version correctement encodée de l’URL ci-avant. Notez que certains caractères de la table ci-dessus ne sont pas encodés. Cela vient du fait qu’ils font office de délimiteurs d’URL.

http://experience.arcgis.com/experience/<AppID>/?data_filter=dataSource_1:name%3D%27Even%26Odd%27

L’URL suivante est un autre exemple d’URL avec deux paramètres de filtre encodés (objectid=1 et fieldA>2) :

https://experience.arcgis.com/experience/<AppId>/?data_filter=ds1:objectid%3D1,ds2:fieldA%3E2

Modifier la version de géodatabase d’une source de données

Pour modifier la version de géodatabase d’une source de données, utilisez data_version.

https://experience.arcgis.com/experience/<AppId>/?data_version=<dsId:version>,<dsId:version>

https://experience.arcgis.com/experience/<AppId>/?data_version=dsId1:v1, dsID2:v1

Paramètres liés à un widget

Vous pouvez utiliser l’URL d’une application pour influer sur les comportements du widget en ajoutant des paramètres d’URL de widget. Bien que différents paramètres soient implémentés via diverses méthodes, ils adoptent généralement la même syntaxe :

https://experience.arcgis.com/experience/<AppId>#widget_1=param1:<value>,param2:<value>&widget_2=param1:<value>&...

Les paramètres de widget commencent par des hashmarks (#) dans une URL et sont reliés par des esperluettes (&). Si plusieurs paramètres affectent le même widget, ils sont séparés par des virgules.

Certaines valeurs peuvent inclure des caractères qui sont des délimiteurs d’URL conservés (par exemple, "&", "=", "'" et "?"). Pour que l’URL interprète correctement les valeurs, vous devez encoder dans l’URL les caractères non sécurisés en les remplaçant par un caractère % suivi de la valeur correspondant à son équivalent hexadécimal au format UTF-8. Les délimiteurs d’URL en dehors des valeurs de paramètre doivent être en texte brut et ne peuvent pas être encodés.

Par exemple, le paramètre center dans l’URL suivante ne fonctionnera pas correctement, car deux des virgules doivent être encodées.

https://experience.arcgis.com/experience/<AppId>#map_1=center:-100,100,102100,rotation:45

L’URL suivante est la version correctement écrite de l’URL ci-dessus :

https://experience.arcgis.com/experience/<AppId>#map_1=center:-100%2C100%2C102100,rotation:45

Paramètres du widget Map (Carte)

Les sous-sections ci-après décrivent les paramètres d’URL liés à la carte. Vous pouvez utiliser les paramètres sous Manage URL status (Gérer le statut de l’URL) pour faire en sorte que ces paramètres apparaissent dans l’URL lorsque l’utilisateur interagit avec le widget Map (Carte). Tous les paramètres du widget Map (Carte) suivent les croisillons (#).

Remarque :

Les paramètres center, scale et rotation du widget Map (Carte) fonctionnent uniquement avec des cartes Web, pas avec des scènes Web.

Définir la carte ou la scène Web lors du chargement initial d’un widget Map (Carte)

Si votre widget Map (Carte) contient plusieurs cartes ou scènes Web, vous pouvez définir laquelle activer lors du chargement de l’application à l’aide du paramètre active_datasource_id suivi de l’ID de source de données de l’élément souhaité. Voici quelques exemples :

https://experience.arcgis.com/experience/<AppId>#<mapWidgetID>=active_datasource_id:<dataSourceId>

https://experience.arcgis.com/experience/<AppId>#map_1=active_datasource_id:dataSource_4

Centrer une carte

Pour centrer une carte sur un emplacement en particulier, utilisez le paramètre center suivi des coordonnées souhaitées et de l’identifiant connu du système de coordonnées souhaité (WKID). Voici quelques exemples :

https://experience.arcgis.com/experience/<AppId>#<mapWidgetID>=center:<x,y,wkid>

https://experience.arcgis.com/experience/<AppId>#map_1=center:-10373125.398783844%2C4598516.55871741%2C102100

Définir l’échelle de la carte

Pour définir l’échelle de la carte, utilisez le paramètre scale suivi d’une valeur d’échelle. Voici quelques exemples :

https://experience.arcgis.com/experience/<AppId>#<mapWidgetID>=scale:<scaleValue>

https://experience.arcgis.com/experience/<AppId>#map_1=scale:19257701.0800833

Définir la rotation de la carte

Pour définir la rotation de la carte, utilisez le paramètre rotation suivi d’un nombre de degrés. Voici quelques exemples :

https://experience.arcgis.com/experience/<AppId>#<mapWidgetID>=rotation:<rotationValue>

https://experience.arcgis.com/experience/<AppId>#map_1=rotation:45

Définir le point de vue de la carte

Pour définir le point de vue, qui est l’emplacement ou la position de la caméra à partir d’où afficher la carte ou la scène, utilisez viewpoint. Si votre widget Map (Carte) contient plusieurs cartes ou scènes, le paramètre viewpoint les affecte tous.

Les points de vue et leurs propriétés sont généralement écrits au format JSON, comme dans l’exemple suivant :

 {
  "rotation": 0,
  "scale": 19966005.903731048,
  "targetGeometry": {
    "spatialReference": {
      "latestWkid": 3857,
      "wkid": 102100
    },
    "x": -9870655.016044471,
    "y": 4724533.527708739
  }
}

Pour définir un point de vue spécifique à l’aide de l’URL, vous devez encoder toutes ces propriétés, généralement écrites au format JSON, dans l’URL. En voici un exemple :

https://experience.arcgis.com/experience/<AppId>#map_1=viewpoint:%7B"rotation"%3A0%2C"scale"%3A24387741.012671936%2C"targetGeometry"%3A%7B"spatialReference"%3A%7B"latestWkid"%3A3857%2C"wkid"%3A102100%7D%2C"x"%3A-10078461.002935613%2C"y"%3A4523117.553838721%7D%7D

Remarque :

Les paramètres center, scale et rotation ont des priorités plus élevées que le paramètre viewpoint et le remplacent si vous utilisez plusieurs paramètres liés à une carte Web.

Remarque :

Les modifications d’étendue de la carte qui ont été générées par des actions Messages ont une priorité plus élevée que celles générées par des paramètres d’URL. Par exemple, si vous tentez d’ouvrir un widget Map (Carte) sur des étendues prédéfinies en utilisant les paramètres d’URL ci-dessus mais que le widget Map (Carte) est également configuré en tant que cible du déclencheur Record selection changes (Modifications de sélection d’enregistrements) et des actions Messages Pan to (Déplacer sur) ou Zoom to (Zoom sur), les étendues associées aux actions Messages remplacent les étendues que vous avez définies avec les paramètres d’URL.

Définir la visibilité des couches de carte

Pour définir la visibilité des couches d’une carte, utilisez le paramètre layer_visibility.

La visibilité d’une couche est généralement écrite au format JSON, comme dans l’exemple suivant :

 {
  "widget_1-dataSource_1": {
    "widget_1-dataSource_1-187938b7328-layer-2": false
  },
  "widget_1-dataSource_4": {
    "widget_1-dataSource_4-18a690b433a-layer-4": false
  }
}

Pour que les couches de votre carte soient visibles ou masquées à l’aide de l’URL, vous devez encoder toutes les informations dans l’URL après le paramètre layer_visibility. En voici un exemple :

https://experience.arcgis.com/experience/<AppId>#map_1=layer_visibility:%7B%22widget_1-dataSource_1%22%3A%7B%22widget_1-dataSource_1-187938b7328-layer-2%22%3Afalse%7D%2C%22widget_1-dataSource_4%22%3A%7B%22widget_1-dataSource_4-18a690b433a-layer-4%22%3Afalse%7D%7D

Paramètres du widget Search (Rechercher)

Les sous-sections ci-après décrivent les paramètres d’URL liés à la recherche. Vous pouvez utiliser les paramètres sous Manage URL status (Gérer le statut de l’URL) pour faire en sorte que ces paramètres apparaissent dans l’URL lorsque l’utilisateur effectue une recherche. Les paramètres du widget Search (Rechercher) suivent les marques de hachage (#).

Afficher l’entrée de recherche

Le paramètre searchText montre quel texte l’utilisateur a saisi pour effectuer la recherche. Voici un exemple d’URL avec le paramètre searchText :

https://experience.arcgis.com/experience/<AppId>#<searchWidgetID>=search_status:%7B"searchText"%3A"<text>"%7D

Afficher la source de recherche

Lorsque l’utilisateur effectue une recherche à l’aide de seulement une partie des sources de recherche disponibles, un des deux paramètres suivants apparaissent dans l’URL :

Si au moins une source de recherche est décochée dans le menu déroulant du widget lors de l’exécution, le paramètre serviceEnabledList apparaît et définit les sources de recherche qui sont cochées. Ce paramètre est masqué lorsque toutes les sources de recherche sont cochées. Voici un exemple d’URL codée :
```
https://experience.arcgis.com/experience/<AppId>#<searchWidgetID>=search_status:%7B"serviceEnabledList"%3A%5B"<SourceID1>"%2C"<SourceID2>"%5D%7D
```
Si l’utilisateur clique sur une suggestion pour appliquer une recherche, le paramètre "status":{"configId":"<SourceID>"} apparaît et définit la source de recherche unique utilisée dans la recherche actuelle. L’entrée de recherche et la source de recherche apparaissent toutes deux dans l’URL. Voici un exemple d’URL codée :
```
https://experience.arcgis.com/experience/<AppId>#<searchWidgetID>=search_status:%7B"searchText"%3A"<text>"%2C"status"%3A%7B"configId"%3A"<SourceID>"%7D%7D
```

Si l’utilisateur clique sur une suggestion de recherche provenant d’une source du localisateur, l’URL affiche le paramètre magicKey associé à la suggestion. magicKey est un ID unique qui lie une suggestion à une adresse ou un lieu. Voici un exemple de propriétés et de paramètres de recherche écrits au format JSON :

{
	"searchText": "<text>",
	"status":{
		"configId": "<SourceID>",
		"magicKey": "<key>"
	}
}

Voici un exemple des mêmes propriétés et paramètres, écrits dans une URL codée :

https://experience.arcgis.com/experience/<AppId>#<searchWidgetID>=search_status:%7B"searchText"%3A"<text>"%2C"status"%3A%7B"configId"%3A"<SourceID>"%2C"magicKey"%3A"<key>"%7D%7D

Paramètres de connexion

Les sous-sections ci-après décrivent les paramètres d’URL liés à la connexion.

Partager l’authentification via un widget Incorporer

Certaines applications Web invitent les utilisateurs à se connecter avec un compte ArcGIS. Une application peut demander aux utilisateurs de se connecter en raison de ses paramètres de partage, car elle inclut des widgets qui utilisent un contenu Premium ou pour d'autres raisons.

Pour incorporer une application Web ArcGIS dans une application Experience Builder si toutes deux demandent aux utilisateurs de se connecter, vous pouvez ajouter les paramètres d’URL arcgis-auth-origin et arcgis-auth-portal pour partager l’authentification entre ces deux applications afin que les utilisateurs n’aient à se connecter qu’une seule fois.

Pour imbriquer une application Experience Builder privée dans une autre application Experience Builder, utilisez ?arcgis-auth-origin= afin de définir l'URL du domaine d'application hôte pour l'authentification. En voici un exemple :

https://<orgdomain>/experience/<AppID>/?arcgis-auth-origin=<your host app domain, such as https://localhost:3001>

Pour intégrer une application basée sur une API JavaScript, comme une application Web AppBuilder, utilisez ?arcgis-auth-origin= pour l’authentification du domaine d’application hôte et ?arcgis-auth-portal= pour le JavaScript du portail ArcGIS à partir duquel l’application basée sur l’API JavaScript a besoin d’une authentification. Voici quelques exemples :

https://<orgdomain>/apps/webappviewer/index.html?id=<appID>&arcgis-auth-origin=<your host app domain, such as https://localhost:3001>&arcgis-auth-portal=<orgA URL>

https://www.arcgis.com/apps/dashboards/index.html#/<appID>?arcgis-auth-origin=https://experience.arcgis.com&arcgis-auth-portal=https://<myorg>.maps.arcgis.com

Diriger les utilisateurs vers la page de connexion d’une organisation

En général, lorsque les utilisateurs tentent d’accéder à une application Experience Builder privée sur ArcGIS Online, ils sont dirigés vers la page de connexion ArcGIS Online principale. Pour réorienter les utilisateurs vers la page de connexion de votre organisation, utilisez org suivi du nom court de votre organisation.

https://experience.arcgis.com/experience/<AppId>/?org=<yourorgshortname>

Vous avez un commentaire à formuler concernant cette rubrique ?