Platform integration guide

Platform integration guide

This guide is meant as a guideline for external developers creating extensions that integrate shop platforms with Hello Retail.

If you run into issues following the guidelines set in this guide, then please contact our support team so we can discuss about possible solutions.

You can find our API-documentation here: https://apidocs.helloretail.com.


Extension UI requirement:

The extension needs to provide a simple UI where the following two things can be accomplished:

  • Insert and save the unique Hello Retail partner id.
  • Generate and save a random key for the data feed access authentication.
  • Insert container Divs with specifically provided ID's at targeted locations throughout the site (This one is not strictly required).

Tracking requirements:

General tracking:
The Hello Retail JavaScript takes care of most of the behavioral tracking on the website and so the extension needs to insert this on all pages throughout the webshop.

The script should be inserted into the header section for optimal load speed.

The script requires jQuery and will detect if it is available upon load.
If jQuery isn't available then our script will load it automatically.
So for shops already using jQuery you should make sure jQuery loads first, to avoid duplicates.

<script type="text/javascript">
        (function() {
                var aws = document.createElement('script');
                aws.type = 'text/javascript';
                if (typeof(aws.async) != "undefined") { aws.async = true; }
                aws.src = (window.location.protocol == 'https:' ? 'https://d1pna5l3xsntoj.cloudfront.net' : 'http://cdn.addwish.com') + '/scripts/company/awAddGift.js#YOUR_PARTNER_ID';
                var s = document.getElementsByTagName('script')[0];
                s.parentNode.insertBefore(aws, s);
        })();
</script>

* Note that the #YOUR_PARTNER_ID  part of the script above needs to be replaced by the unique partner id provided by the customer through the UI of the extension.

For SPA (Single page applications) you need to call the script's reload endpoint whenever essential page content changes - the most common would be when the url changes.
The following method should be called after the new content is available in the DOM.

ADDWISH_PARTNER_NS.api.reload()

Conversion and cart tracking:
While the Hello Retail script takes care of most of the tracking on its own, it still needs a little help when it comes to conversion and cart tracking.
Conversion and cart tracking can be done by either inserting spans to the DOM or by calling our JTHIS SETUP COULD REQUIRE MULTIPLE FEEDS FOR ONE SITE -avaScript API - of the two methods we prefer the API.

If you choose to use our JavaScript API then you need to make sure that the general Hello Retail script is loaded and ready when you try to call the API - you can check our documentation for event binding here: https://apidocs.helloretail.com/#event-binding
There is also an example of this being used if you go to the conversion tracking example in the documentation.

Conversion tracking specifics:
Conversions should be registered when an order is completed. Typically this will happen on the order receipt/confirmation page.

Cart tracking specifics:
The cart tracking needs to happen whenever a change is made to the cart, no matter what page the customer is on. For simplicity, you can also choose to just update the cart on every page load.

If a variant product has been purchased then the ProductData registered in the cart should be from that variant.

Cart restore:
The cart span has an attribute called "cart-url" and the API function accepts a "url" key in its data object. This is used specifically for abandoned cart triggered emails so a link to restore each unique cart can be provided. 

Usually, this is implemented through a cart restore endpoint in the extension which takes cart data as a parameter - it could look something like this: https://domain.com/cart/restore?x:y,x:y where x indicates the product id and y indicates the quantity.
Depending on the shop system it might be necessary to expand the format to accept variation or option ids as well.

Exactly how you chose to implement this feature is up to you as long as it works by requesting a URL with some parameters.

 


Markup insertion requirements:

Recommendation boxes

Hello Retail's recommendation boxes can be loaded by adding container Div's with specific ID's to the site's markup. You can find an article on how to find the IDs for your site here: https://support.helloretail.com/t/q5aq0y/divs-for-recom-placements

If possible, we recommend that you make a UI that allows to set the ID's of the container Div's from within your platform, as this makes it easy to change the relation between container Div's and the content loaded.

 

Search

To support Hello Retails search product you will need to do two things:

