Documentation

Shoppable Widget

Please note that this documentation only applies to text-based recipe web pages. For recipe videos, the implementation will vary, and will also depend on the capabilities of your media player.

How It Works?RequirementsInstallationCustomizationChange Log

How It Works?

The partner will need to insert:

1) a line of JavaScript into the page containing a recipe
2) an HTML tag where the button is expected to show up

The partner will be able to specify the color of the button within the HTML tag. When the JavaScript is initialized, it will extract the ingredients from the schema.org compliant recipe metadata on the page that stores the recipe name, ingredients used and quantity. Then it will send this data, along with the canonical URL of the page to SideChef server. If this is the first time our server sees this recipe, it will save the information and also match the ingredients to the ingredient list in the SideChef database. The JavaScript will also inject the stylised button to the location where the partner has placed the HTML tag.

When someone clicks on the button, this opens up a popup/lightbox on the page. The popup will also make a call to SideChef servers to get the closest store based on the user's IP address, and also the ingredient matched products for this store. If we are unable to find a store for the user’s IP, we will use our default store (in New Jersey).

Requirements

For the SideChef Widget to function properly, we require the content page to be annotated with the schema.org Recipe type markup in the HTML <head> section of your recipe pages. We support both the JSON-LD and Microdata markup formats. Here is an example:

<script type="application/ld+json"> {
  "@context": "https://schema.org",
  "@type": "Recipe",
  "name": "Mom's World Famous Banana Bread",
  "author": "John Smith",
  "datePublished": "2009-05-08",
  "description": "This classic banana bread recipe comes from my mom.",
  "image": "https://www.example.com/images/bananabread.jpg",
  "url": "https://www.example.com/recipes/42/moms_world_famous_banana_bread",
  "recipeIngredient": [
    "3 or 4 ripe bananas, smashed",
    "1 egg",
    "3/4 cup of sugar"
  ],
  "cookTime": "PT1H",
  "prepTime": "PT15M",
  "recipeYield": "1 loaf"
}
</script>

We always recommend recipe publishers implement schema.org annotations, because it improves the way search engines crawl and return recipes in search results, boosts SEO rankings, and also allows for rich results/snippets, like the example below:

Using schema.org markup on your site increases the chances that your website’s search results will include more interesting information (like a photo, preparation time, rating, or ingredients information), which in turn means that more people will click on that link.

Read morehere on how Google leverages recipe structured data.

Installation

After signing up to become a SideChef partner, you will get access to the SideChef JavaScript asset. Then, you need to ensure that the HTML for your content pages contain the following line:

<script async src="https://www.scgrocery.net/widget/"></script>

We suggest placing the script element near the end of the body tag.

Next, you will need to define where the SideChef Widget will be loaded to show the button in your page. You can do this by inserting the following HTML element in your content page where you wish for it to appear: 

<div id="sidechef-shop-button"></div>

The widget will appear to your users as a clickable image as shown in the section below.

We recommend testing the shoppable button on your staging server. You can test that the button works on a single recipe URL that you will provide for us. If this URL is publicly accessible, then we can ingest this recipe from our platform. If this URL is protected within your network, then please provide us either with the production version of this recipe, or provide us with the recipe URL, the recipe title, the ingredients names, and the associated quantities of the ingredients, so we can manually register this recipe into our system.
‍
Once we have successfully ingested/registered the recipe in our system, we will inform you that you can proceed with testing, and the shoppable button will show up properly on your staging server.

Customization

There are two design options you can choose from:

Multi-button - Optimized for conversions

Clicking on the retailer logo will open a new browser window, taking a user to the retailer's web page with the selected products pre-populated in the user's shopping cart.

Clicking ‘view all’ button, a pop up will appear with the recipe ingredients mapped to available products in a user's closest retailer, as shown below.

Clicking on the call to action button will open a new browser window, taking a user to the retailer's web page with the selected products pre-populated in the user's shopping cart.

Please note that Kroger can not be exposed in the multi-button option, it will only be available in the pop up.

Single-button

Clicking on the call to action will open the same pop-up as mentioned above, where the user can select which retailer he prefers to shop.

It is possible to customize the appearance of the button using any of the following data attributes:

