Before we begin, you can click on the hyperlinks of the subtitles below to jump to their section.
Widget Setup
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 in some place on 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 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 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.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 this code will find the element with announcekit-widget class and insert the badge into that element.
Additional to element selector, you can pass HTML Object within the "selector" parameter.,
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.co/widgets/v2/31nbbO",
// Target element selector or HTMLElement object 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: In case you want to filter and display posts under a specific label or tag.
labels: ["new", "fix", "product_x"],
// Optional: JWT setup: https://announcekit.app/docs/jwt
user_token:"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXUyJ9.eyJpc3.AbIJTDMFc7yUa5MhvcP03nJP",
// Optional: User identification data. This is used for User Tracking purposes,
// mainly for calculating the unread counter.
// See User Tracking & Sync section below.
user: {
id: "<USER ID>",
email: "[email protected]",
name: "John Doe"
},
// Optional: User segmentation data.
data: {
some_segmentation_field: "Some Value",
member_type: "trial_user"
},
})
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);
// Subscribe email address announcekit.widget$somename.subscribeToProject("[email protected]");
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-ready", function({ widget }) {
// Called when the 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 specified widget has been updated
})
Boosters
You can also programmatically control the boosters. Before calling the methods, make sure that bar modal properties are defined. In case there are no announcements chosen for the boosters, bar modal properties will not be available.
announcekit.on("widget-init", function() {
// Show announcement bar booster
announcekit.boosters.bar.show()
// Hide announcement bar booster
announcekit.boosters.bar.hide()
// Show popup modal booster
announcekit.boosters.modal.show()
// Hide popup modal booster
announcekit.boosters.modal.hide()
})
Overriding Launcher Default Styles
The badge, 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 into the elements style property so you can use any css style property here.
announcekit.push({
// Standard config
widget: "https://announcekit.co/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"
}
}
})
Multiple Language Setup
AnnounceKit supports multiple languages. 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.
To choose a different language while setting up a widget, simply use the lang property:
announcekit.push({
// Standard config
widget: "https://announcekit.co/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 languages. In case there is no project language for this given browser language, we will simply fall back to your default language.
User Tracking & Sync and Segmentation Setup
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.co/widgets/v2/31nbbO",
selector: ".announcekit-widget",
user: {
id: "123456",
// Optional additional fields
email: "[email protected]",
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 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.co/widgets/v2/31nbbO",
selector: ".announcekit-widget",
user: {
id: "123456",
},
data: {
member_type: "trial_user"
}
})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 segmented posts.