1: Supply an empty page to display the full page search results on. Besides the navigation and other things that is in your base page, we need you to add  a container Div in which we will insert the results

<div id="hr-search-results"></div>

2: Add an ID to the search-bar to be used with Hello Retails instant search feature.
Altering the existing markup is preferable to replacing the old one, as this means the old one will continue to work right up until Hello Retail takes over the functionality.

<input id="hr-search-input"></input>

 


Data synchronization requirements:

General info on feeds:
Hello Retail uses feeds to synchronize data between our database and the shop. The feeds should be in JSON fomat. 

The data in these feeds must always match what is seen on the site.

This is what the root should look like:

{
    "extensionVersion": "1.0.0",
    "totalCount": 1234,
    "lastPage": 123
    "items": []
}
  • extensionVersion being the version of the extension currently installed on the shop.
  • totalCount being the total count of active products available.
  • lastPage being the last page with a given pageSize (see pagination below).
  • items the list of items on the request page

Security:
The extension should authenticate the requester of the feeds by checking that the request has a key parameter matching the random key generated by the extension (check the Extension UI requirement section).

The random key will be shared with Hello Retail and we will add it as a request parameter for all our feed requests like so:

domain.com/helloretail/productfeed?key=123xyz

We also recommend that feeds are only accessible via https.

 

Pagination:
To ease the load from the extension when requesting feeds, the extension needs to support pagination. When Hello Retail adds the parameters "page" and "pageSize" in a request then the extension should only generate a part of the complete feed.
So for a request like

domain.com/helloretail/productfeed?page=0&pageSize=100

the extension should generate a feed containing only the first 100 products.

If the pagination parameters are not present in the request then the feed should not be paginated.

 

Shop variables:

If the shop platform supports multiple languages and/or currencies we should be able to request all the necessary translations and/or prices in the feeds.
A request could look like this: 
domain.com/helloretail/productfeed?language=en&currency=eur

 

Multi-currency

Multi-currency can be supported by having one webshop per currency.

 