<!-- Button Design Style -->
data-style-button="multi" <!-- Options: single, multi. Default: multi -->

<!-- Button Text Color -->
data-text-color="white" <!-- Default: white -->

<!-- Button Background Color -->
data-bg-color="black" <!-- Default: black -->

<!-- Button Text -->
data-button-text="SHOP INGREDIENTS" <!-- Default: "SHOP INGREDIENTS" -->

<!-- Language of Widget Button -->
data-lang="en" <!-- Supports: en, de. Default: en -->

<!-- Disable Header Text -->
data-disable-header <!-- Hides the header text rendered before the button -->

<!-- Disable 'Powered by SideChef' Text -->
data-disable-powered-by <!-- Hides the 'Powered by SideChef' text rendered below the button -->

<!-- Partner Key Configuration -->
data-partner-key="" <!-- Add partner key in the attribute to control how the widget behaves based on the partner configuration
n -->

<!-- Enable Liquor Sales -->
data-enabled-liquor <!--  Allows the sale of alcohol products if that is allowed in the user’s state -->

<!-- Liquor Sale Message for Dry States -->
data-liquor-message="" <!-- Specific message displayed for users in dry states -->

<!-- URL for Dry States -->
data-liquor-url="" <!-- URL for redirecting users from dry states -->

<!-- Enabled Grocers List -->
data-enabled-grocers="" <!-- List of grocers visible, separated by commas -->

<!-- Disabled Grocers List -->
data-disabled-grocers="" <!-- List of grocers hidden, separated by commas -->

<!-- Disabled View All Button -->
data-disable-view-all <!-- Hides the view all button which in multi button mode -->

<!-- Scale Down Grocer Buttons -->
data-button-scale="0.9" <!-- specify a number between 0 and 1 to scale down the grocer buttons -->

For example, by inserting the following HTML element in your content page:

<div id="sidechef-shop-button" data-style-button="single"
       data-text-color="yellow"
       data-button-text="Shop Online"
       data-disable-header
       data-disable-powered-by>
</div>

The widget will appear as shown below:

The SideChef widget also supports displaying Ads. One needs to insert the following HTML snippet where the Ads should appear:

<div id="sidechef-widget-ad"></div>

FAQ

How long does it take for the SideChef buttons to appear on my site?

After you provide all the assets as specified above and SideChef completes processing recipes and products, we will inform you that the buttons are ready for your testing. The buttons will appear as soon as you integrate the JavaScript snippet into the recipe page.

Why does the grocery cart show items as out of stock, even when the store actually has them?

SideChef uses the retailer’s snapshot and real-time availability API to determine product availability.  Sometimes that can be out of sync with the actual inventory of the store.  Also the fulfillment method might impact the availability, meaning the product might be available for pickup/delivery, but not for shipping, and vice versa.  This is true in Target’s case where they do not allow perishable items to be shipped, and hence it would be placed in the “Saved for Later” section of the cart, unless the fulfillment is changed to pickup/delivery, assuming the product is available at the store.

Why am I seeing different products added to cart when I use the direct buttons versus adding products from the popup?

When using the direct to cart button, SideChef picks the closest store near you based on your IP address.  When you open the pop-up, that default store is also chosen.  But when you change the zip code or change the store selected, then other products can be chosen.  Changing the zip code or store from the popup does not change what the default store used in the direct buttons are, so when the store is changed from the pop-up, then there might be differences between products of the two flows.

Why are some products on Target placed into the “Saved for Later” section of the cart?

Products are placed in the “Saved for Later” when the product is out of stock or is not available for shipping.  Perishable products are ineligible for shipping and are pickup/delivery only, even when they are available.
Target defaults to shipping as the fulfillment method, which can be updated on the Target side in order to move a perishable item from “Saved for Later” back into the Target cart for pickup/delivery.

If I make updates to the recipe ingredients list, will the product list in the cart be updated automatically?

Any changes to the tracker must accompany a message to the SideChef team informing us of the change.  We will update the recipes per your changes so we can ensure the consistent information is displayed.

Can I replace the shoppable buttons from one recipe with a different recipe?

