Embed Dashboard Widget into Your Website

Integrating a dashboard widget into your web application is straightforward; however, due to user authentication requirements, a session is necessary for interaction with the widget. This mechanism ensures only authorized users can access the widget.

Below is a step-by-step guide on how to embed the widget. Note that this process closely mirrors the chatbot embedding procedure.

How to find your widgetId: After selecting a specific widget, look at your browser’s URL. For example, if the URL is
/dashboard/analytic/1?widgetId=cf51c274-0a0e-45ff-b90d-3b8107e6d8cd&isEndpoint=false,
then your widgetId is cf51c274-0a0e-45ff-b90d-3b8107e6d8cd.

Step 1: Create a Session

First, you need to create a session from your backend by calling the following API:

curl --location 'https://www.askyourdatabase.com/api/widget/v2/session' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $API_KEY' \
--data-raw '{
    "widgetId": "${widgetId}",
    "name": "User Name",
    "email": "user@example.com",
    "properties": {
        "customField": "customValue"
    }
}'

Note: You can create or find your API key on the API Keys page.

The response will contain a single-use, time-limited URL:

{
    "url": "https://www.askyourdatabase.com/api/widget/auth/callback?code=abcdefg"
}

Step 2: Embed the Widget

Once you have this session URL, you can embed the widget as follows.

Next.js Example

Backend code (e.g. app/api/widget-session/route.ts):

import { NextRequest, NextResponse } from "next/server";
 
export async function POST(req: NextRequest) {
  const response = await fetch("https://www.askyourdatabase.com/api/widget/v2/session", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer $API_KEY"
    },
    body: JSON.stringify({
      widgetId: "${widgetId}",
      name: "User Name",
      email: "user@example.com",
      properties: {
        // add any custom properties here
      }
    })
  });
 
  const data = await response.json();
  return NextResponse.json({url: data.url});
}

Frontend code:

"use client";
import { useEffect, useState } from "react";
 
export default function WidgetContainer() {
  const [iframeUrl, setIframeUrl] = useState("");
 
  useEffect(() => {
    fetch("/api/widget-session", {
      method: "POST",
      headers: {
        "Content-Type": "application/json"
      }
    })
      .then((res) => res.json())
      .then(({ url }) => {
        setIframeUrl(url);
      });
  }, []);
 
  return (
    <iframe
      src={iframeUrl}
      style={{
        width: "100%",
        height: "600px",
        border: "none",
      }}
    />
  );
}

In this example, the front-end code calls an internal endpoint ("/api/widget-session"), which itself calls the AYD official session creation API. Once the back-end receives the session URL from AYD, it returns the URL to the front-end.

The front-end then uses this URL to load the widget in an iframe, ensuring your API key remains secure on the server side. This approach prevents any sensitive credentials from being exposed in client-side code while still allowing you to embed the widget seamlessly into your application.

Quick Start with Official Demo Repository

For a quick start, we provide an official demo repository at https://github.com/AskYourDatabase/nextjs-chatbot (opens in a new tab). You can quickly deploy your own instance by clicking the "Deploy to Vercel" button in the README. This will create a live site on Vercel where you can embed your chatbot or dashboard widget with minimal setup required.

Plain HTML/JavaScript Example

<div id="widget-container"></div>
<script>
async function loadWidget() {
  const response = await fetch('/api/widget-session', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    }
  });
 
  const { url } = await response.json();
  
  const iframe = document.createElement('iframe');
  iframe.src = url;
  iframe.style.width = '100%';
  iframe.style.height = '600px';
  iframe.style.border = 'none';
  
  document.getElementById('widget-container').appendChild(iframe);
}
 
loadWidget();
</script>

Security Considerations

1. Always keep your API key secure and never expose it in frontend code.
2. Implement proper user authentication before creating widget sessions.
3. The session URL is single-use and expires after a short period (e.g., 5 minutes).
4. Consider implementing rate limiting on your session creation endpoint to prevent abuse.