How to: Implement Headless Widget

External widgets are tools that enable you to display community content directly on your website. By integrating these widgets, you can showcase user-generated content, updates, and discussions, enhancing user engagement and creating a vibrant hub for community interaction.

Presentation and limitations

The new widget integration is based on the new headless mode built in the platform. This widget can only be used for channels accessible to visitors and only for these types of channels:

• Gallery
• Blog
• Product Pairing
• Routine

By default the posts are ordered following these criteria :

• Validated By Admin
• Number of likes
• Date (descending)

👉 The new widget is not compatible with the old one. Only one type can be used at the same time

Create a div

On the target page, create a div with an id like this :

<div id="toky_channel_1280"></div>

👉 You will find it in the channel url after the "channel/"
Example: for https://[communityname]/app/581/channel/1292 the channelId is 1292)

This is where the widget will be shown on the page, below some notes :

• It is important that the channel Id of the targeted channel is present, don’t forget to replace it with the one you want
• You need to set the width of this div as the content will adapt to it
• The height will computed on Brand Communities' side and should not be specified

Insert the JS tag

Add the following script where you want to display the widget (preferably at the end of the body):

(function() {
//insert custom product ID here if needed
var tokyChannelWidget = document.createElement('script');
tokyChannelWidget.type = 'text/javascript';
tokyChannelWidget.async = true;
tokyChannelWidget.src = 'https://community.mywebsite.com/channelwidget/1280/embed.js';
if(window && window.toky_customVars && window.toky_customVars.productId)
{tokyChannelWidget.src += '?productId=' + window.toky_customVars.productId;}
(document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0])
.appendChild(
tokyChannelWidget);
})();

👉It is important that the channel Id of the targeted channel is present, remember to replace it with the one you want, and to replace the community.mywebsite.com by the domain of your community

Filters and sorting (Optional)

Several filters, and sorting can be applied on the widget depending on what the client wants to show. 

Filters

As filter you can use : 

• `comments`:  to choose between posts with or without comments
  `0` showing all posts, with and withouth comments
  `1` showing only posts without comments
  `2` showing only posts with comments
  
  
• `validatedOnly` : to show only posts that have been validated by an admin
  `false` showing the non-validated posts only
  `true` showing the validated posts only
  
  
• `maxDays` : to choose only posts that have been created in the date range given
  The time has to be given as a number of days, has to be a number.
  
  
• `categoryId` : to show only the content of a category
  
  
• `productId` : to show only posts tagged with this product Id
  The productId must be the same than the one given in the products catalogue

Sorting

As sorting you can use : 

• `order` : to choose between most popular, most recent or validated posts
  `0` most recent posts first, chronological order
  `1`most popular posts first, the ones that have the most likes first
  `2` validated posts first, the ones that have been validated first, then the most popular ones, then the most recent ones.

Example:

window.toky_customVars = {
filters: {
comments: 0,
validatedOnly: true,
maxDays: 90,
categoryId: 3
},
order: 1,
productId: 'ABCD-1234'
}

Customization Options (Optional)

To customize the widget, go to:
AdminV2 > Settings > External widgets customization > Embed.JS

In here you can use Javascript to add some customizations to the widget

There can only be one customization per channel, but the customization can be different depending on the channel

• Widget size
  The widget height is customizable (sizes can be different on mobile/desktop)

window.tokyExternalWidgets.channel_1280.config.desktopWidth = '100%',
window.tokyExternalWidgets.channel_1280.config.desktopHeight = '500px',
window.tokyExternalWidgets.channel_1280.config.mobileWidth = '100%',
window.tokyExternalWidgets.channel_1280.config.mobileHeight = '500px',

• Popup size
  

  When clicking a post in the new widget a popup opens showing the details of the post

  The size of the popup can be edited, (sizes can be different on mobile/desktop)

window.tokyExternalWidgets.channel_1280.config.desktopPopupWidth = '852px',
window.tokyExternalWidgets.channel_1280.config.desktopPopupHeight = '70%',
window.tokyExternalWidgets.channel_1280.config.mobilePopupWidth = '100%',
window.tokyExternalWidgets.channel_1280.config.mobilePopupHeight = '100%',

• Interefere with the iframe creation
  You can perform some actions before, during and after the iframe creation and display using these javascript functions :

Before the iframe is created

window.tokyExternalWidgets.channel_1280.before = function(){
//add your code here
}

During the creation

window.tokyExternalWidgets.channel_1280.customize = function(){
//add your code here
}

After the creation

window.tokyExternalWidgets.channel_1280.after = function(){
//add your code here
}

Examples

You can see an exemple on https://community.mywebsite.com
👉Remember to replace community.mywebsite.com by your domain and the Id by the channel Id you want)

Routine - Cosmetics

Gallery - Cosmetics

Product Pairing - Fashion

Blog - DIY