The LaunchNotes embed provides you with an additional channel to share announcement updates with your users. It allows you to easily integrate LaunchNotes notifications into any web app or relevant web property.
We currently offer two types of embedded applications; the Pop-up embed, and the inline embed. Both applications leverage the LaunchNotes public API.
💡 This article will cover the Pop-up Embed, for information on the Inline Embed,
visit the Inline Embed help article.
The pop-up
Pop-up embeds are a great way of showing product updates to your users within your app.
The pop-up embed is hidden by default and can be toggled by clicking an element in your application. When clicked, a list of your most recent Announcements will be shown.
When an announcement card is selected within the embed, the full announcement will show in a new, larger, window:
Unread Indicator
The pop-up embed supports an unread indicator. This takes the form of an icon or mark next to the toggle selector to indicate that there are unread updates on the widget. This will disappear once the widget is clicked and opened.
The second way the unread indicator works is by highlighting the individual announcements in the widget that have not been read -- these will have bolded text and a darkened background. This highlight will only disappear when the announcement itself is clicked into.
Installation
First, head to Settings on the Admin nav bar, then API & Embed, where you'll be able to create a new published API token. We recommend creating a specific API token for each place you intend implement the embed.
Next, add the following scripts in the head tag on your site:
<script type="module" async="" src="https://embed.launchnotes.io/latest/dist/esm/launchnotes-embed.js"></script>
<script nomodule="" async="" src="https://embed.launchnotes.io/latest/dist/esm/launchnotes-embed.js"></script>
With these scripts installed, you can now implement your pop-up embed wherever you'd like. Simply add the embed's HTML tag with the relevant properties, and you're ready to go!
<launchnotes-embed
token="public_fqe2Gasd1pUBFrPxVTtawYl9g5i"
project="pro_4flZZoOkasdtFBaP"
categories='["meta-slug", "another-cat-slug", "third-cat-slug"]'
toggle-selector="#whats-new-link"
heading="Hi there"
heading-color="#FFF"
subheading="The latest features, improvements, and bug fixes"
subheading-color="rgba(255, 255, 255, 0.8)"
primary-color="lightblue"
widget-placement="auto"
widget-offset-skidding="0"
widget-offset-distance="0"
show-unread
anonymous-user-id="YOUR_ANON_ID"
unread-placement="right-start"
unread-offset-skidding="-4"
unread-offset-distance="4"
unread-background-color="#0080ff"
unread-text-color="#ffffff"
widget-footer-html="<p style='color: #FF0000;'>My Custom <a href='example_url.com' rel='noopener' target='_blank'><strong>Link</strong></a></p>"
></launchnotes-embed>
💡 The Snippet example above has placeholders for some variables such as the API token, projectID, Categories, HTML and links.
Required properties
token
Your public API token
project
Your project ID - this can be found in the URL of your account admin, and will start with "pro_", for example:
Optional properties
categories
You can pass in the categories that you'd like different groups of users to see, by mapping these user types to the specific category slugs, which are then listed in a JSON array as shown in the snippet above.
Category slugs can be found under the Categories tab under your project Settings.
toggle-selector
A unique CSS selector targeting the link or button you want to use to show and hide the pop-up widget
❗ Do not place the launchnotes-embed element within the element you are using as your toggle-selector. It would only open the embed when clicked but obstruct the embed from being closed via the close-button.
heading
The title text. Use this to personalize the messaging for your users.
heading-color
The title text color.
subheading
The title sub-heading text.
subheading-color
The title sub-heading text color.
primary-color
The background color of the heading and subheading. This can be a hex, rgb, rgba color or a gradient.
widget-placement
Placement of the pop-up relative to the toggle selector. We use Popper to position the unread indicator and the supported values are auto (default), auto-start, auto-end, top, bottom, right, left, top-start, top-end, bottom-start, bottom-end, right-start, right-end, left-start, left-end.
widget-offset-skidding
An amount to offset the pop-up along the toggle selector. See the Popper docs for an explanation.
widget-offset-distance
An amount to offset the pop-up away from the toggle selector. See the Popper docs for an explanation.
show-unread
Set to true to show an unread indicator when you post new announcements. Defaults to false.
anonymous-user-id
A unique user identifier used to determine whether or not there is an unread announcement for the viewer. This property is required for the unread indicator to work. This can be something like the user's primary key ID, email address, or some other non-changing value. For additional security feel free to hash this value before sending.
unread-placement
Placement of the unread indicator relative to the toggle selector. We use Popper to position the unread indicator and the supported values are auto, auto-start, auto-end, top, bottom, right, left, top-start, top-end, bottom-start, bottom-end, right-start(default) , right-end, left-start, left-end.
unread-offset-skidding
An amount to offset the indicator along the toggle selector. See the Popper docs for an explanation.
unread-offset-distance
An amount to offset the indicator away from the toggle selector. See the Popper docs for an explanation.
unread-background-color
The background color of the unread indicator.
unread-text-color
The text color of the unread indicator.
widget-footer-html
(Optional) The footer text that appears above the 'Powered by LaunchNotes' watermark in the opened widget. This accepts HTML to customize text color, style, and add custom links.
With these scripts installed, you can now implement your pop-up embed wherever you'd like. Simply add the embed's HTML tag with the relevant properties, and you're ready to go! Ideally you should place the launchnotes-embed element adjacent or higher than your toggle-selector element (the element that triggers the embed opening).
Do not nest the embed element with the element you use to trigger the embed to show. This will result in blocking the widget from closing.
FAQ's
Self-hosting the widget
If there are requirements that you host the pop-up widget yourselves, this can be done by loading it via npm. Instructions for this can be found here: https://www.npmjs.com/package/@launchnotes/embed