Skip to main content

Integration

Overview​

The <ai12z-cta> Search/Ask web component allows seamless integration of AI-powered search capabilities into your HTML pages. This component is loaded from a Content Delivery Network (CDN) and can be customized through a variety of properties.

The Search Web component, that loads from the CDN using the ai12z search web component

Setup​

Insert the following script and stylesheet in the head section of your HTML:

<script
  type="module"
  src="https://cdn.ai12z.net/pkg/ai12z@latest/dist/esm/library.js"
></script>
<link
  rel="stylesheet"
  href="https://cdn.ai12z.net/pkg/ai12z@latest/dist/library/library.css"
/>

Add the Component
You can insert the <ai12z-cta> into your HTML. This tag supports customization via the dialog agent->controls->ai12z-cta search

Example HTML page​

<html>
  <head>
    <script
      type="module"
      src="https://cdn.ai12z.net/pkg/ai12z@latest/dist/esm/library.js"
    ></script>
    <link
      rel="stylesheet"
      href="https://cdn.ai12z.net/pkg/ai12z@latest/dist/library/library.css"
    />
  </head>
  <body>
    <div>
      <ai12z-cta data-key="your_api_key_here"></ai12z-cta>
    </div>
  </body>
</html>

data-key​

Locate the data-key in agent->agent settings , It's the API key

The api key

note

Add config-id, if you have more than one config for ai12z-cta, under agent->controls->ai12z-cta search. You can have more than one config, if no config-id, it uses the default config

Control Attributes​

  • The control contains following properties to customize the page.
PropertyDescriptionExampleDefault
data-key (Required)API key from your ai12z Agent settingsdata-key="123456"
config-id (Optional)Load the settings based on config id.config-id="1234567891"

The below image will contains the config id.

alt text

To include a privacy policy link, use the <privacy> tag with a custom slot within the <ai12z-cta> element:

<ai12z-cta data-key="your_api_key_here">
  <div slot="custom-privacy">
    Privacy Statement
    <a href="https://ai12z.com/privacy-policy/" target="_blank"
      >Click to view</a
    >
  </div>
</ai12z-cta>

CTA (Optional)​

If cta tag exists the standard search control will be replaced with the html in the cta tag

<ai12z-cta data-key="your_api_key_here" heading="">
  <div slot="cta">
    <img
      style="width: 20px; cursor: pointer"
      src="https://cdn.ai12z.net/assets/web/magnifying-glass-solid.svg"
      alt="Search"
    />
  </div>
</ai12z-cta>

Passing attributes and tags​

Attributes​

Developer can pass a dictionary of additional data that can be used in prompts if you include the attribute tag in Answer AI.

IncludeTags​

Array of tags, only content with one of these tags will be returned.

ExcludeTags​

Array of tags,content will be excluded if it has one of these tags.

Example for passing the attributes,excludeTags and includeTags​

        document.addEventListener("DOMContentLoaded", function () {
          const ele = document.querySelector("ai12z-cta")
          if (ele) {
            ele.excludeTags = ["blog"]
            ele.includeTags = []
            ele.dataAttributes = {
              content: {
                newlist: [
                  {
                    _uid: "BUY6Drn9e1",
                    component: "foo",
                    headline: "Foo",
                  },
                  {
                    _uid: "gJZoSLkfZV",
                    component: "bar",
                    title: "Bar",
                  },
                  {
                    _uid: "X1JAfdsZxy",
                    component: "foo",
                    headline: "Another headline",
                  },
                ],
              },
            }
          }
        })

Events​

The following events emitted by the component. You can subscribe to these events to execute custom logic in response to specific actions or state changes within the component.

1. errored​

Description:

Emitted when an error occurs within the component. This event provides error details that can be used for logging or displaying error messages to the user.

Usage Example:

// Assuming 'myComponent' is a reference to your component
myComponent.addEventListener("errored", (event) => {
  console.error("An error occurred:", event.detail)
})

Explanation:

  • Listener: Attach an event listener to the errored event.
  • Event Object: The callback function receives an event object.
  • Error Details: Access the error information via event.detail.

2. buttonClicked​

Description:

Emitted when a button within the component is clicked. Useful for triggering actions in response to user interactions.

Usage Example:

myComponent.addEventListener("buttonClicked", (event) => {
  console.log("Button was clicked:", event.detail)
  // You can access additional data from event.detail if provided
})