You can add more recipes within your contracted limit, but we do not support swapping out recipes that have been ingested and released to reduce the count in the contracted limit.

Why are some ingredients not matching the correct products in the SideChef cart?

We have two flows for product ingredient matching: One is sponsored products and the other is non-sponsored products.  For sponsored products and for all retailers except for Instacart, SideChef handles the matching and we look for the first product in the ordered sponsorship chain (primary and fallback) that is available, and use that as the matched product.  If none are available, we default to the first product but mark it as “out of stock” in the product list.For Instacart, we simply send the branded product name to their platform, and the matching is done on the retailer's side.For non-sponsored products, the matching is done on the retailer side, and they will return the best match that is available.  It is possible that the retailer returns a similar product that is not exactly what was the ingredient.Note that SideChef currently uses the same sponsorship mechanism to sponsor private-labeled products to avoid displaying products from competitors.Note that due to different product availability in the stores, each store can have different matched products.

Why are some products placed in the “My Pantry” section of the SideChef cart?

SideChef has a set of ingredients that we assume the user will most likely have, and these are then added to the “My Pantry” section.  Users can still add them if needed by clicking on the item.

I have changed the canonical URL of the page, and now the button is not showing.  Why can’t I change the canonical URL?

SideChef uses the canonical URL as the ID, tying the shoppable button content to the page, because this is specifically what this is designed for and used by all search engines.  Please read the further explanation of the canonical URL and its use from Google, and why this is used as the definitive ID of the page versus using the URL.  It is important to keep the canonical URL consistent such that the page's reputation for SEO purposes is maintained.  It is fine to change the actual page URL, or have multiple different URLs resolving to the same page, as long as the canonical URL stays consistent.  For a new page, we would need to add the canonical URL to our whitelist, and then trigger the ingestion and QA of the new page.

Troubleshooting

Shoppable Buttons Not Displaying Correctly

Possible Causes:

  • The widget is not properly embedded in the recipe page
  • Missing or incorrect widget configuration settings
  • Conflicting CSS styles or JavaScript on the page
  • The SideChef team has not whitelisted the recipe pages yet
  • The attribute “data-partner-key” has not been inserted or it has been inserted incorrectly

Troubleshooting Steps:

  • Step 1: Verify if the widget code is correctly placed in the recipe page HTML (check for any missing or broken code).
  • Step 2: Check the widget configuration settings (e.g., placement, size, and content source).
  • Step 3: Inspect the page’s CSS or JavaScript to see if other styles/scripts are interfering with the widget. You can do this by temporarily disabling other scripts/styles and checking the widget’s display.
  • Step 4: Confirm the attribute “data-partner-key” has been inserted into the code
  • Step 5: Check the JavaScript console to see if it is reporting any errors
  • Step 6: Clear the browser cache and refresh the page to check if the issue persists.
  • Step 7: Confirm with the SideChef team that the recipe pages have been whitelisted

Shoppable Buttons Not Functioning

Possible Causes:

  • The provided recipe canonical URL has changed and is different than the original canonical URL
  • The provided recipe URL has not been whitelisted yet by the SideChef team
  • The data attribute “data-partner-key” has not been inserted or it has been inserted incorrectly

Troubleshooting Steps:

  • Step 1: Verify that the provided URL has not changed (check the recipe page source for the canonical URL and ensure it matches the URL supplied in the tracker spreadsheet)
  • Step 2: Confirm if the URL has been whitelisted by the SideChef team
  • Step 3: Verify that the data attribute “data-partner-key” has been inserted

Shoppable Button Not Updating With New Recipe Data

Possible Causes:

  • The recipe has been updated, but the changes have not been implemented by the SideChef team
  • The recipe used to display the button is no longer displaying it

Troubleshooting Steps:

  • Step 1: Verify that the originally provided URL did not change
  • Step 2: Inform the SideChef team about the changes on the recipe pages

Contact Support

If you’ve followed all troubleshooting steps and the issue persists, please contact your Key Account Representative with the following information:

  • A description of the issue, including time, browser version, and phone model if accessed from a mobile phone
  • Steps to reproduce
  • A link to the affected recipe page
  • Preferably, record the issue with a video, or at minimum, take screenshots of the issue.

Change Log