Skip to main content

Interactions with Retorik Framework

Some data / functionalities are exported in order to be usable from a Reactjs application, or are link to the variable window for a vanillajs use.
N.B. : as using a Reactjs application is the prime goal, the interaction are more numerous in that case.

List of exports from Retorik Framework
exports from package
  export {
    RetorikAgent,                     // main component
    RetorikWidget,                    // main component (widget version)
    RetorikNews,                      // main component (informations channel only)
    renderAgent,
    addDetailedAttachmentTrigger,     // add a custom rendering component when a specific action occurs
    addExternalActivityHandler,       // method replacing 'externalEventHandler'. Adds a handler typed (action: any) => boolean for each activity using the directline channel
    cancelCurrentUtterance,           // (since v3.0.1) method to forcibly stop the current speech synthesis
    characters,                       // available characters
    closeWidget,                      // (component RetorikWidget) call widget closing
    fetchAvailableLanguages,          // retrieve allowed languages
    getRetorikConfigs,                // retrieve configuration data from Retorik Studio
    getThemeColors,                   // retrieve application's color data
    hideAgent,                        // hide the agent
    openWidget,                       // (component RetorikWidget) call widget opening
    pauseConversation,                // (since v3.0.1) method to pause directline activity. No incoming / outgoing activity will be processed
    playExternalSynthesis,            // (since v3.0.1) method to speak a text using the specch synthesis system inside the application
    presets,                          // positionning data when using a 3D character
    resumeConversation,               // (since v3.0.1) method to unpause the directline after pausing it
    resetStores                       // Flush all content from zustand stores. This content persists even after main component unmounting.
    sendActivity,                     // (deprecated soince v3.2.6) send an activity with the directline channel
    sendEvent,                        // (since v3.0.1) method to send a message to the back-end with the directline channel
    sendMessage,                      // (since v3.0.1) method to send an event to the back-end with the directline channel
    sendMessageToChatbot,             // (since v3.0.1) method to send a message directly to the front-end without using the directline channel
    setCurrentCustomView,             // force rendering of a custom view
    setCurrentSubView,                // force rendering of a secondary custom view
    setDashboardOpened,               // (since v3.2.6) method to open / close the main menu
    setDisplaySubtitles,              // method to show / hide subtitles
    setLoaderClosed,                  // force loader page closing. Boolean (true -> page closed)
    setLocale,                        // set language, string formatted as <language>-<CULTURE> (ex : 'en-US', 'fr-FR')
    setModalFullscreenContent,        // set content to be displayed on the overlay page (cf pdf preview page).
    setMode,                          // change mode (vocal or text). Import enum { Mode } to get the possibilities
    setMuted,                         // (since v3.0.1) method mute / unmute the application
    setPrintingCallback,              // method called on 'print' button click (pdf preview page). Entry parameter is the URL of the document.
    setVisibility,                    // (since v3.0.1) method to show / hide the application
    showAgent,                        // show the agent
    toggleDisplay,                    // (component RetorikWidget) change component's size (if possible)
    toggleMicrophone,                 // (since v3.0.1) method to toggle the current status of the microphone (opened / closed)
    toggleSubtitles,                  // (since v3.0.1) method to toggle the current status of the subtitles (visible / hidden)
    toggleVisibility,                 // (since v3.0.1) method to toggle the current status of the application's visibility (visible / hidden)
    toggleWidget,                     // (component RetorikWidget) switch from one state to another (opened -> closed / closed -> opened)
    useConfiguration,                 // (since v3.0.1) hook to get the parameter 'configuration'
    useCurrentSubView,                // (since v3.0.1) hook to get the parameter 'currentSubView'
    useIsMobile,                      // (since v3.0.1) hook to get the parameter 'isMobile' (boolean : true = mobile ou widget device)
    useIsRTL,                         // (since v3.0.1) hook to get the parameter 'isRTL' (boolean : true = rtl language (right-to-left), ex : arabic, hebrew)
    useIsUsedOnBorne,                 // (since v3.0.1) hook to get the parameter 'isUsedOnBorne' (boolean : true = borne mode => no external link opening, urls changed in QRcodes)
    useIsWidget,                      // (since v3.0.1) hook to get the parameter 'isWidget' (boolean : true = widget mode)
    useKioskParameterOpening,         // (since v3.0.1) hook to get the parameter 'kioskParameterOpening'
    useLoaderClosed,                  // (since v3.0.1) hook to get the parameter 'loaderClosed'
    useLocale,                        // (since v3.0.1) hook to get the parameter 'locale' (string : currently selected language)
    useMode,                          // (since v3.0.1) hook to get the parameter 'mode' (vocal or text)
    useMuted,                         // (since v3.0.1) hook to get the parameter 'muted' (boolean : true = muted)
    useRetorikEvent,                  // (since v3.0.1) hook to get the parameter 'retorikevent'
    useThemeColors,                   // (since v3.0.1) hook to get the parameter 'themeColors' (application's color)
    useTranslation                    // (since v3.0.1) hook to get the parameter 'translation' (translation of the internal texts in the currently selected language)
  }

