[WIP] Popsell Metablog : Widget Integration Guidelines

Warning: This document is in work in progress state. Popsell is currently re-building its entire widgets architecture. Everything related in this document is subject to complete changes.

This document describes the integration process of the Popsell Metablog Widget. The Popsell Metablog Widget is intended to display content from Popsell on an external website, and enable some interactions.

Getting Started

Prerequisites

The Popsell Metablog Widget need some requirements to be able to be integrated:

1- A Popsell environment

If you don’t have a Popsell Environment yet, please contact the Popsell Team to obtain your custom environment : support@popsell.com

2- An API Key from Popsell to authenticate requests

In order to display ambassador’s posts, you must possess an API key to authenticate requests. If you don’t have an API key yet, or if your need to provide a list of public posts, a guest API key which include limited features is required.

3- Widget options enabled in your Popsell environment

The widget need the option “Enable external widgets” to be checked in your Popsell environment to be allowed to execute itself.

Make sure to fill the requirements before going to the next step. If you need assistance with the validation of the prerequisites, contact our tech team at the following address: tech@popsell.com

How it works

Our conviction is that your customers will drive your commerce in the future. Popsell is an innovative solution to engage your customers and employees with your brand, enabling to build a new C2C sales channel.

With Popsell, each customer becomes a new point of sale!

The Popsell Metablog Widget allows you to embed various contents created on a Popsell Platform, in a form of a collection of smart items. The widget is developed as a jQuery UI plugin or Vue.js plugin. No dependency management is required, and its installation remains simple.

It is possible to customize the widget by passing a list of options. (See options)

Installation

NPM is the only installation provided for now.

NPM

npm i --save @popsell/popsell-metablog

TEXT

Vue.js integration

If you own a Vue.js environment, you can simply import and use the <popsell-metablog /> component.

 <popsell-metablog
    :api-url="<your api url>"
    :api-key="<your api key>"
    mode="stack"
    :limit="8"
    :invite-meet-community="true"
    :display-load-more="false"
    :display-comments="true"
    :display-likes="true"
    :internal-behavior="true"
/>

HTML

jQuery integration // NEED CHECK UP

The Popsell Metablog Widget can also be used in along side with jQuery.

<div id="popsell-widget-posts-slider-view" style="margin: 15px;"></div>
<script src="https://code.jquery.com/jquery-3.4.1.min.js" integrity="sha256-CSXorXvZcTkaix6Yvo6HppcZGetbYMGWSFlBw8HfCJo=" crossorigin="anonymous"></script>
<script src="node_modules/@popsell/popsell-metablog/dist/popsell-metablog.js" type="text/javascript"></script>
<script type="text/javascript">
    $(function() {
        popsellChallengeView = $(document).popsellMetablog({
            mode: 'page',
            apiKey: "<your api key>",
            apiUrl: "<your api path>",
            // others options
        });
    });
</script>

HTML

Options

Option	Type & default value	Required	Description
`api-key`	String	Yes	Generate an API key in the Popsell Manager under “Configuration > API” menu
`api-url`	String default: `https://popsell.com/api/v4/`		By default, configured on global the Popsell API endpoint. This can be changed to specify another instance of the Popsell API or a specific domain.
`cell-width`	Number default: 300		Define the width in pixels of the metablog cells.
`ratio`	Number default: 3/4		Represent the radio (width / height) used to draw cells.
`mode`	String [slider, stack] default: slider		Display mode of the widget The slider mode is an horizontal fixed height display with a carousel. Stack mode is a masonry pattern
`display-likes`	Boolean default: false		Should the likes count be displayed
`display-comments`	Boolean default: true		Should the comments be displayed
`invite-meet-community`	Boolean default: false		Should the invite to join the community be displayed. This button is located on a post detail.
`limit`	Number default: 15		Limit the amount of posts loaded and displayed in batch.
`display-load-more`	Boolean default: false		Should the load more posts button be displayed Only in stack mode
`open-post-mode`	String [zoom, redirect] default: zoom		Define the action when opening a post from the Popsell Metablog Widget. The ‘zoom’ mode opens a modal box integrated in the page containing the post details. The ‘redirect’ mode redirect the user to a new page with the post detail, in accordance of `redirectUrlScheme`
`redirect-url-scheme`	String default: `https://brand.popsell.com/users/${userId}/post/${postId}`	Only if `open-post-mode=redirect`	This is used to build the redirect URL associated with a post detail. `${postId}` will be replace by the post id. `${userId}` will be replaced by the post’s author. Usage example : `https://ba111od.community/users/${userId}/post/${postId}`
`filters`	Object		Filter the results. Only one filter is intended to be used The filter needs to be written in this form: `{ // Uncomment the desired // filter and define // the desired ids // pointsOfSale: [13, 6], // products: [15234, 15516], // categories: [159, 153] }` JS Existing filters : `pointsOfSale` , `products`, `categories`
internal-behavior	Boolean default: false		Define the default CTA behavior. If setup to false, the button opens up the page in the same browser tab. If setup to true, the button opens up the page in a new tab.

Future improvements

Remove jQuery in favor of VanillaJS
Performances improvements