Skip to main content

InveroProvider Context Provider

The InveroProvider component serves as the foundation for the Invero SDK, providing the necessary context for the AI chat functionality throughout your application. It must wrap any component that needs access to the Invero AI features.

Basic usage​

import React from "react";
import { InveroProvider } from "@inveroai/react-sdk";

function App() {
  return (
    <InveroProvider
      integrationId="your-integration-id"
      callbacks={{
        askAI: {
          onQuerySubmit: (data) => {
            console.log("Question asked:", data.question);
          },
        },
      }}
    >
      <YourApplication />
    </InveroProvider>
  );
}

Props​

PropTypeRequiredDefaultDescription
integrationIdstringYes-Your Invero integration ID from the Invero platform.
userTrackingMode"fingerprint" | "cookie" | "none"No"cookie"Enable tracking to identify unique users.
callbacksCallbacksYes-Callback functions for tracking user interactions with the SDK.
botProtectionMechanism"recaptcha" | "hcaptcha"No"recaptcha"Choose which captcha provider to use for bot protection.
hasConsentForCaptchabooleanNotrueWhether the user has provided consent for captcha. Set to false if you need to obtain consent before enabling captcha.
customizationIdstringNo-The ID of a customization to apply to chat requests. When set, every query uses the specified customization's prompt overrides.
sourceGroupIDsIncludestring[]No-Array of source group IDs to limit the SDK's knowledge base. When set, the SDK only uses sources from the specified groups (plus any global sources). See source groups documentation for details.
conversationHistoryConversationHistoryOptionsNo-Options for saving completed conversations to the browser's localStorage, so they can be listed and reopened with the useConversationHistory hook. On by default. See Conversation history.
apiServiceInveroApiServiceNoDefault API ServiceOptional API service implementation for testing or custom networking. You can provide a custom implementation that follows the InveroApiService interface.

Integration ID​

The integrationId is a unique identifier for your Invero integration. To find your integration ID:

  1. Log in to your Invero platform
  2. Navigate to the "Integrations" section
  3. Select or create a widget integration
  4. Copy the Integration ID from the setup page
<InveroProvider
  integrationId="7d04c434-4090-4ebf-aeb3-8e90645a504d" // Your actual integration ID
  callbacks={{...}}
>
  <YourApplication />
</InveroProvider>

Source groups​

The sourceGroupIDsInclude prop allows you to limit the SDK to specific source groups:

<InveroProvider
  integrationId="your-integration-id"
  sourceGroupIDsInclude={["product-a-group", "version-2-group"]}
  callbacks={{...}}
>
  <YourApplication />
</InveroProvider>

When set, queries only use sources from the specified groups (plus any global sources). You can get the group IDs from the "Manage groups" page in the Invero platform.

Callbacks​

The callbacks prop allows you to track and respond to user interactions. The structure is:

interface Callbacks {
  askAI?: {
    onQuerySubmit?: (data: QuerySubmitPayload) => void;
    onAnswerGenerationCompleted?: (
      data: AnswerGenerationCompletedPayload,
    ) => void;
    onAnswerGenerationStop?: (data: AnswerGenerationStopPayload) => void;
    onConversationReset?: (data: ConversationResetPayload) => void;
    onFeedbackSubmit?: (data: FeedbackSubmitPayload) => void;
  };
}

Callback events​

EventTriggered whenPayload data
onQuerySubmitUser submits a questionQuestion text, thread ID, conversation history
onAnswerGenerationCompletedAI finishes generating an answerThread ID, question, answer, conversation history
onAnswerGenerationStopUser stops answer generation, or restoring a conversation cancels itThread ID, question, conversation history
onConversationResetUser resets the conversationThread ID, conversation history
onFeedbackSubmitUser submits feedbackReaction, comment, conversation details

Conversation history​

InveroProvider saves completed conversations to the browser's localStorage by default. Users can list and reopen them through the useConversationHistory hook, and follow-up questions continue the restored thread. Use the conversationHistory prop to change the defaults, or to turn history off:

<InveroProvider
  integrationId="your-integration-id"
  conversationHistory={{ enabled: false }}
>
  <App />
</InveroProvider>
OptionTypeDefaultDescription
enabledbooleantrueWhether completed conversations are saved.
storageKeystringinvero_conversation_history_<integrationId>The localStorage key the history is stored under. If you change it after mount, the conversation open at that moment is no longer saved under either key.
maxThreadsnumber50Maximum number of stored conversations. The oldest are dropped first.

Conversations are stored unencrypted in the browser and are never sent to Invero. Like all localStorage data, they are readable by JavaScript running on the page and persist until removed.

User tracking mode​

The userTrackingMode prop allows you to generate anonymous user identifiers:

<InveroProvider
  integrationId="your-integration-id"
  userTrackingMode="cookie"
  callbacks={{...}}
>
  <YourApplication />
</InveroProvider>

Possible values are:

  • cookie (default): uses a first-party cookie, see Anonymous user tracking for details.
  • fingerprint: the SDK uses browser and device characteristics to create a unique "fingerprint". Fingerprint tracking works across domains and can track users for longer under the same identifier. The FingerprintJS agent sets its own cookies for browser identification. Fingerprint tracking is powered by FingerprintJS Pro.
  • none disables user tracking entirely.

