When you create a widget, you will be provided with a HTML snippet.
Please insert the snippet into your web pages right above the </body> tag.
The widget code requires a container element in your page. The container will be populated with the badge or link widget launcher according to your configuration.
For example, if you wish to add the AnnounceKit badge somewhere on your page, add an HTML element such as:
<div class="announcekit-widget"></div>
This element can be a div, span, or whatever you wish.
Having this element in place, insert the AnnounceKit widget code provided to you on your Widget implementation page.
Note that the widget code contains a placeholder: YOUR_ELEMENT_SELECTOR. You need to set this selector to target the element you created.
For example, given the div above, the widget code should be inserted like this:
<!-- AnnounceKit widget --><script> window.announcekit = (window.announcekit || { queue: [], push: function(x) { window.announcekit.queue.push(x); } }); window.announcekit.push({ "widget": "https://announcekit.co/widgets/v2/31nbbO", "selector": ".announcekit-widget" })</script><script async src="https://cdn.announcekit.app/widget-v2.js"></script>
The "selector": ".announcekit-widget" ensures that the code will find the element with the announcekit-widget class and insert the badge into that element.
Additionally, you can pass an HTML Object within the "selector" parameter.
Widget API
The AnnounceKit widget code creates a global variable named announcekit. This variable allows you to interact with the widgets on your website.
The most basic function is announcekit.push(widget_config). This call is provided to you in the widget embed code. The basic structure is as follows:
announcekit.push({ // The widget URL — provided by our widget code, do not change widget: "https://announcekit.co/widgets/v2/31nbbO", // Target element selector or HTMLElement for the widget launcher. // For badge widgets this is where the badge is placed. // For line and embed widgets this is where the content gets injected. // Not needed when you want to control the widget yourself. selector: ".announcekit-widget", // Optional: Only applicable for embed type widgets. embed: true, // Optional: Name for the widget object — access via announcekit.widget$somename name: "somename", // Optional: Set language automatically from browser settings lang: "auto", // Optional: Disable boosters on this page boosters: false, // Optional: Filter posts by label or tag labels: ["new", "fix", "product_x"], // Optional: JWT setup: https://announcekit.app/docs/jwt user_token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXUyJ9...", // Optional: User identification for tracking (see User Tracking article) user: { id: "<USER ID>", email: "[email protected]", name: "John Doe" }, // Optional: Segmentation data (see User Tracking & Segmentation article) data: { member_type: "trial_user" },})
Each push call creates a widget and handles setup. If you access the widget object via announcekit.widget$somename, you can call open and close methods to manually control the widget:
// Open the widget manuallyannouncekit.widget$somename.open();// Close it manuallyannouncekit.widget$somename.close();// Open the widget and scroll to a specific post// (get POST_ID from Dashboard → Post Edit URL)announcekit.widget$somename.showPost(POST_ID);// Subscribe an email addressannouncekit.widget$somename.subscribeToProject("[email protected]");
Events
The global announcekit object provides several events to listen to widget changes.
announcekit.on("init", function() { // Called when the announcekit code loads, before widgets are initialized.})announcekit.on("widget-init", function({ widget }) { // Called for each widget after it has been successfully loaded. widget.open(); // automatically display widget widget.close(); // hide widget})announcekit.on("widget-ready", function({ widget }) { // Called when widget posts are loaded and ready for interaction})announcekit.on("widget-open", function({ widget }) { // Called when the specified widget is opened})announcekit.on("widget-close", function({ widget }) { // Called when the specified widget is closed})announcekit.on("widget-resize", function({ widget, size }) { // Called when the specified widget is resized})announcekit.on("widget-unread", function({ widget, unread }) { // Called when unread post count of the specified widget is updated})
Boosters
You can also programmatically control boosters. Before calling the methods, make sure that bar and modal properties are defined. If no announcements are chosen for the boosters, these properties will not be available.
announcekit.on("widget-init", function() { announcekit.boosters.bar.show() // Show announcement bar booster announcekit.boosters.bar.hide() // Hide announcement bar booster announcekit.boosters.modal.show() // Show popup modal booster announcekit.boosters.modal.hide() // Hide popup modal booster})