Feed types:

  • Product feed:
    The product feed is essential and is therefore always required. 

    For products with variants, we will refer to the main product as the master product and the variations as variants.

    If the master product is simply an empty container for the variants, and therefore doesn't have information in itself, the master product should simply inherit the info of the default variant.

    If variants don't hold specific info on their own, the shared data from the master product should be inherited by the variants.

    Below is the list of fields that should be present on each product entry in the feed:

    productData:
    type
    id
    sku
    ean
    productNumber
    price
    priceNoTax
    previousPrice
    previousPriceNoTax
    hasPriceRange
    currency
    title
    description
    hierarchies
    attributes
    keywords
    tags
    url
    imgUrl
    secondaryImgUrls
    overlay
    visibility
    instock
    quantity
    createdDate
    isNews
    variants

    You may add other fields that you find useful for our search engine or our product recommendations.

    The productData fields are explained in detail in the bottom of this guide, where there also is a sample product populated with data.

    Some of the fields may not make sense with your shop platform and some may only make sense for the masterproduct but not its variants, or vice versa, but please contact Hello Retail's support if you want to leave out a field or change the structure.

    Sample product:

    [
        {
            "type": "configurable",
            "id": 917,
            "sku": "2heu28371prop",
            "ean": "1234576251872",
            "productNumber": "837192837217",
            "price": 100,
            "priceNoTax": 80,
            "previousPrice": 130,
            "previousPriceNoTax": 104,
            "hasPriceRange": false,
            "currency": "DKK",
            "title": "Cool Bike helmet",
            "description": "This bike helmet has a great fit with an adjustabe strap. comes in two colors.",
            "hierarchies":[
                [
                    "equipment",
                    "bike equipment",
                    "helmets"
                ],
                [
                    "equipment",
                    "outlet"
                ]
            ],
            "attributes": {
                "color": [
                    "blue",
                    "red"
                ],
                "size": [
                    "unisex"
                ]
            },
            "keywords": "helmet safety cycling",
            "tags": [
                "safety",
                "outdoor"
            ],
            "url": "https://www.domain.com/cool-bike-helmet",
            "imgUrl": "https://www.domain.com/cache/250x250/cool-bike-helmet.jpg",
            "secondaryImgUrls": [
                "https://www.domain.com/cache/250x250/cool-bike-helmet-blue.jpg",
                "https://www.domain.com/cache/250x250/cool-bike-helmet-red.jpg",
                "https://www.domain.com/cache/250x250/cool-bike-helmet-2.jpg"
            ],
            "overlay": [
                "https://www.domain.com/cache/25x25/saving-badge.jpg"
            ],
            "visibility": "search/catalog",
            "instock": true,
            "quantity": 5,
            "createdDate": "2019-05-12 10:04:05",
            "isNews": false,
            "variants": [
                {
                    "type": "variant",
                    "id": "918",
                    "sku": "2heu28371propblue",
                    "ean": "1234576251823",
                    "productNumber": "837192837218",
                    "price": 100,
                    "priceNoTax": 80,
                    "previousPrice": 130,
                    "previousPriceNoTax": 104,
                    "hasPriceRange": false,
                    "currency": "DKK",
                    "title": "Cool Bike helmet blue",
                    "description": "This blue bike helmet has a great fit with an adjustabe strap. it also comes in red.",
                    "hierarchies": [
                        [
                            "equipment",
                            "bike equipment",
                            "helmets"
                        ],
                        [
                            "equipment",
                            "outlet"
                        ]
                    ],
                    "attributes": {
                        "color": [
                            "blue"
                        ],
                        "size": [
                            "unisex"
                        ]
                    },
                    "keywords": "helmet safety cycling",
                    "tags": [
                        "safety",
                        "outdoor"
                    ],
                    "url": "https://www.domain.com/cool-bike-helmet-918",
                    "imgUrl": "https://www.domain.com/cache/250x250/cool-bike-helmet-blue.jpg",
                    "secondaryImgUrls": [
                        "https://www.domain.com/cache/250x250/cool-bike-helmet-2.jpg"
                    ],
                    "overlay": [
                        "https://www.domain.com/cache/25x25/saving-badge.jpg"
                    ],
                    "visibility": "search/catalog",
                    "instock": true,
                    "quantity": 3,
                    "createdDate": "2019-05-12 10:04:05",
                    "isNews": false
                },
                {
                    "...": "...",
                    "...": "..."
                }
            ]
        }
    ]
    

     

  • Order feed:
    The order feed is also essential to a good integration and is therefor also required.

    It should Should contain orders from the last 2-3 days from the time the feed is requested as a default, but accept a parameter named "daysBack" that allows to go further back in time.

    it could look like this domain.com/helloretail/orderfeed?daysBack=90 if you wanted to get orders dating around 3 months back.

    Below is the list of fields that should be present on each order entry in the feed:

    orderData:
    id
    orderNumber
    orderProducts
    createdDate
    total
    email

    orderProductData:
    id
    url
    productNumber
    quantity
    price
    priceNoTax

    if a variant product has been purchased then the orderProductData should be from that variant.

    Sample order:

    [
        {
            "id": 888,
            "orderNumber": "91826od",
            "orderProducts": [
                {
                    "id": 144,
                    "url": "https://www.domain.com/cool-bike-helmet",
                    "productNumber": "738237238232",
                    "quantity": 1,
                    "price": 100,
                    "priceNoTax": 80
                },
                {
                    "id": 322,
                    "url": "https://www.domain.com/bike-gloves",
                    "productNumber": "837192837217-xxl",
                    "quantity": 1,
                    "price": 100,
                    "priceNoTax": 80
                }
            ],
            "createdDate": "2019-05-12 10:04:05",
            "total": 200,
            "email": "purchase@much.com"
        }
    ]

     

  • Content feeds:
    Content feeds are primarily used to enable our search engine to find and deliver relevant content on the customers' website. Some content types might be relevant for one shop system while others may be relevant for another - if you are in doubt then please contact the Hello Retail development department.
    • Category feed:
      The category feed is essential for many customers using our search feature and is therefore also considered a requirement.
      The feed should contain all the active categories belonging to the site.

      Below is the list of fields that should be present on each category entry in the feed:

      categoryData:
      id
      url
      title
      hierachy
      keywords
      description

      Sample category:

      [
          {
              "id": "72",
              "url": "https://www.domain.com/equipment/bike-equipment/helmets",
              "title": "Helmets",
              "hierarchy": [
                  "equipment",
                  "bike equipment",
                  "helmets"
              ],
              "keywords": "safety bike helmets",
              "description": "Helmets for everyone",
          }
      ]

       

    • Blogpost feed:
      Blogpost feeds are generally not a requirement, but is very nice to have anyways. 
      Whether it makes sense to include this depends on the shop platform - is it supported in the platform and is it an important part of its features?

      The content of the feed should be the same as for category feeds
       
    • Brand feed:
      If brand pages are distinguishable from category pages in the shop platform then a specific brand feed is required. If however the brands can't be distinguished from the categories then the brand will naturally occur in the category feed and there is no need to create a specific brand feed

      The content of the feed should be the same as for category feeds
       
    • Sitepage feed:
      Sitepage feeds are generally not a requirement but it is very nice to have anyway. Whether it makes sense to include this depends on the shop platform - is it supported in the platform and is it an important part of its features?

      The content of the feed should be the same as for category feeds

