HomeGuidesAPI Reference
Guides

Custom MerchantJS

Steps for integrating Findify with any platform

Suggest Edits

Overview

You can integrate Findify with any storefront in a variety of different ways:

Custom MerchantJS Integration

Findify integration consists of a couple key components:

  1. Product feed pulling: This is the mechanism with which Findify keeps up to date with the products on your store. It will ensure all products, prices and availability shown in search results are accurate.
  2. Customer Feedback: Collecting metrics about which products are viewed and ultimately purchased is important to improve the performance of Findify's search algorithm.
  3. Search: Findify replaces whichever search you may have built in to your store. This is a simple addition to your store.

To integrate Findify into your shop you'll need to follow steps listed below:

  1. Select a plan and create a Findify account
  2. Configure a product feed
  3. Setup the search page
  4. Setup the feedback mechanisms: Add the Findify tracking HTML tags
  5. Add the Findify Script Tag to the <head> section

📘

We're Here To Help

If you have any problems or are stuck at any step, don't hesitate to contact us at [email protected].

1. Create a Findify Account

If you haven't done so yet, you need to sign up for Findify's service by visiting our Registration Page.

📘

Already Have an Account?

If you already have a Findify account, you can access it at our Dashboard.

  1. Go to our Registration Page
  2. Select Javascript - Other platforms
  3. Enter your name, email and store URL. The store URL value should not contain https:// or http:// prefix, e.g. www.example.com or example.com are both valid
  4. You will receive an email to validate your account. Click the confirmation link and proceed to the next steps

1.1. Provide More Information About Your Shop

In order to make the most of Findify's search algorithm, we need to know a bit more about your store. You will be asked to fill all required information out during the onboarding and can always adjust your setting in the Dashboard.

  1. Select the language

🚧

Select The Correct Language

Choosing the language of your store is important because it impacts the way search queries are analyzed and is a big factor in the performance of the search itself.

Findify UI components will also be translated to the language you selected.

If you don't find the language you need, contact us at [email protected]

  1. Choose the time zone that your shop is in. This is mainly for analytics to be calculated correctly.
  2. Choose the currency of your store

❗️

Multiple Currencies

we currently don't support multiple currencies on a single store, unless the conversion is done on the front end.

If you need multiple currencies, contact us at [email protected].

2. Configure a Product Feed

Findify needs to load all the product information from your store to index them and make them searchable. This happens initially during the onboarding as well as periodically, once a day.

The way it works is, Findify's servers will request a product feed via HTTP or HTTPS from an endpoint you configure. This endpoint needs to be publicly accessible, or you need to explicitly grant Findify's servers access to it.

📘

Feed Pulling Authentication

We also support Basic Authentication when requesting the product feed.
To enable this feature for your feed, please contact us directly at [email protected].

Findify will refresh the product at a set interval.

We support the following formats of the product feed. Click on the format best suited for you to learn more about it's required structure:

You will need to provide the URL and the format of the feed in the onboarding wizard or your Findify dashboard.

If there are any issues with the product feed format or if there is any missing product information, you will be notified via email, once the synchronization job has completed.

❗️

Product Feed Issues

You will not be able to proceed further with the integration unless the product feed is processed successfully.

If your product feed is formatted correctly and contains all required information, but you still get errors from Findify, please contact us at [email protected]

3. Setup the Search Page

This is the most visible component of Findify. It's where your customers will be able to find products.

Configure the url

We recommend you create a new, empty page in your store to host the page, where detailed search results and interface will be shown.

You will need to configure the address of this page, it's URL, in your Findify dashboard. The search page URL is the address to which your customers will be redirected to view the search results.

Once you've created the search page and have it's URL, configure it in the onboarding flow, or share it with your integration contact at Findify.

Examples of search page URLs:

  • /search
  • /pages/search
  • /pages/search/results

You can also specify a blank page "/", so that the search results will be rendered on the home page of your store in a modal view.

Configure the Search Page

There are a handful of HTML elements you will need to add in order to enable search:

  • A container HTML element in which search results will be displayed
  • Input HTML element for the autocomplete

Search Result Container

Search results will be rendered by Findify Javascript SDK in any HTML element that has data-findify-attr="findify-search-results" attribute.

<div data-findify-attr="findify-search-results" data-findify="controlled-tabs"></div>

📘

Note

The search results will only be displayed, if the URL of the page containing the element with the findify-search-results attribute matches the configured search page URL.

Autocomplete Input Field

Autocomplete functionality can be added to any input field. You simply need to add the data-findify-attr="findify-autocomplete-input" attribute to it.
You can add the attribute to multiple input elements on a single page. 

