Skip to main content

How to Install Tolstoy on Native Sites

Written by Mikaela Lasig

Installing Tolstoy on a native site lets merchants add Tolstoy widgets to websites that are not running on Shopify. It helps merchants display shoppable or interactive Tolstoy experiences on their own site by loading Tolstoy's widget scripts directly in the website header.

  1. Click your Account > Go to Settings > Set up store.

  2. Open the Add Tolstoy Widget to Your Website step.

  3. Copy the code snippet shown in Tolstoy. Should look something like this:
    ​

    <script>
      tolstoyAppKey="YOUR_APP_KEY"
    </script>

    <script
      type="module"
      async
      src="https://widget.gotolstoy.com/we/widget.js"
    >
    </script>

    <script
      type="module"
      src="https://play.gotolstoy.com/widget-v2/widget.js"
      id="tolstoy-widget-script"
      data-app-key="YOUR_APP_KEY"
      data-shop="public/integrations/products-import/YOUR_APP_KEY"
      data-product-id="PRODUCT_ID_OPTIONAL"
    >
    </script>


    ​

  4. Add the snippet to the <head> section of your website, or place it in your site's global header template so it loads across the pages where Tolstoy should appear.

  5. Copy your conversion tracking code. Add this code to your purchase confirmation/thank you page to track conversions. Replace the red highlighted fields with your actual order data.
    ​
    ​


    ​

  6. Save and publish the website changes in your site builder, CMS, or codebase.

  7. If you are installing Tolstoy on product pages, add the optional data-product-id attribute with the correct product ID so Tolstoy can recognize the page as a product page.

  8. If your site uses product-based Tolstoy experiences and you have not imported products yet, complete the Non-Shopify product setup, such as CSV product upload, before testing product-linked widgets.

  9. Open your website and confirm the page loads normally after the code is added.

  10. In Tolstoy, return to the Set up store page and click I completed all the steps when the installation is finished.

Troubleshooting / FAQs

Where should I place the Tolstoy code on my site?
Place it in the <head> section of your site or in a shared header template so it loads on the pages where Tolstoy should run.
​

What does data-product-id do?
​data-product-id is optional and is used on product pages to tell Tolstoy which product page the shopper is viewing. It should be the dynamic product ID of the product/page the customer is currently viewing, not a hardcoded value. The value should update automatically based on the page. For your setup, it should be your platform’s equivalent product variable.
​

What if I leave out data-product-id?
Tolstoy can still load on the site, but product-specific behavior may not work correctly on product pages if the widget expects product context.

Why is my widget not showing after installation?
Common reasons are that the site changes were not saved, Tolstoy code isn't properly pasted on site's <Head> seciton, the widget itself was not published yet, the widget-specific placement step was skipped, or the product context is missing on a product-based page.

Can I install Tolstoy on a non-Shopify website?
Yes. This setup flow is designed for native or manually managed sites that are not using the Shopify app-block installation path.

Did this answer your question?