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) {
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) {
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) {
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) {
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' or '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. |
featureKey | string | ❌ | 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 widget from main site. These functions are exposed to window object.
js
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 widget4. 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 $ or ^ symbol.
js
window.addEventListener("message", (event) => {
if (event.data?.type === "CASH_TAG_CLICK") {
console.log(event.data.value); // print clicked cash tag
}
});