Displaying an external component / page​

Retorik Framework owns a window in which you can inject a react component, in order to display it as an overlay above the main application layer. For example, we use it to display pdf files before download/ printing. In order to use it, you must use the setModalFullscreenContent(component: JSX.Element | null): void method, taking either a React component to display or null (close window) as parameter.
This can also be used in vanillaJs since v3.2.5 by using window.Retorik.setModalFullscreenContent.

Example
import { setModalFullscreenContent } from '@davi-ai/retorik-framework';

const componentToRender: JSX.Element = (
  <div
    style={{
      width: '100%',
      height: '100%',
      display: 'flex',
      justifyContent: 'center',
      alignItems: 'center',
    }}
    onClick={() => setModalFullscreenContent(null)}
  >
    Component to render, close on click
  </div>
);

setModalFullscreenContent(componentToRender);

Using an external script to interact with the application (customCSS / customScripts)​

Since v3.2.5, the preferred method for using custom scripts / CSS is using the customScripts and customCSS options inside Retorik Studio. These scripts can use the methods exported on the window element to modify states inside the application. The scripts imported must be .js files, and are not imported as modules.

Exemple : adding an externalEventHandler
// Adding an externalEventHandler
const handler = (action) => {
  if (action.payload.activity.type === 'event') {
    console.log("this activity is of type 'event', let's cut the process with return = true");
    return true;
  }

  return false;
};

// Add the handler inside the application with the merhod window.Retorik.addExternalActivityHandler
window.Retorik.addExternalActivityHandler(handler);

Methods taking a reactJs component as parameter can also be used. For this, you need :

  • ReactJs to be imported (used the path to "node_modules/react/cjs/react.production.min.js" to prevent an error due to the absence of an environment variable)
  • the final .js file to contains the compiled code (raw code with ReactJs component can not work as the files are imported as )
Exemple : injecting a ReactJs component
import React from '../node_modules/react/cjs/react.production.min.js';

// ReactJs component that will be injected
const CustomComponent = ({ source }) => {
  const handleClick = () => {
    window.Retorik.setModalFullscreenContent(null);
  };

  return (
    <div
      style={{
        width: '100%',
        height: '100%',
        display: 'flex',
        flexDirection: 'column',
        gap: '1rem',
      }}
    >
      <div
        style={{
          height: '2rem',
          width: '100%',
          padding: '0px 1rem',
          display: 'flex',
          flexFlow: 'wrap',
          background: 'white',
          cursor: 'pointer',
          placeContent: 'center',
        }}
        onClick={handleClick}
      >
        {' '}
        CLOSE ✕{' '}
      </div>
      <iframe src={source} height="850" width="1100"></iframe>
    </div>
  );
};

const externalHandler = (action) => {
  if (action.payload?.activity?.name === 'hospitality.ShowContentItem' || action.payload?.activity?.name === 'hospitality.ShowPointOfInterest') {
    const url = action.payload.activity.value?.content?.Thing?.Url?.Url || 'https://davi.ai';
    // Use the method linked to window.Retorik to inject the component inside the application's modal window
    url && window.Retorik.setModalFullscreenContent(<CustomComponent source={url} />);

    return true;
  }

  return false;
};

window.Retorik.addExternalActivityHandler(externalHandler);