Installation

@join-stories/widget-bubble-list package is also available through npm. To add JOIN Web SDK to your project using npm, please use one of the following methods:

npm install @join-stories/widget-bubble-list

pnpm install @join-stories/widget-bubble-list

Widget Bubble

📘

TeamId and widget alias

You will need your team id and the widgets' alias you want to integrate. You can find both of them in the Integration tab of your widget on studio.

To create a widget, check the documentation.

Integration in React

To successfully integrate @join-stories/widget-bubble-list into your webpage, follow these steps:

Step 1: Import renderBubbleList function

import { renderBubbleList } from "@join-stories/widget-bubble-list";

Step 2: Prepare Container of the widget

You have to create a <div> element that will serve as the container for the widget. Assign a unique id to this <div> to easily reference it later in your JavaScript code.

<div id="unique-div-id" />

Step 3: Initialize renderBubbleList

useEffect(() => {
  const destroy = renderBubbleList(
     "uniqueDivId",
     "teamId",
     "aliasWidget"
   );
  return () => {
      destroy(); // the destroy method allow you to unmount the widget
    }; 
  }, []);

Complete overview

Congratulations! By following the steps provided, you've successfully integrated the renderBubbleList widget into your web application. Your code should now look similar to the example below:

import { useEffect } from 'react';
import { renderBubbleList } from "@join-stories/widget-bubble-list";

const App = () => {
	useEffect(() => {
  	const destroy = renderBubbleList(
    	"unique-div-id",
    	"teamId",
    	"aliasWidget"
    );
  	
    return () => {
      destroy(); 
    }; 
  }, []);

	return <div id="uniqueDivId" />;
}

Integration in HTML & JS

<script type="module" src="./main.js"></script>
<div id="unique-div-dd">
</div>

import { renderBubbleList } from "@join-stories/widget-bubble-list";
renderBubbleList(
	"uniqueDivId",
	"teamId",
	"aliasWidget"
);

Prevent CLS

🚧

Content layout shift

When the widget is first displayed, it may cause Content layout shift. To avoid this, you may add custom CSS to reserve space on the page.

Join Stories generate the style automatically for standard widgets. You can get the generated style in the integration panel of your widget on Studio.

The style depends on the shape and size of your widget. For fully custom integration you may need to adapt these values.

Reference

Live Examples

To help you better understand how to integrate @join-stories/widget-bubble-list into your projects, we've prepared an example.

Basic integration

Analytics

You can listen to analytics events triggered by the widget like this:

function analyticsCallback(payload) {
  // Do something with the payload...
  console.log(payload.cpWidgetAlias)
}

renderBubbleList(
  "uniqueDivId",
  "teamId",
  "aliasWidget",
  { analyticsCallback },
);

See Analytics to learn more about available events.

Ads

If you have setup JOIN Ads, you set custom targeting using the method setCustomAdsTargeting like this:

import { setCustomAdsTargeting } from "@join-stories/widget-bubble-list";

setCustomAdsTargeting({
  program_id: "1234",
}, 'my-widget-alias');

For more details on Ads, see Ads.

For more details on custom targeting, see Set custom targeting.

Changelog

1.3.0 (Current version)

• 💫 Ads - You can now connect stories to your Ad Server (see Ads documentation)
• minor fixes

1.2.1

• minor fixes and improvements

1.2.0

• 💫 Analytics - new event listener (see NPM Package - Analytics).
• accessibility improvements.
• minor fixes.

1.1.0

• 💫 Shopping - Add to cart (see Add to cart : Plug stories add-to-cart to my website ).
• Optimizations on Data fetching.
• Improvements on Interactions animations.
• Various improvements on Audiences.
• Minor UI fixes.

1.0.6

• Reduced bundle size.
• optimized emoji images.

1.0.5

• Improvements on interactions, with new animations.

1.0.4

• 💫 Custom spacing between widget bubbles.
• Performances improvements on video player.

1.0.3

• Performances improvements on bubbles + video covers

1.0.1

• Minor fixes

1.0.0

• 💫 New implementation of Join Stories widget. More performances and reduced bundle size. Widgets are more flexibles, with new customizations options.