Appearance

PiQEdge Widget Integration Guide ​

Easily integrate the PiQEdge widget into your website or platform using a simple script tag. This guide covers Floating and Embedded modes with available configurations.

1. Installation ​

a. Embedded Mode ​

Add this script to your website:

html
<script>
  const script = document.createElement("script");
  script.src = "https://publish.piqedge.com/assets/widget.js";
  script.async = true;
  script.onload = () => {
    if (window.initWidget) {
      const widgetId = window.initWidget({
        siteKey: "YOUR_SITE_KEY",
        mode: "embedded",
        targetId: "widget-container",
      });
    }
  };
  document.head.appendChild(script);
</script>

Replace YOUR_SITE_KEY with your actual site key from the PiQEdge dashboard.

Example (HTML) ​

html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Widget Integration</title>
  </head>
  <body>
    <h1>
      This is a simple HTML page to demonstrate the integration of a widget.
    </h1>

    <!-- Widget Element -->
    <div id="widget-container" style="width: 460px; height: 700px"></div>
    <!-- Widget Element -->

    <!-- Widget Script -->
    <script>
      const script = document.createElement("script");
      script.src = "https://publish.piqedge.com/assets/widget.js";
      script.async = true;
      script.onload = () => {
        if (window.initWidget) {
          const widgetId = window.initWidget({
            siteKey: "YOUR_SITE_KEY",
            mode: "embedded",
            targetId: "widget-container",
          });
        }
      };
      document.head.appendChild(script);
    </script>
    <!-- Widget Script -->
  </body>
</html>

Example (React) ​

tsx
// PiQEdgeEmbeddedWidget.tsx
import { useEffect, useRef } from "react";

declare global {
  interface Window {
    initWidget: (config: {
      mode: string;
      siteKey: string;
      targetId: string;
    }) => void;
  }
}

const PiQEdgeEmbeddedWidget = () => {
  const scriptRef = useRef<HTMLScriptElement | null>(null);
  const isInitialized = useRef(false);

  useEffect(() => {
    if (isInitialized.current) return;

    const script = document.createElement("script");
    script.src = "https://publish.piqedge.com/assets/widget.js";
    script.async = true;
    scriptRef.current = script;
    document.body.appendChild(script);

    script.onload = () => {
      if (window.initWidget && !isInitialized.current) {
        isInitialized.current = true;
        window.initWidget({
          mode: "embedded",
          siteKey: "YOUR_SITE_KEY",
          targetId: "widget-container",
        });
      }
    };

    return () => {
      if (scriptRef.current && document.body.contains(scriptRef.current)) {
        document.body.removeChild(scriptRef.current);
      }
      isInitialized.current = false;
    };
  }, []);

  return (
    <div id="widget-container" style={{ height: "500px", width: "462px" }} />
  );
};

export default PiQEdgeEmbeddedWidget;

Demo:

b. Floating Mode ​

Add this script to your website:

html
<script>
  const script = document.createElement("script");
  script.src = "https://publish.piqedge.com/assets/widget.js";
  script.async = true;
  script.onload = () => {
    if (window.initWidget) {
      const widgetId = window.initWidget({
        siteKey: "YOUR_SITE_KEY",
        mode: "floating",
      });
    }
  };
  document.head.appendChild(script);
</script>

Replace YOUR_SITE_KEY with your actual site key from the PiQEdge dashboard.

Example (HTML) ​

html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Widget Integration</title>
  </head>
  <body style="background: #ccc">
    <h1>
      This is a simple HTML page to demonstrate the integration of a widget.
    </h1>

    <!-- Widget Script -->
    <script>
      const script = document.createElement("script");
      script.src = "https://publish.piqedge.com/assets/widget.js";
      script.async = true;
      script.onload = () => {
        if (window.initWidget) {
          const widgetId = window.initWidget({
            siteKey: "YOUR_SITE_KEY",
            mode: "floating",
          });
        }
      };
      document.head.appendChild(script);
    </script>
    <!-- Widget Script -->
  </body>
</html>

Demo:

2. Configuration Options ​

OptionTypeRequiredDescription
siteKeystring✅Your unique site key provided by PiQEdge
mode'floating' or 'embedded'✅Determines how the widget is displayed
targetIdstring❌ (required only in embedded mode)ID of the HTML element where the widget will be mounted
openSharedLinkOnWidgetboolean❌ (default: false)If enabled, article will open its shared link inside the widget. If disabled, the original article source link will open instead.
authboolean❌ (default: false)Enables user authentication within the widget. When set to true, user data is stored and can be loaded in future sessions, allowing personalized experiences.
adboolean❌ (default: true)Toggles the display of advertisements configured from the admin panel. Set to false to run the widget without ads.
featureKeystring❌Can be obtained from feature management of admin panel, which only enables the features allowed in admin.

3. Widget External Functions ​

Widget external functions are used to trigger actions inside the widget from the main site. These functions are exposed to the window object.

All external functions accept an optional widgetId as the last parameter. You can get widgetId from the initWidget(...) response. If widgetId is not provided, the first loaded widget is used.

js
window.widget_setTheme(value, widgetId); // toggles widget theme, value can be 'dark' or 'light'
window.widget_gotoHome(widgetId); // go to home page of widget
window.widget_openBookMark(widgetId); // opens bookmark page
window.widget_close(widgetId); // close widget on floating mode
window.widget_getAudioAlertState(widgetId); // return current audio alert state (true/false)
window.widget_setAudioAlertState(value, widgetId); // set audio alert state, value can be true or false
window.widget_setSearch(value, widgetId); // set search value on widget
window.widget_openLiveTV(widgetId); // opens live TV modal on widget
window.widget_useFeature(featureKey, widgetId); // use feature with given feature key which is enabled from admin panel

4. Widget Events ​

These events are emitted by the widget and can be handled in your site.

Widget loaded ​

Widget emit this event when widget is loaded and ready to use.

js
window.addEventListener("message", (event) => {
  if (event.data?.type === "INITIALIZE") {
    console.log("Widget is loaded and ready to use");
  }
});

Theme changed ​

Widget emit this event when user change widget theme.

js
window.addEventListener("message", (event) => {
  if (event.data?.type === "THEME_CHANGE") {
    console.log(event.data.value); // print current widget theme, value can be 'dark' or 'light'
  }
});

CASH tag clicked ​

Widget emit this event when user click any article tag which starts with $ or ^ symbol.

js
window.addEventListener("message", (event) => {
  if (event.data?.type === "CASH_TAG_CLICK") {
    console.log(event.data.value); // print clicked cash tag
  }
});

Last updated:

© 2026 PiQEdge Ltd. All rights reserved.