When enabled:

  • The SDK generates a unique visitor ID
  • This ID persists across sessions
  • No personal information is collected
  • This allows tracking conversations for users who aren't logged in

Bot protection​

The SDK uses captcha verification to protect against automated bots:

<InveroProvider
  integrationId="your-integration-id"
  botProtectionMechanism="hcaptcha" // "recaptcha" (default) or "hcaptcha"
  hasConsentForCaptcha={true}       // Set to false if you need explicit consent
  callbacks={{...}}
>
  <YourApplication />
</InveroProvider>

Google reCAPTCHA​

By default, the Google reCAPTCHA badge is visible when using reCAPTCHA. To hide the badge, follow Google's guidelines. Refer to the reCAPTCHA FAQ on hiding the badge.

hCaptcha​

If you use hCaptcha, include the following text and links to ensure you are in compliance with the online privacy laws:

This site is protected by hCaptcha and its
<a href="https://www.hcaptcha.com/privacy">Privacy Policy</a> and
<a href="https://www.hcaptcha.com/terms">Terms of Service</a> apply.

hCaptcha prohibits the use of localhost and 127.0.0.1 domains, typically used during local development. To develop and test with hCaptcha locally, run the development server on a fake domain name such as myapp.test. Refer to the hCaptcha documentation for more details.

If you need to obtain explicit user consent before enabling captcha:

function App() {
  const [captchaConsent, setCaptchaConsent] = useState(false);

  return (
    <>
      {!captchaConsent && (
        <div className="consent-banner">
          <p>We use CAPTCHA to protect our service from bots.</p>
          <button onClick={() => setCaptchaConsent(true)}>
            Accept
          </button>
        </div>
      )}

      <InveroProvider
        integrationId="your-integration-id"
        hasConsentForCaptcha={captchaConsent}
        callbacks={{...}}
      >
        <YourApplication />
      </InveroProvider>
    </>
  );
}

Custom API service​

For testing or special networking requirements, you can provide a custom API service:

import { InveroProvider, DefaultInveroApiService } from '@inveroai/react-sdk';

// Custom proxy URL
const customApiService = new DefaultInveroApiService('https://your-custom-proxy.example.com');

function App() {
  return (
    <InveroProvider
      integrationId="your-integration-id"
      callbacks={{...}}
      apiService={customApiService}
    >
      <YourApplication />
    </InveroProvider>
  );
}

For more complex customization, see the Custom API Services documentation.

User metadata​

You can provide user metadata by setting the global inveroSettings object:

// Set this before mounting the InveroProvider
window.inveroSettings = {
  user: {
    email: 'user@example.com',           // Optional: user's email
    uniqueClientId: 'user-123',          // Optional: your system's user ID
    metadata: {
      companyName: 'Acme Corp',          // Optional: company/org name
      firstName: 'Jane',                 // Optional: user's first name
      lastName: 'Doe'                    // Optional: user's last name
    }
  }
};

// Then render your provider
<InveroProvider integrationId="your-integration-id" callbacks={{...}}>
  <YourApplication />
</InveroProvider>

For dynamic user identification (e.g., after login):

function App() {
  const { user } = useAuth(); // Your auth hook

  useEffect(() => {
    if (user) {
      window.inveroSettings = {
        user: {
          email: user.email,
          uniqueClientId: user.id,
          metadata: {
            companyName: user.organization,
            firstName: user.firstName,
            lastName: user.lastName
          }
        }
      };
    } else {
      window.inveroSettings = { user: undefined };
    }
  }, [user]);

  return (
    <InveroProvider integrationId="your-integration-id" callbacks={{...}}>
      <YourApplication />
    </InveroProvider>
  );
}

Best practices​

  1. Place the provider as high as needed - but no higher. Only wrap components that need access to the Invero functionality.
  2. Initialize user data before mounting - Set window.inveroSettings before rendering the provider when possible.
  3. Handle authentication changes - When a user logs in or out, update the user identification accordingly.
  4. Use meaningful callback names - Name your callback handler functions descriptively for better code readability.
  5. Consider lazy loading - If the chat functionality isn't needed immediately, consider lazy loading it:
import React, { lazy, Suspense } from 'react';

const ChatWidget = lazy(() => import('./ChatWidget'));

function App() {
  const [showChat, setShowChat] = useState(false);

  return (
    <div>
      <button onClick={() => setShowChat(true)}>
        Open Chat
      </button>

      {showChat && (
        <Suspense fallback={<div>Loading chat...</div>}>
          <InveroProvider integrationId="your-integration-id" callbacks={{...}}>
            <ChatWidget />
          </InveroProvider>
        </Suspense>
      )}
    </div>
  );
}

Error handling​

The InveroProvider handles internal errors, but you should implement UI feedback for users when errors occur:

function ChatInterface() {
  const { error } = useChat();

  return (
    <div>
      {error && (
        <div className="error-message">
          <p>{error}</p>
          <p>Please try again or refresh the page.</p>
        </div>
      )}

      {/* Rest of chat interface */}
    </div>
  );
}

For more complex error handling, see the Troubleshooting guide.