Explanation:

  • User Interaction: Respond to button clicks inside the component.
  • Custom Data: event.detail contains information about which button was clicked.

3. messageSent​

Description:

Emitted when the component sends a message. This can be used to track outgoing messages or to update the UI accordingly.

Usage Example:

myComponent.addEventListener("messageSent", (event) => {
  console.log("Message sent:", event.detail)
  // Update message list or notify other components
})

Explanation:

  • Messaging Logic: Useful in chat applications or components that handle communication.
  • Event Data: event.detail contains the message content or metadata.

4. messageReceived​

Description:

Emitted when the component receives a message. Allows you to handle incoming messages and update the interface or state.

Usage Example:

myComponent.addEventListener("messageReceived", (event) => {
  console.log("Message received:", event.detail)
  // Display the message or process it as needed
})

Explanation:

  • Incoming Messages: Essential for handling data received from external sources or services.
  • Processing Data: Utilize event.detail to access message content.

5. open​

Description:

Emitted when the component is opened. Ideal for setting up resources or initializing state when the component becomes active.

Usage Example:

myComponent.addEventListener("open", () => {
  console.log("Component has been opened.")
  // Initialize data or start animations
})

Explanation:

  • Lifecycle Event: Signifies that the component is ready for interaction.
  • Initialization: Perform setup tasks when the component opens.

6. close​

Description:

Emitted when the component is closed or destroyed. Use this event to perform cleanup tasks or save the component's state.

Usage Example:

myComponent.addEventListener("close", () => {
  console.log("Component has been closed.")
  // Save state or release resources
})

Explanation:

  • Cleanup: Ideal for removing event listeners or stopping timers.
  • Resource Management: Ensure there are no memory leaks by cleaning up.

Custom Methods​

Method NameDescriptionHow to use it
sendMessageThis method allows us to send a message programmatically. It accepts two parameters. Message (Required) – The first parameter must be a string containing the message to be sent to the server to be processed by the ai12z server the React LLM. Display Text (Optional) – The second parameter is optional and should be a string that specifies the display text for the message in the bot bubble. If the second parameter is not provided, the bot bubble will be use the first parameterconst ctaElement = document.querySelector("ai12z-cta"); ctaElement.sendMessage("What are the activities available","List all Activities")
sendJSONThis method allows us to send a JSON programmatically. It accepts two parameters. jsonData (Required) – The first parameter must be an object which will be sent to the server to be processed by a12z server React LLM. DisplayText(Required) – The second parameter should be a string that specifies the display text that the bot bubble will show.const ctaElement=document.querySelector("ai12z-cta");ctaElement.sendJSON({"firstname":"xxxx","lastname":"yyyy","dob":"zzzz"}, "Info submitted");

General Usage Notes​

  • Event Subscription: Use the addEventListener method to subscribe to events emitted by the component.
  • Event Object: The event listener callback receives an event object, which may contain additional data in event.detail.
  • Component Reference: Replace myComponent with the actual reference to your component instance.

Example: Subscribing to Multiple Events​

// Reference to your component
const myComponent = document.querySelector("my-component")

// onErrored
myComponent.addEventListener("errored", (event) => {
  console.error("Error:", event.detail)
})

// onButtonClicked
myComponent.addEventListener("buttonClicked", (event) => {
  console.log("Button clicked:", event.detail)
})

// onMessageSent
myComponent.addEventListener("messageSent", (event) => {
  console.log("Sent message:", event.detail)
})

// onMessageReceived
myComponent.addEventListener("messageReceived", (event) => {
  console.log("Received message:", event.detail)
})

// onOpen
myComponent.addEventListener("open", () => {
  console.log("Component opened")
})

// onClose
myComponent.addEventListener("close", () => {
  console.log("Component closed")
})

Tips for Handling Events​

  • Error Handling: Always check if event.detail exists to avoid undefined errors.
  • Asynchronous Operations: If you're performing asynchronous tasks within the event handlers, consider using async/await or .then() for Promises.
  • Unsubscribing Events: If necessary, remove event listeners using removeEventListener to prevent memory leaks.
// Removing an event listener
const onOpenHandler = () => {
  console.log("Component opened")
}

myComponent.addEventListener("open", onOpenHandler)

// Later in your code
myComponent.removeEventListener("open", onOpenHandler)

Conclusion​

By subscribing to these events, you can effectively interact with the component and respond to its internal actions. This enables a more dynamic and responsive user experience.