React

Integrating with Alan AI

To integrate a React app with Alan AI:

1. Add the Alan AI Web SDK to your app. You can do it in two ways:

   • With the npm package

   • In the browser library mode

   NPM package

   To install the Alan AI Web SDK with the npm package:

   1. In the Terminal, run the command:

      Terminal

      npm install @alan-ai/alan-sdk-web --save
      

   2. Import alanBtn to your React component:

      Client app

      import alanBtn from "@alan-ai/alan-sdk-web";
      

   Browser library mode

   To load the Alan AI Web SDK in the browser library mode, add the alan_lib.min.js library to the index.html file using the <script> tag:

   Client app

   <script type="text/javascript" src="https://studio.alan.app/web/lib/alan_lib.min.js"></script>
   

2. Add the Alan AI button to your React component:

   • React functional component

   • React class component

   Functional component

   Client app

   import React, { useEffect } from 'react';
   
   useEffect(() => {
     alanBtn({
       key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
       host: 'v1.alan.app',
       onCommand: (commandData) => {
         if (commandData.command === 'go:back') {
           // Call the client code that will react to the received command
         }
       }
     });
   }, []);
   

   If you want to access the component state (or props) inside the callbacks that are passed to the AlanButton, please remember that you may face the «stale closure» problem that occurs because of the closure. To avoid this problem, you may use refs to store your state as shown in the example below:

   Client app

   function useStateReference(value) {
     const ref = useRef(value);
     const [, forceRender] = useState(false);
   
     function updateState(newState) {
       if (!Object.is(ref.current, newState)) {
         ref.current = newState;
         forceRender(s => !s);
       }
     }
   
     return [ref, updateState];
   }
   
   function App() {
     const [count, setCount] = useStateReference({});
     useEffect(() => {
       alanBtn({
         key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
         host: 'v1.alan.app',
         onCommand: () => {
           console.info('Actual count value:', count.current);
         }
       });
     }, []);
   
     return (
       <div className="App">
       </div>
     );
   }
   

   With the code above, the count variable will hold the «actual» value.

   Class component

   Client app

   componentDidMount() {
     this.alanBtnInstance = alanBtn({
       key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
       host: 'v1.alan.app',
       onCommand: (commandData) => {
         if (commandData.command === 'go:back') {
           // Call the client code that will react to the received command
         }
       },
     });
   }
   

Note

Regularly update the @alan-ai/alan-sdk-web package your project depends on. To check if a newer version is available, run npm outdated. To update the alan package, run npm update @alan-ai/alan-sdk-web. For more details, see npm documentation.

Specifying the Alan AI button parameters

You can specify the following parameters for the Alan AI button added to your app:

textChat Properties

Name	Type	Description
closeDelay	number	Specifies the delay (in milliseconds) for the close animation when the chat is rendered in inline mode.
showBtnIfChatOpen	boolean	Determines whether the Alan button should be shown when the chat is open in inline mode.
openByDefault	boolean	Indicates whether the chat should be open or closed by default when rendered in inline mode.
onOpen	function	A callback function that is triggered when the chat interface is opened.
onClose	function	A callback function that is triggered when the chat interface is closed.
onMinimize	function	A callback function that is triggered when the chat interface is minimized.

Changing the Alan AI button position

By default, the Alan AI button is placed in the bottom right corner of the window. To change the Alan AI button position, you can use the following options for the alanBtn variable:

• left: sets the Alan AI button position from the left edge

• right: sets the Alan AI button position from the right edge

• top: sets the Alan AI button position from the top edge

• bottom: sets the Alan AI button position from the bottom edge

• zIndex: sets the z-order of the Alan AI button

Client app

alanBtn({
   key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
   bottom: '50px',
   left: '50px',
   zIndex: 10
});

Using client API methods

You can use the following client API methods in your React app:

• setVisualState()

• callProjectApi()

• playText()

• sendText()

• playCommand()

• activate()

• deactivate()

• isActive()

• remove()

• textChat.isAudioOutputEnabled()

• textChat.setAudioOutputEnabled()

• textChat.setFullScreenMode()

• textChat.open()

• textChat.close()

• textChat.minimize()

• textChat.clear()

• theme.setTheme(theme)

• theme.getTheme()

setVisualState()

Use the setVisualState() method to inform the AI Agentic Interface about the app’s visual context. For details, see setVisualState().

Client app

import alanBtn from '@alan-ai/alan-sdk-web';
import React, { useEffect, useRef } from 'react';