productData fields specifications:

type: string
Configurable, simple, bundle, etc. whatever you shop platform calls the different product types.

id: string
Id of the product.

sku: string
Sku of the product.

ean: string
Ean of the product.

productNumber: string
Product number of the product.

price: string or float
Current price in default or requested currency as shown on website incl. tax.

priceNoTax: string or float
Current price in default or requested currency as shown on website excl. tax.

previousPrice: string or float
The standard price in default or requested currency of the product incl. tax -  will be the same as the price for products not on sale.

previousPriceNoTax: string or float
The standard price in default or requested currency of the product excl. tax - will be the same as priceNoTax for products not on sale.

hasPriceRange: bool
Indicates if the product is available in a range of prices (ie through variants).

currency: string
Currency used for the price.

title: string
Product title in default or requested language.

description: string
Product description in default or requested language.

hierarchies: list of hierarchy lists
a hierarchy can be compared with the breadcrumb navigation on the site. its a list of categories, going from root category to the most nested subcategory in the hierarchical order.
Hierarchies are simply a list of hierarchies, which is useful as products often exist in multiple categories.
If one of the hierarchies is to be considered a default then that should be listed first.
attributes: object with key-value pairs - each product attribute should be assigned here. key = attribute name, value = list of attribute values assigned to the product.

keywords: string
Product keywords separated by spaces.

tags: list
List of product tags

url: string
Product URL for default or requested language.

imgUrl: string
Default image URL - preferably scaled to the size used by the shops' catalog pages.

secondaryImgUrls: list
List of secondary/alternative image URL - preferably scaled to the size used by the shops catalog pages.

overlay: list
List of HTML, image URLs or other used to display badges/overlays on the product tile.

visibility: string
Indicates the product's visibility setting  - search, search/catalog, hidden, etc.

instock: bool
Indicates if the product is in stock.

quantity: string or number
Indicates the quantity in stock. For products with variants, it would be a sum of all the variants.

createdDate: string
The timestamp of the product creation date. formatted yyyy-MM-dd HH:mm:ss.

isNews: bool
It indicates if the product should be considered as news.

variants: list of productData
List of product variants. If one of the variants is to be considered a default then that should be listed first.

 

orderData, orderProductData and categoryData fields specifications:

See productData fields specifications above as the fields are the same.

Like Follow
  • 2 mths agoLast active
  • 202Views
  • 1 Following