Integrating Aspectiva

Based on Artificial Intelligence and Natural Language Processing technologies, Aspectiva analyzes massive volumes of consumer opinions from across the web across any type of product or service. Turning them into comprehensive and valuable insights, Aspectiva significantly increases shopper engagement and conversion rates. Aspectiva’s solution can be integrated either by including pre-built UI components with HTML and  JavaScript, or by directly accessing the API.

UI Components Integration

Aspectiva’s integration on a hosting webpage is managed by including a URL as a JavaScript AMD module, and one or more HTML tags that serve as containers for the widgets. (A plain JavaScript snippet can be included instead in non-AMD environments.) Product pages are initialized with a product ID, and on category pages the widget containers set the product ID with an HTML data attribute. The JavaScript retrieves the relevant information from Aspectiva’s servers and presents it in an interactive, attractive, user-friendly and fully responsive format. All widgets are optimized for performance and efficiency, run asynchronously, and safely integrate without affecting other elements of the page.

Tip

Skinning and other customization options are available on all widgets for a smooth and seamless integration into your site. Before integration begins Aspectiva will provide you with a personalized widget URL that is pre-configured for your site.

Include the widget code once on any page where one or more of Aspectiva’s widgets will be added. In an AMD environment such as RequireJS, include and initialize the module either along with your other dependencies or by itself, and initialize it as follows:

require(['widget URL'], function(o) {
    o.init({
        // Include the product ID on product pages only.
        // On category pages it will be set later for each product.
        aspectiva_product_id: the product ID,
    });
});

If you are using plain JavaScript, use the following code snippet instead, anywhere in the head or body of the page.

// Include the product ID on product pages only.
// On category pages it will be set later for each product.
var aspectiva_product_id = the product ID;

(function() {
    var scr = document.createElement("script");
    scr.type = "text/javascript";
    scr.async = true;
    scr.src = 'widget URL';
    var s = document.getElementsByTagName('script')[0];
    s.parentNode.insertBefore(scr, s);
})();
AJAX Support

When you include the widget URL as described above, the module immediately looks for any HTML widget container tags in the page. If your site loads some or all of the HTML widget container tags dynamically, for example, after the user clicks a button to see more results, call the following method to tell the module that new containers have been added:

aspectiva.ui.findContainers('widget container class or ID');

Tip

aspectiva refers to the global variable window.aspectiva exported by the module.
Run this code only after the module has been included on the page.
Skins

All JavaScript widgets are available in a selection of skins that can be customized to your site’s colors and styles. When we initially configure your account we will work with you to customize your primary skin and any other skins you may need, and configure your account accordingly. All JavaScript widgets will then use your primary skin. A widget that needs to use one of the other skins can specify the data-skin attribute in its HTML container tag. Possible values for the data-skin attribute include white and dark, along with any other custom skins created for your account.

API Integration

Aspectiva offers a RESTful API that fully supports the data that appears in the UI components described below. Each component also describes how it can be integrated using the API directly. The complete API documentation is available here.

Product Feed Methods

To ensure that Aspectiva’s servers have the necessary product data to be presented on customers’ webpages, Aspectiva supports either an offline or dynamic workflow. Both workflows are based on the customer providing a universal product identifier. Supported identifiers include UPC, GTIN and EAN.

Offline Product Feed

In this workflow you will send a list of product identifiers to Aspectiva, which our servers will use to retrieve any missing data and ensure that it will be available for displaying. Once this process is complete, all products with available information will have displayable widgets and will be available through the API. When choosing this method, use a CSV or TSV formatted feed that contains a list of product identifiers with one product on each line. For the sake of the Product Recommendations feature, also include the product page URL associated with each identifier. An example for such a feed in CSV format is:

123456789012,SKU1,URL1
123456789013,SKU2,URL2
123456789014,SKU3,URL3
Dynamic Product Feed

In this workflow you do not need to send any lists to Aspectiva in advance. Instead, in a UI Components integration, the widgets will automatically notify Aspectiva’s servers of missing products. In an API integration you can POST to the Products endpoint to notify Aspectiva’s servers of missing products at any time, such as in response to a Products endpoint GET request that has no information or during your own offline process. Please contact us at support@aspectiva.com for more information on how to send API requests to Aspectiva to post notification of new products.

Tip

In a UI components integration, you can choose to initiate a batch loading of webpages just to trigger the dynamic process, or wait for calls to be made spontaneously by users.
UI Components

Aspectiva’s technology can be included in your site in the following ways:

Product Page Widget

The product page widget contains opinions gathered from across the web, analyzed and visualized, to provide your shoppers with at-a-glance product insights. The widget enables your visitors to find the best fit for their specific needs and confidently advance to checkout.

API Integration

API integration is supported primarily by the Products service, which provides the data for the total score and number of opinions, along with the aspects and their details. The included aspect search is supported by the Aspect Search Suggestions service to provide the search results, and the Examples service for the details associated with the selected aspect.

Widget Integration

Widget integration is available by including the following HTML tag at the desired location in the page:

 <div id="asp_container1"></div>

Optional attributes that can be added to the HTML tag include:

Name Description
data-product-id Used to set the product ID when integrating on a category page.
data-skin See skins.
data-title false (default) / true. Adds a stylized title section to the top of the widget that includes the product name and image
data-href Used along with data-title to make the product name a clickable link to this encoded URL
Product Recommendations

If a product does not rate highly for a specific aspect, Aspectiva’s recommendations engine suggests alternative products that are best for this aspect, thus addressing the customers’ concerns with choices tailored to what they deem important. This technology increases time on page and reduces bounce rates.

API Integration

API integration is supported by the Recommendations service which provides information for recommended products and associated aspects.

