AnnounceKit logo

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

  // 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: In case of a project with multiple languages, choose the language automatically
  // See the following section for further details
  lang: "auto",

  // Optional: In case you don't want to boosters appear on the page the widget is placed.
  boosters: false,

  // Optional: User and Segment data
  user: {
    id: "<USER ID>",
    email: "user@example.com",
    name: "John Doe"
  },

  data: {
    some_segmentation_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();

// Open the widget and scroll to the post
// You can get the POST_ID from your Dashboard->Post Edit link
// https://announcekit.app/dashboard/post/[POST_ID]/edit
announcekit.widget$somename.showPost(POST_ID);

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.

  //automatically display widget
  widget.open();

  //hide widget
  //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 Launcher Default Styles:
The bagde, float and line launchers have their own default styles. Basic styling options, like colors, can be changed from a widget settings page. If you need more customization (like changing launcher position or size) you can pass an object with CSS definitions in config options. The style object gets merged to the elements style property so you can use any css style property here.

announcekit.push({
  // Standard config
  widget: "https://announcekit.app/widgets/v2/31nbbO",
  selector: ".announcekit-widget",

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

  // Style config for float launcher:
  float: {
    style: {
      padding: "10px",
      position: "absolute",
      left: "10px",
      bottom: "10px"
    }
  }
})

Language Selection

AnnounceKit supports multiple languages. In order to use this feature you first need to add additional languages to your project on the project settings page.

Each project has a default language and any number of additional languages. By default, your widgets will load the content in this language.

In order to choose a different language while setting up a widget, simply use the lang property:

announcekit.push({
  // Standard config
  widget: "https://announcekit.app/widgets/v2/31nbbO",
  selector: ".announcekit-widget",

  // Choose fr language to show French posts and localize the widget in French
  lang: "fr"
})

In case you wish to choose the language automatically depending on the users browser language settings, you can use lang: "auto" instead of a specific language code. AnnounceKit will match the users browser language to the project langauges. In case there is no project language for this given browser language, we will simply fall back to your default language.

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/widgets/v2/31nbbO",
  selector: ".announcekit-widget",
  user: {
    id: "123456",
    // Optional additional fields
    email: "user@example.com",
    name: "John Doe",
  }
})

When the 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/widgets/v2/31nbbO",
  selector: ".announcekit-widget",
  user: {
    id: "123456",
  },
  data: {
    member_type: "paid"
  }
})

Having this code on your site, now you can create posts with filters on member_type field.
Make sure you have created member_type Segment Field before providing any data to it. Otherwise you can’t use that property to create a segmented posts.