function App() {
  const alanBtnRef = useRef({}).current;
  useEffect(() => {
    alanBtnRef.btnInstance = alanBtn({
      key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
      host: 'v1.alan.app',
    });
  }, []);

  return (
    <div className="App">
      <button onClick={() => {
        alanBtnRef.btnInstance.setVisualState({ data: 'your data' });
      }}>Send visual state</button>
    </div>
  );
}

export default App;

callProjectApi()

Use the callProjectApi() method to send data from the client app to the dialog script and trigger activities without voice and text commands. For details, see callProjectApi().

Dialog script

projectAPI.setClientData = function(p, param, callback) {
  console.log(param);
};

Client app

import alanBtn from '@alan-ai/alan-sdk-web';
import React, { useEffect, useRef } from 'react';

function App() {
  const alanBtnRef = useRef({}).current;
  useEffect(() => {
    alanBtnRef.btnInstance = alanBtn({
      key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
      host: 'v1.alan.app',
    });
  }, []);

  return (
    <div className="App">
      <button onClick={() => {
        alanBtnRef.btnInstance.callProjectApi("setClientData", {value:"your data"}, function (error, result){
          // handle error and result here
        });
      }}>Call setClientData method</button>
    </div>
  );
}

export default App;

playText()

Use the playText() method to play specific text in the client app. For details, see playText().

Client app

import alanBtn from '@alan-ai/alan-sdk-web';
import React, { useEffect, useRef } from 'react';

function App() {
  const alanBtnRef = useRef({}).current;
  useEffect(() => {
    alanBtnRef.btnInstance = alanBtn({
      key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
      host: 'v1.alan.app',
    });
  }, []);

  return (
    <div className="App">
      <button onClick={() => {
        alanBtnRef.btnInstance.playText("Hi there, I am Alan");
      }}>Play text</button>
    </div>
  );
}

export default App;

sendText()

Use the sendText() method to send a text message to Alan AI as the user’s input. For details, see sendText().

Client app

import alanBtn from '@alan-ai/alan-sdk-web';
import React, { useEffect, useRef } from 'react';

function App() {
  const alanBtnRef = useRef({}).current;
  useEffect(() => {
    alanBtnRef.btnInstance = alanBtn({
      key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
      host: 'v1.alan.app',
    });
  }, []);

  return (
    <div className="App">
      <button onClick={() => {
        alanBtnRef.btnInstance.sendText("Hello Alan, can you help me?");
      }}>Play text</button>
    </div>
  );
}

export default App;

playCommand()

Use the playCommand() method to execute a specific command in the client app. For details, see playCommand().

Client app

import alanBtn from '@alan-ai/alan-sdk-web';
import React, { useEffect, useRef } from 'react';

function App() {
  const alanBtnRef = useRef({}).current;
  useEffect(() => {
    alanBtnRef.btnInstance = alanBtn({
      key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
      host: 'v1.alan.app',
      onCommand: (commandData) => {
        if (commandData.command === 'goBack') {
          // Call client code that will react to the received command
        }
      },
    });
  }, []);

  return (
    <div className="App">
      <button onClick={() => {
        alanBtnRef.btnInstance.playCommand({command: "goBack"});
      }}>Play command</button>
    </div>
  );
}

export default App;

activate()

Use the activate() method to activate the Alan AI button programmatically. For details, see activate().

Client app

import alanBtn from '@alan-ai/alan-sdk-web';
import React, { useEffect, useRef } from 'react';

function App() {
  const alanBtnRef = useRef({}).current;
  useEffect(() => {
    alanBtnRef.btnInstance = alanBtn({
      key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
      host: 'v1.alan.app',
    });
  }, []);

  return (
    <div className="App">
      <button onClick={() => {
        alanBtnRef.btnInstance.activate();
      }}>Activate the Alan AI button</button>
    </div>
  );
}

export default App;

deactivate()

Use the deactivate() method to deactivate the Alan AI button programmatically. For details, see deactivate().

Client app

import alanBtn from '@alan-ai/alan-sdk-web';
import React, { useEffect, useRef } from 'react';

function App() {
  const alanBtnRef = useRef({}).current;
  useEffect(() => {
    alanBtnRef.btnInstance = alanBtn({
      key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
      host: 'v1.alan.app',
    });
  }, []);

  return (
    <div className="App">
      <button onClick={() => {
        alanBtnRef.btnInstance.deactivate();
      }}>Deactivate the Alan AI button</button>
    </div>
  );
}

export default App;

isActive()

Use the isActive() method to check the Alan AI button state: active or not. For details, see isActive().

Client app

import alanBtn from '@alan-ai/alan-sdk-web';
import React, { useEffect, useRef } from 'react';