<input data-findify-attr="findify-autocomplete-input"/>

4. Feedback Integration

Findify tracks customer activity which is in turn used by our Machine Learning algorithms to improve the search performance.

This is done in a way that our javascript SDK looks for certain HTML tags on the pages and reads the information out of them. Below, we describe the tags you need to add and where to add them.

4.1. Product Page

It is important to know which products a customer views. This allows Findify to rank products by popularity, giving popular products a higher score and thus a more prominent placement in search results.

Add this tag to all product pages. We recommend placing it in your product page template.

<div data-findify-event="view-page" data-findify-item-id="PRODUCT_ID" data-findify-variant-item-id="PRODUCT_VARIANT_ID"></div>

Schema:

  • data-findify-item-id must contain the ID of the product. The ID of the product must be the same as the value of item_group_id in the product feed.
  • data-findify-variant-item-id could contain the variant ID of the product, in case you have multiple variants of the same product. This tag is optional.

4.2. Cart Page

Knowing which products customers add to cart is an important signal for our Machine Learning algorithm. It helps Findify make better recommendations for the customers of your store, ultimately increasing your conversion rate.

🚧

Frequently Purchased Together

The 'Frequently purchased together' recommendation will not work if this tag is not present.

We recommend you place this tag in all templates that display customer's cart items.
Even if the cart is empty, this tag should still be included.

<div data-findify-event="update-cart">
  <div data-findify-item-id="PRODUCT_ID_1" data-findify-variant-item-id="VARIANT_ID_1" data-findify-unit-price="{{ price }}" data-findify-quantity="{{ quantity }}"></div>
  <div data-findify-item-id="PRODUCT_ID_2" data-findify-variant-item-id="VARIANT_ID_2" data-findify-unit-price="{{ price }}" data-findify-quantity="{{ quantity }}"></div>
</div>

Schema:
For each line item there should be a div with the following tags:

  • data-findify-item-id must contain the product ID
  • data-findify-variant-item-id should contain the variant ID, if applicable. This tag is optional
  • data-findify-quantity must contain the quantity of the product in the cart
  • data-findify-unit-price should contain the unit price of the product (the discounted price, if it's a discount)

If the cart is empty for the user, just put an empty tag

<div data-findify-event="update-cart"></div>

4.3. Purchase Confirmation Page

Knowing which products the customer purchased is important for two reasons.
First, Findify will use it as an input to the Machine Learning algorithm to better promote popular products and improve the performance of the search.
Second, we will provide you, the merchant, search analytics to better understand the impact of Findify on your conversion.

👍

Improved Performance

The machine learning components automatically improve the search functionality on your site and increase your conversion, average order value and customer lifetime value.

This tag should be placed on the page that is shown to the customer after their order has been confirmed (often called order confirmation page or checkout success). 

<div data-findify-event="purchase" data-findify-order-id="ORDER_ID" data-findify-currency="EUR" data-findify-revenue="288" data-findify-total-discount="5" data-findify-total-tax="6" data-findify-total-shipping="10">
   <div data-findify-item-id="PRODUCT_ID_1" data-findify-variant-item-id="VARIANT_ID_1" data-findify-unit-price="269" data-findify-quantity="1"></div>
   <div data-findify-item-id="PRODUCT_ID_2" data-findify-variant-item-id="VARIANT_ID_2" data-findify-unit-price="19" data-findify-quantity="1"></div>
</div>

Schema:

  • data-findify-order-id must contain the unique ID of the order
  • data-findify-currency must contain the currency code of the order (use ISO 4217 for the currency code, for example: USD, EUR, SEK…)
  • data-findify-revenue must contain the total order value, which should include all the discounts applied and the shipping costs if applicable
  • data-findify-total-discount must contain the total order discount value
  • data-findify-total-tax must contain the total order tax value
  • data-findify-total-shipping must contain the total order shipping cost value

For each line_item, there should be a div with the following tags:

  • data-findify-item-id must contain the product ID
  • data-findify-variant-item-id should contain the variant ID, if applicable. This tag is optional
  • data-findify-quantity must contain the quantity of the product in cart
  • data-findify-unit-price must contain the unit price of the product (the discounted price, if it's a discount)

5. Add the Findify Script Tag

Finally, to tie everything together and enable Findify on your store, you need to add the Findify Script tag to the <head> section of your template.

Go to your Findify dashboard to obtain the snippet and paste it to your header template.

Example snippet:

<script src="//assets.findify.io/search/prod/your-shop-domain.com.min.js" async defer></script>

👍

Congratulations!

Findify should be live in your store now!

Updated about 1 year ago

What’s Next