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:

<script>
  const script = document.createElement("script");
  script.src = "https://publish.piqedge.com/assets/widget.js";
  script.async = true;
  script.onload = () => {
    if (window.initWidget) {
      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.

Examples:

  • 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) {
          window.initWidget({
            siteKey: 'YOUR_SITE_KEY',
            mode: 'embedded',
            targetId: 'widget-container',
          });
        }
      };
      document.head.appendChild(script);
    </script>
    <!-- Widget Script -->
  </body>
</html>
  • REACT
// 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:

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

  </body>
</html>

Demo:

2. Configuration Options

Option

Type

Required

Description

siteKey

string

✅

Your unique site key provided by PiQEdge

mode

'floating' | 'embedded'

✅

Determines how the widget is displayed

targetId

string

❌ (required only in embedded mode)

ID of the HTML element where the widget will be mounted

openSharedLinkOnWidget

boolean

❌ (default: false)

If enabled, article will open its shared link inside the widget. If disabled, the original article source link will open instead.

auth

boolean

❌ (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.

ad

boolean

❌ (default: true)

Toggles the display of advertisements configured from the admin panel. Set to false to run the widget without ads.

3. Widget External Functions

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

  window.widget_setTheme(value); // toggles widget theme, value can be 'dark' or 'light'
  window.widget_gotoHome(); // go to home page of widget
  window.widget_openBookMark(); // opens bookmark page
  window.widget_close(); // close widget on floating mode
  window.widget_getAudioAlertState(); // return current audio alert state (true/false)
  window.widget_setAudioAlertState(value); // set audio alert state, value can be true or false
  window.widget_setSearch(value); // set search value on widget

4. Widget Events

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

  • CASH tag clicked:

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

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