Integration Guide

Learn about the SDK's display modes, DOM conventions, authentication mechanisms, and more advanced features.

Display Modes

Fullscreen Mode (Default)

User types in the landing page input → landing page fades out → AI fullscreen UI fades in. Ideal for tool-oriented landing pages (SEO content + AI feature entry point).

All App types support fullscreen mode.

Embedded Mode (Chatbot Only)

The SDK renders a mini chat window inside a specified DOM container. Ideal for embedding a conversation widget within a section of your page.

<!-- Place a container -->
<div id="my-chatbot" style="width:400px;height:500px;"></div>

<script src="https://sdk.usite.io/sdk.js"></script>
<script>
  SiteSDK.init({
    appId: 'your_app_id',
    appKey: 'your_app_key',
    mode: 'embedded',
    el: '#my-chatbot',
  });
</script>

Page DOM Conventions

In fullscreen mode, the SDK looks for the following DOM elements (IDs/selectors can be overridden via configuration):

Element	Default Selector	Purpose	Required
Input	`#heroInput`	Textarea where users type their prompt	Yes
Send Button	`#heroSend`	Button that triggers submission	Yes
Content Container	`#pageContent`	Landing page body, hidden in fullscreen mode	No
Example Chips	`.example-chip`	Clicks auto-fill and submit the data-q content	No
Login Area	`.usdk-login-bar`	SDK auto-renders Google sign-in button or avatar	No

Custom Selectors

If your page structure differs from the default selectors, you can override them via configuration:

SiteSDK.init({
  appId: 'your_app_id',
  appKey: 'your_app_key',

  // Custom selectors
  inputEl: '#my-input',          // Input field
  sendEl: '#my-send-btn',        // Send button
  contentEl: '#my-landing-page', // Landing page content
  exampleEls: '.my-example',     // Example chips
});

Example chips must have a data-q attribute:

<button class="my-example" data-q="Content to auto-send on click">Button text</button>

User Authentication (Google Sign-In)

If requireAuth is enabled in the dashboard, the SDK will automatically:

Disable the input field and display "Sign in with Google to start..."
Render a Google sign-in button in the .usdk-login-bar area
Enable the input field after the user signs in and display their avatar
Automatically prompt re-authentication when the token expires

Tip: You don't need to write any authentication code. Just place an empty <div class="usdk-login-bar"></div> in your page.

Quota & Billing

You can configure free usage limits when setting up your App in the dashboard:

Config	Description	Default
`no_login_quota`	Free requests for anonymous users	3 per day
`login_quota`	Free requests for signed-in users	20 per day
`quota_reset`	Reset interval	daily / weekly / monthly

The SDK handles quota logic automatically:

Quota exhausted + not signed in → shows "Sign in for more" + Google sign-in prompt
Quota exhausted + signed in → shows "Daily limit reached"
No billing_config set → unlimited usage

Async Tasks (Image/Video Generation)

When using the Kie.ai Provider, image and video generation are asynchronous. The SDK handles the entire workflow automatically:

SDK submits the task → card shows "Queued..."

SDK polls task status every 30 seconds → "In queue..." / "Generating..."

Task complete → displays the image or video player

Task failed → displays error message

You don't need to worry about polling logic -- the SDK handles everything automatically.

SDK Lifecycle

Page loads
  ↓
SiteSDK.init({ appId, appKey })
  ↓
POST /v1/init → Fetch site + app configuration
  ↓
Dynamically load sub-SDK based on app.type (chatbot.js / imagegen.js / videogen.js)
  ↓
Sub-SDK takes over DOM and binds events
  ↓
User interacts with input → Fullscreen UI expands → AI interaction

Error Handling

The SDK includes built-in automatic error handling -- you don't need to write any error handling code:

Scenario	SDK Behavior
Network disconnected	Auto-retries 2 times (exponential backoff), then shows "Network error"
Server 5xx	Auto-retries 2 times
Token expired	Shows "Session expired" and auto-opens Google sign-in window
Rate limited (429)	Shows "Too many requests. Please wait a moment"
Other errors	Shows "Something went wrong. Please try again"

Rate Limiting

SDK requests are automatically protected by IP-level rate limiting:

Endpoint	Limit
Chat	10 req/IP/min
Image	6 req/IP/min
Video	3 req/IP/min

Normal usage will not trigger rate limiting. When rate limited, the SDK shows a "Too many requests" message.

Important Notes

1. Place the SDK script before </body> — Ensures all DOM elements already exist

2. Only call init once per page — Do not call init multiple times for the same appId

3. Do not hide #heroInput and #heroSend — The SDK requires these elements to be visible

4. #pageContent must wrap all landing page content — This container is hidden during fullscreen mode transitions

5. Use HTTPS — HTTPS is required in production; Google sign-in will not work without it

6. No CORS issues — The SDK and API are CORS-configured and work on any domain