function App() {
  const alanBtnRef = useRef({}).current;
  useEffect(() => {
    alanBtnRef.btnInstance = alanBtn({
      key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
      host: 'v1.alan.app',
    });
  }, []);

  return (
    <div className="App">
      <button onClick={() => {
        console.log('Button is active: ' + alanBtnRef.btnInstance.isActive());
      }}>Check the button state</button>
    </div>
  );
}

export default App;

remove()

Use the remove() method to remove the Alan AI button from the parent element. For details, see remove().

Client app

import alanBtn from '@alan-ai/alan-sdk-web';
import React, { useEffect, useRef } from 'react';

function App() {
  const alanBtnRef = useRef({}).current;
  useEffect(() => {
    alanBtnRef.btnInstance = alanBtn({
      key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
      host: 'v1.alan.app',
    });
  }, []);

  return (
    <div className="App">
      <button onClick={() => {
        alanBtnRef.btnInstance.remove();
      }}>Remove the Alan AI button</button>
    </div>
  );
}

export default App;

textChat.isAudioOutputEnabled()

Use the textChat.isAudioOutputEnabled() method to get the state of audio output for the Alan AI Chat. For details, see textChat.isAudioOutputEnabled().

Client app

alanBtnInstance.textChat.isAudioOutputEnabled()

textChat.setAudioOutputEnabled()

Use the textChat.setAudioOutputEnabled() method to enable or disable audio output for the Alan AI Chat. For details, see textChat.setAudioOutputEnabled().

Client app

alanBtnInstance.textChat.setAudioOutputEnabled(true)

textChat.setFullScreenMode()

Use the textChat.setFullScreenMode() method allows switching the Alan AI Chat interface between full-screen and normal view. For details, see textChat.setFullScreenMode().

Client app

alanBtnInstance.textChat.setFullScreenMode(true);

textChat.open()

Use the textChat.open() method to open the Alan AI Chat interface. For details, see textChat.open().

Client app

alanBtnInstance.textChat.open(); // Opens the Alan AI Chat interface

textChat.close()

Use the textChat.close() method to close the Alan AI Chat interface. For details, see textChat.close().

Client app

alanBtnInstance.textChat.close(); // Closes the Alan AI Chat interface

textChat.minimize()

Use the textChat.minimize() method to minimize the Alan AI Chat interface. For details, see textChat.minimize().

Client app

alanBtnInstance.textChat.minimize(); // Minimizes the Alan AI Chat interface

textChat.clear()

Use the textChat.clear() method to clear the Alan AI Chat interface. For details, see textChat.clear().

Client app

alanBtnInstance.textChat.clear(); // Clears the chat history in the Alan AI Chat interface

theme.setTheme(theme)

Use the theme.setTheme(theme) method to set the Alan AI Chat interface theme to either light and dark. For details, see theme.setTheme(theme).

Client app

alanBtnInstance.theme.setTheme('light');

theme.getTheme()

Use the theme.getTheme() method to retrieve the current theme of the Alan AI Chat interface. For details, see theme.getTheme().

Client app

alanBtnInstance.theme.getTheme(); // returns 'light' or 'dark'

Using handlers

You can use the following Alan AI handlers in your React app:

• onCommand handler

• onButtonState handler

• onConnectionStatus handler

• onEvent handler

onCommand handler

Use the onCommand handler to handle commands sent from the dialog script. For details, see onCommand handler.

Client app

alanBtn({
  key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
  host: 'v1.alan.app',
  onCommand: (commandData) => {
    if (commandData.command === 'go:back') {
      // Call client code that will react to the received command
    }
  },
});

onButtonState handler

Use the onButtonState handler to capture and handle the Alan AI button state changes. For details, see onButtonState handler.

Client app

alanBtn({
  key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
  host: 'v1.alan.app',
  onButtonState: function (e) {
    console.info('onButtonState', e);
  },
});

onConnectionStatus handler

Use the onConnectionStatus handler to capture and handle the connection status for the AI Agentic Interface project. For details, see onConnectionStatus handler.

Client app

alanBtn({
  key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
  host: 'v1.alan.app',
  onConnectionStatus: function(status) {
    console.log("The status is " + status);
  },
});

onEvent handler

Use the onEvent handler to capture and handle events emitted by Alan AI: get user’s utterances, AI Agentic Interface responses and so on. For details, see onEvent handler.

Client app

alanBtn({
  key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
  host: 'v1.alan.app',
  onEvent: function (e) {
    console.info('onEvent', e);
  },
});

textChat parameter

Use the textChat to provide additional configuration options and handlers for managing the Alan AI Chat interface in “inlined” mode. For details, see textChat parameter.

What’s next?

Example apps

Find and explore examples of AI Agentic Interfaces in Alan AI GitHub.