Integration via the Impresee Snippet
This document describes how you can integrate the Impresee snippet into your online store, and also all the options you can use to configure it.
Basics
The Impresee snippet is a short piece of code written in Javascript that has all the necessary to integrate an e-commerce site with Impresee’s search services. The functionalities it includes are the following:
- A drawing canvas
- Option to upload images from the filesystem or directly from a camera
- A modal window that displays the uploaded image, which allows cropping the picture
- Performing visual searches
- Performing instant searches
- Displaying search results
- Instant search screen
- Full search screen, with filters, ordering and pagination options
The snippet works by loading all the code that is necessary to perform the visual searches into the browser. To operate, the snippet will capture the clicks on the buttons that are set to activate each type of visual search.
Integration
The snippet must be integrated into any view of the online store where Impresee’s features are to be enabled. Generally, it is enough to add the code next to the search bar. In addition, the buttons that trigger each type of search must be added into the site (this must be done only if the search by text is disabled, otherwise it is optional). An example of how the snippet could look like is shown below:
_wssee is a javascript object variable that contains Impresee’s configuration, which is available at window level. The properties of this object indicate what kind of search services will be enabled and how the results will be displayed. This object has different keys that will allow you to customize the search process and results. There is only one key that is required, which is the setup key. The value assigned to setup is an object that describes how the search will be triggered, your Impresee applications, and other things such as the main color of the results and the container of the grid of results. To enable the search-by-picture service you must include a photoButton key (the CSS class of the button that’ll trigger the visual search), and a photoApp key (your Impresee search-by-picture application) properties in setup. To enable the search-by-sketch service you must include a sketchButton key (the CSS class of the button that’ll trigger the search by sketch), and a sketchApp key (your Impresee search-by-sketch application) properties in setup. For example, suppose that you have two buttons as shown below, and you wish to configure both search-by-picture and search-by-sketch.
What you have to do is create the _wssee, and assign a setup key as shown below object and add both a photo and a sketch properties, as shown below
Configuration
General options
The setup variable accepts extra optional properties, these options allows you to customize how the results will be displayed, how the layout will look, and more:
| Option | Description | Type | Default | Example |
|--------------------------|----------------------------------------------------------------------------------------------------------------------------------------|-------------|---------------------------|-------------------------------------------------------------|
| `loadAfterPageRender` | Indicates whether the code should be loaded before, or after the whole site loads (useful when search buttons are created dynamically) | `boolean` | `false` | `true` |
| `container` | Selector of the DOM element that'll contain the search results | `string` | `null` | `.container` |
| `mainColor` | Main color of the search interface, which can be seen on the buttons | hex value | `#9CD333` | #999999 |
| `afterLoadResults` | Function that is called after results are added into the DOM | `function` | `function(searchType) {}` | `function(searchType) { console.log('results'); }` |
| `beforeLoadResults` | Function that is called before results are added into the DOM | `function` | `function(searchType) {}` | `function(searchType) { console.log('before results'); }` |
| `onSearchFailed` | Function called when a search fails | `function` | `function() {}` | `function() { console.log('search failed'); }` |
| `onCloseResults` | Function called when results are closed | `function` | `function() {}` | `function() { console.log('search closed'); }` |
| `addSearchDataToUrl` | Add search related data to the URL, this allows reloading the search when refreshing the webpage | `boolean` | `false` | `true` |
| `onlyCameraAsInput` | Used in mobile devices to only allow the usage of images only taken directly from the camera | `boolean` | `false` | `true` |
| `disableImageCrop` | Used to disable the image crop screen. When true, the user is no loner given the option to crop the query | `boolean` | `false` | `true` |
| `numberFractionDigits` | Number of fraction digits to be included in prices | `int` | `2` | `0` |
| `decimalSeparator` | Char used to separate fraction digits from the whole number | `char` | `,` | `.` |
| `thousandsSeparator` | Char used to separate thousands from the whole number | `char` | `.` | `,` |
| `currencySymbolAtTheEnd` | Indicates whether the currency symbol should be at the back of the price or not | `boolean` | `false` | `true` |
| `colorOnSale` | Color of the "On Sale" label that appears when products are on sale | `hex value` | `#FF0000` | `#9CD333` |
| `useDetection` | Indicate whether to sue detection or not (Note: use true ONLY if you selected fashion & apparel) | `bool` | `false` | `true` |
| `displayOnSaleProducts` | Show "On sale" sign on products with a discount | `bool` | `true` | `false` |
| `currencySymbolAtTheEnd` | Place currency symbol at the end of the price (right side) | `bool` | `false` | `true` |
| `customGoogleAnalytics` | Google analytics code, used to register search events | `string` | `` | `UA-XXXXX-Y` |Search by text
To configure and enable the search by text or instant search functionality you also need to include a searchByText key, which has three required fields:
useText: boolean that indicates whether or not the instant search will be enabled on the site (e.g. true)searchBarSelector: selector of the input part of search bar of the site, where people can actually type (e.g. #searchbar)fullTextSearchContainerSelector: selector of the container that will hold the full results. These are the ones that feature filters, pagination and more! (e.g. #root)
The searchByText also has optional key values, which are described below:
| Option | Description | Type | Default | Example |
|-----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|---------------------------|-------------------------------------------------------------------------|
| `searchDelayMilis` | The delay in milliseconds between the latest user input and the execution of the search result. | `int` | `300` | `100` |
| `pressSeeAll` | Function that is executed when the user presses the "see all results buttons" or presses enter on the search input | `function` | `function (queryText) {}` | `function(queryText) { window.location.href = "?IText=" + queryText; }` |
| `onCloseResults` | Function that is executed when the user closes the full results screen | `function ` | `function () {}` | `function () { console.log('closing results') }` |
| `onOpenDropDownResults` | Function that is executed when the Instant Search dropdown appears, that is when a user clicks on the search bar | `function ` | `function () {}` | `function () { console.log('opening dropdown') }` |
| `onCloseResults` | Function that is executed when the Instant Search dropdown is closed | `function` | `function () {}` | `function () { console.log('closing dropdown') }` |
| `fullTextSearchContainerSelector` | Selector of the DOM element that will contain the search results grid | `string` | `null` | `.container` |
| `computeTopFromElement` | Selector of the DOM element to be used when position the search results grid vertically (usually it should be to site's header) | `string` | `null` | `header` |
| `instantFull` | Tells the snippet to load the results from the full search without reloading the site (we recommend to set this option to true and use the `computeTopFromElement` to locate the grid in a nice position) | `bool` | `false` | `true` |
| `useButtonAsSearchBar` | Displays a button in the lower left corner of the site, which will work as a search bar. Recommended for sites with no search bar | `bool` | `false` | `true` |
| `useText` | Use search by text feature | `bool` | `true` | `false` |
| `searchBarSelector` | Search bar selector | `string` | `[name=q]` | `[name=q],input[name=s]` |
| `buttonSearchBarLocation` | Position of the floating button. Possible values: BOTTOM_LEFT, TOP_LEFT, MIDDLE_LEFT, BOTTOM_RIGHT, TOP_RIGHT, MIDDLE_RIGHT | `string` | `BOTTOM_LEFT` | `TOP_RIGHT` |
Note: The full search results will be loaded when Impresee’s snippet finds an IText query param. This is why we recommend the pressSeeAll function to be set to
Labels
The _wssee object also has an optional key texts, which corresponds an object, that allows the customization of textual labels that appear on screen, such as in the canvas, crop screen, among others.
With this _wssee can look as follows:
The available keys for texts are shown below:
| Key | Description | Default |
|------------------------------|----------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------|
| `searchResultsTitle` | Title of the grid that contains the search results | Search results |
| `searchButtonLabel` | Label of any search button | Search |
| `oops` | Surprise exclamation used when an error occurs | Oops ... |
| `error` | Header of the error screen | We didn't expect this at all. |
| `errorDescription` | Message displayed on the error screen | It seems our system is overheating, please try again later. |
| `dragAndDropImageTitle` | Header of the drag and drop image screen | Drag & Drop an image or just click here |
| `dragAndDropImageMessage` | Message displayed on the drag and drop image screen | Upload the image you'd like to use to search |
| `customSelectionSearchLabel` | Message displayed when re-cropping a query | Custom search |
| `startWriting` | Message displayed before the user starts typing in the Instant Search dropdown | Start typing to search |
| `currencySymbol` | Currency symbol used when displaying prices | $ |
| `searchByPhoto` | Search by photo label that appears on the Instant Search dropdown | Search by photo |
| `searchBySketch` | Search by drawing label that appears on the Instant Search dropdown | Search by drawing |
| `seeAllResults` | See all results label that appears on the Instant Search dropdown after results are painted on the screen | See all results |
| `noMatchingResult` | Text that appears when no results match | We couldn't find any results for: |
| `onSale` | On sale label used on products that are on sale | On sale |
| `resultsTitleforTextSearch` | Header for the full text search results screen (Desktop) | Search results for |
| `numberResultsTitle` | Header that displays the number of results (Desktop). If you decide to modify this text, please keep the placeholder ({1}) | Displaying {1} results |
| `resultsTitleForMobile` | Header for the full text search results screen (Mobile) If you decide to modify this text, please keep the placeholders | Displaying {1} results for \"{2}\" |
| `filtersTitle` | Header for the filter column (Mobile) | Filters |
| `clearFilters` | Clear filters button label | Clear filters |
| `sortBy` | Sort by select label | Sort by |
| `applyFilters` | Apply filters button label (Mobile only) | Apply |
| `tryAgainWhenNoResults` | Label that motivates users to keep searching when no results match | Why don't you try drawing or taking a picture of what you want? |Hints
- The CSS class
ImpreseeHidecan be used to hide elements. One interesting detail is that when the search results are closed, our system will find all elements with this class and remove the class from them. This allows you to hide certain elements when displaying the results. This can be useful when using thecontaineroption. - If you decide to use the
ImpreseeHideclass we recommend that you use thebeforeLoadResultsor theafterLoadResultsfunctions to locate the elements you wish to hide. You can also add theImpreseeHideclass to those elements inside of any of these functions. - The
beforeLoadResultsandafterLoadResultsreceive the search type as a parameter, this means that you can customize the look and feel of Instant search, search by sketch and search by photo separately. The search types of these kinds of search are:- Instant search:
instant search - Full search by text:
text - Search by photo:
photo - Search by drawing:
sketch
- Instant search:
- If you decide to embed the search results somewhere in your site, please take into consideration that this might fail if the container hides the overflowing content (CSS
overflow:hidden). You can use thebeforeLoadResultsfunction to modify the overflow behavior of the container, and then you can use theonCloseResultsfunction to have it back to normal.
If you have any question regarding integration via this snippet, please contact support@impresee.com