Widget Setup

When you create a widget, you will be provided with an HTML snippet on the right side of the widget config page.

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 according to your configuration.

For example, if you wish to add the Announcekit badge in some place in your page, simply add an html element such as:

  <div class="announcekit-widget"></div>

This element can be a div, span or whatever you wish basically.

Having this element in place, insert the Announcekit widget code provided to you in your Widget configuration page.
Note that the widget code contains a placeholder: YOUR_ELEMENT_SELECTOR. You need to set this selector to target the element you created before.

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.app/widget/Bt3aw",
      "selector": ".announcekit-widget"
    })
  </script>
  <script async src="https://cdn.announcekit.app/widget.js"></script>

The "selector": ".announcekit-widget" ensures that this code will find the element with announcekit-widget class and insert the badge into that element.

Widget API

The Announcekit widget code creates a global valiable 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, this is provided by our widget code and should not be changed
  widget: "https://announcekit.app/widget/Bt3aw",
  // Target element selector for the widget interactive part.
  // For badge based widgets this is where the badge is placed.
  // For line and embed based widgets this is where the widget content gets injected.
  // Not needed when you want to control the widget yourself
  selector: ".announcekit-widget",
  // Optional: Only applicible for the embed type widget. This must be provided for embeds to work correctly.
  embed: true,
  // Optional: If you wish to access the widget object yourself, you can provide a name for the widget
  // After loading completes, you can access the widget using `announcekit.widget$somename`
  name: "somename",
  // Optional: User and Segment data
  data: {
    user_id: "<USER ID>",
    user_email: "user@example.com",
    user_name: "John Doe",
    some_field: "Some Value"
  }
})

Each push call creates a widget and handles the setup. If you access the widget object, using announcekit.widget$somename you can call open and close methods to manually control the widget;

// Open the widget manually
announcekit.widget$somename.open();

// Close it manually
announcekit.widget$somename.close();

Events:

The global announcekit object provides several events in order to listen to changes.

announcekit.on("init", function() {
  // Called when the announcekit code loads. Before the widgets are loaded.
})

announcekit.on("widget-init", function(widget) {
  // Called for each widget after the widget has been successfully loaded.
  // Widget  object is passed to the handler.

  widget.open();
  widget.close();
})

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 specified widget has been updated
})

Overriding Default Styles:

The badge and line style widgets insert a trigger into your page. In case of badge, this is a circular counter, displaying the number of unread posts.
These elements have default styles attached to the style element so CSS definitions on your page are overriden. However if you wish to change the default style, you can pass a config option as:

announcekit.push({
  // Standard config
  widget: "https://announcekit.app/widget/Bt3aw",
  selector: ".announcekit-widget",

  // Style config for badge:
  badge: {
    style: {
      padding: "10px",
      borderRadius: "0"
    }
  }
})

The style object gets merged to the elements style property so you can use any css style property here. For the line type widgets, simply replace badge with line.

User Tracking & Sync

Announcekit can track your own users and report back to you their activities on your dashboard. We also ensure that your users do not see the same notifications even if they are using multiple browsers / computers etc.

For this to work, you need to provide a unique user identifier in your widget embed code. This ID is expected to be a string and it should always be the same for the same user.

announcekit.push({
  widget: "https://announcekit.app/widget/Bt3aw",
  selector: ".announcekit-widget",
  data: {
    user_id: "121212",
    // Optional additional fields
    user_email: "user@example.com",
    user_name: "John Doe",
  }
})

When the user_id parameter is present, we’ll handle the remaining. As listed on the sample, we encourage you to also provide user_email and user_name fields so you can receive more usable reports from your users’ activities.

Segmentation

In addition to tracking users with their IDs, emails and names, you can also provide custom data for segmentation.

Simply provide any additional data you wish to segment on within the data object. For example, if you wish to differentiate your paid members and show different posts to them, you can simply designate a property for this variable:

announcekit.push({
  widget: "https://announcekit.app/widget/Bt3aw",
  selector: ".announcekit-widget",
  data: {
    user_id: "121212",
    member_type: "paid"
  }
})

Having this code on your site, now you can create posts with filters on member_type field.