Widget Integration

Recommendations are built into our product page widget, so there is no further implementation required. The recommendation engine will then be triggered automatically when a negative aspect is expanded. To include URL parameters at the end of your product page links, include aspectiva_link_parameters as follows in the page’s JavaScript initialization code:

require(['widget URL'], function(o) {
    o.init({
        aspectiva_product_id: the product ID,
        aspectiva_link_parameters: {
            parameter1: value1,
            parameter2: value2,
        },
    });
});

For the plain JavaScript snippet:

var aspectiva_product_id = the product ID;
var aspectiva_link_parameters = {
    parameter1: value1,
    parameter2: value2,
};
(function() {
    var scr = document.createElement("script");
    scr.type = "text/javascript";
    scr.async = true;
    scr.src = 'widget URL';
    var s = document.getElementsByTagName('script')[0];
    s.parentNode.insertBefore(scr, s);
})();
Search Filter

With our advanced search filter technology, Aspectiva automatically extracts the most talked-about product aspects from customer opinions across the web to be added to your search results pages as an extra layer of filtering. With the option to filter by product aspects, your customers can find the products that are best matched to their own needs according to actual consumers’ experience, integrated with your existing filters.

API Integration

Use Aspectiva’s API to import product tags for any category and then allow users to filter by these tags and easily find products that better suit their individual needs. To import product tags, use the Aspects end point to get positive aspects for each product. We recommend importing a tag when it represents a positive aspect (an aspect that meets the positive cutoff percentage, 70% by default, of positive opinions). This is easily done by setting the sentiment request parameter to positive. Keep the size parameter of the request unassigned in order to get all the positive aspects of the product. You may choose to import a tag only when the aspect score reaches a different threshold such as 80, which means that 80% of the aspect opinions are positive. In such a case, check the score field of the response and import a tag only if it meets your preferred condition.

Use the aspect tags obtained from Aspectiva to integrate them directly into your data store used for other search filters you may already provide.

Widget Integration

Since this feature is best utilized integrated directly with your other search filters, widget integration as a stand-alone feature is not available.

Teasers

These widgets provide a concise and informative preview of Aspectiva’s information, engaging users and inviting them to learn more. Teasers are useful on category pages near each product, or on product pages above the fold or fixed in view while scrolling. They come in a selection of presentations to suit different needs and contexts.

API Integration

API integration is supported primarily by the Products service which provides the data for the total score and number of opinions, along with the aspects and their details sorted best-first.

Widget Integration:
Score Summary Preview
 <div class="asp-score-summary"></div>

Optional attributes that can be added to the HTML tag include:

Name Description
data-product-id Used to set the product ID when integrating on a category page.
data-skin See skins.
data-href Makes the widget clickable and directs the user to this encoded URL. If not provided and integration is on a product page with the Product Page Widget, clicking takes the user to the Product Page Widget.
Widget Integration:
Best Aspects Summary Preview

The Best Aspects Summary Preview wraps as needed and is best suited above the fold on a product page. Clicking on it scrolls directly to the Product Page Widget on the same page. Integration for it is available by including the following HTML tag at the desired location in the page:

 <div class="asp-best-for-preview"></div>

Optional attributes that can be added to the HTML tag include:

Name Description
data-product-id Used to set the product ID when integrating on a category page.
data-skin See skins.
Widget Integration:
Best Aspects Summary Bar

With its minimal footprint and sleek design, the Best Aspects Summary Bar is a great way to keep the product’s best aspects in view at all times without changing the layout of your product page. It remains fixed at the bottom of the page, and includes a button that scrolls the customer directly to the Product Page Widget on the same page. To integrate it simply include aspectiva_best_for_fixed_bar in the page’s JavaScript initialization code. For example:

require(['widget URL'], function(o) {
    o.init({
        aspectiva_product_id: the product ID,
        aspectiva_best_for_fixed_bar: true,
    });
});

For the plain JavaScript snippet:

var aspectiva_product_id = the product ID;
var aspectiva_best_for_fixed_bar = true;
(function() {
    var scr = document.createElement("script");
    scr.type = "text/javascript";
    scr.async = true;
    scr.src = 'widget URL';
    var s = document.getElementsByTagName('script')[0];
    s.parentNode.insertBefore(scr, s);
})();
Widget Integration:
Star Ratings

A more traditional Star Ratings widget is also available by including the following HTML tag at the desired location in the page:

 <div class="asp-ratings"></div>

Optional attributes that can be added to the HTML tag include:

Name Description
data-product-id Used to set the product ID when integrating on a category page.
data-skin See skins.
data-href Makes the widget clickable and directs the user to this encoded URL. If not provided and integration is on a product page with the Product Page Widget, clicking takes the user to the Product Page Widget.
Widget Integration:
Opinions Count

This simple widget is often used along with one of the other widgets to display the total number of opinions. It shows the number as plain text allowing you to style or link the text as needed. Include the following HTML tag at the desired location in the page:

<span class="asp-reviews-count"></span>

Tip

To include text before and after the count that only appears when there is product information available, include the words using CSS instead of HTML as follows:
<style>
.asp-reviews-count:not(:empty ):before { content: ' See '; }
.asp-reviews-count:not(:empty ):after { content: ' web opinions '; }
</style>

Optional attributes that can be added to the HTML tag include:

Name Description
data-product-id Used to set the product ID when integrating on a category page.

Just like our other widgets, the Score Summary Preview is “responsive”, adjusting it’s presentation automatically depending on the space made available for it, so integration in both product pages and category pages is seamless. Integration for it is available by including the following HTML tag at the desired location in the page:

Need help from the support team?

Email us at: support@aspectiva.com