IHA Integration Framework

Tips & Tricks

Enabling IHA Mode

In the index.html at the bottom of the page there is a <script> tag. Add data-mode="iha".

Query String & Command Line Parameters

For convenience, there are a few command line parameters that can be used to change certain properties instead of needing to create multiple projects for minor changes. These parameters are set using a BAT file to load the PRSONAS_VIWER.EXE. Add a space, then add parameterID=value. NOTE: These parameters also work with query strings if you are developing ouside of the viewer for testing. Priority will be JSON configuration -> query string -> command line.

The following are framework only options that can be set:

  • map_prsonas_loc_id=XXXXX - This query string will override the starting location used in MappedIn directions.

Knowledge Base & MappedIn

The Knowledge Base is used to interpret spoken word into something useful which returns an answer or a response. We use metadata to help communicate to the UX what to do with that response. If no metadata is returned then the UX will simply speak the answer returned. The intent used for the speech is the question replacing spaces with underscores and removing special characters.

In addition to the DXP handling there is one specifically used in IHA for use with MappedIn. The sytax is action_ux=location_locationID. When this metadata is used then the UX knows that this response is referring to a location in MappedIn. When this is returned in a response, MappedIn will automatically navigate to the location. If the answer in the response is not empty then the answer is what is spoken. If the answer in the response is empty then the response is taken from project.json map.mappedin.avatarSpeech.

avatarSpeech has 2 nodes, direction and location. The value is the string that will be spoken under those conditions. Using [LOCATION_NAME] in the string will be replaced with the name of the location in question. This works in both pulling up a location and also in the destination for directions.

Examples:

"avatarSpeech": {
	"directions": "You can find directions to the [LOCATION_NAME] below. Scan the QRCode on the screen below to transfer to your mobile phone. Anything else I can help you find?",

	"location": "You have selected the [LOCATION_NAME]. Click the Directions button to get full turn by turn instructions to that location."
}

Sign Language

Currently, we do not support genAI for sign language. By default, when clicking or speaking directions or locations, generic intent responses are designated to be called when using sign language. These generic intents are set in the project.json map.avatarSpeech.signLanguageIntents. The defaults are:

"signLanguageIntents": {
	"directions": "genericdirections",
	"location": "genericlocation"
}

The languages that will use these responses are set in the project.json services.genaiFallbackToIntents. The defaults are:

"genaiFallbackToIntents": [
	"_ASL",
	"_BSL"
]

Implementing Mapping iFrame Web Application

The DXP installer includes iFrame_WebApp. This is the HTML for hosting the MappedIn enabled experiences.

The web app is the interactive map that is displayed in the experience. A webserver must be set up to host it. Upload the content of the iFrame_WebApp folder. Then in the project.json map.mappedin.config.url you will place the url to the web app. You will need to add the query string "?venue=" to the end of it.

Example of the AI Concierge web app URL:
https://app-webmaps-prod-central-001-a7hucnfpctfjercg.centralus-01.azurewebsites.net/iframe/index.html?venue=

Implementing MappedIn

In order to enable MappedIn, in addition to hosting the web application, you must make sure IHA is enabled. This is done in the index.html file. Add to the <script> at the bottom of the page data-mode = "iha". In the same file there are a number for commented out mark up that need to be enabled.

Uncomment the following:

  • In the <head> uncomment the loading <script> for mappedin.js.
  • The <div> sdkMapContainer.
  • The <div> iha-mappedin-container.

The project.json map node will need to be configured.

Implementing A Back Button

The back button is triggered by the event EVENT_PAGE_BACK_BTN. For the back button to work properly the EVENT_PAGE_HOME_BTN must be defined even if the home button is not going to be used. See Implementing A Home or Main Menu Button on how to set that up.

A page is considered any module using the event prefixed with EVENT_PAGE. When you click the back button it will call the last page event appending _STOP_ANIM. For example: If the previous page was EVENT_PAGE_FAQ, and you clicked the back button, EVENT_PAGE_FAQ_STOP_ANIM will be called.

Make sure that for your pages that the back button may link to that sendKeyEvents includes the _STOP_ANIM page event and proxySendkeyEvents includes the pages with _STOP_ANIM.

So in the example used, in the sendKeyEvents you will have:

"EVENT_PAGE_FAQ": "faq",
"EVENT_PAGE_FAQ_STOP_ANIM": ""

Then in proxySendkeyEvents you will have :

"EVENT_PAGE_FAQ_STOP_ANIM": "EVENT_PAGE_FAQ".

The reason for doing this is because if you go back to a page you may not want the avatar to speak or you may want to change the narrative.

Implementing A Home or Main Menu Button

The home button is triggered by the event EVENT_PAGE_HOME_BTN. This button resets the back button page event stack.

Make sure that you link the EVENT_PAGE_HOME_BTN to the main menu or home page event. If we use the example that your home page is EVENT_PAGE_MAIN_MENU you will need to implement the following:

In the sendKeyEvents you will have something like:

"EVENT_PAGE_MAIN_MENU": "mainmenu",
"EVENT_PAGE_HOME_BTN": ""

Then in proxySendkeyEvents you will have :

"EVENT_PAGE_HOME_BTN": "EVENT_PAGE_MAIN_MENU".