# Universal Embed - for WooCommerce, BigCommerce, and any platform outside of Shopify
*Available on Analyst and above.*
KnoCommerce is fully platform agnostic. We currently work natively with Shopify and support all other platforms using this Universal Embed/Custom Integration. Official integrations will be coming with WooCommerce, BigCommerce, Magento, and others.
---
[Specific Use Cases of Universal Embed](#h_ab8519d3c1)
[Configure KnoCommerce](#h_2aa7f7fa55)
[Configure Custom Integration](#h_902de38b9d)
[Embed Script Snippet](#h_a1e189b7bf)
[Configure Brand Confirmation Page Code](#h_25879b8ae2)
[Minimum Script](#h_fcd7a0b25c)
[Minimum Script Instructions](#h_61c60af236)
[Highly Recommended Script Additions](#h_8edd995007)
[Full Script Variables](#h_f2792e726f)
[Obfuscating Customer Identifiers (Advanced)](#h_obfuscating_identifiers)
---
# Specific Use Cases of Universal Embed
All non-Shopify platforms use the technology and format described in this help doc. However, we have given more advanced instructions for some specific setups:
- [Google Tag Manager](https://docs.knocommerce.com/en/articles/8121139-getting-knocommerce-script-into-google-tag-manager)
- [BigCommerce (Optimized One-Page Checkout)](https://docs.knocommerce.com/en/articles/7939880-big-commerce-embed-optimized-one-page-checkout)
- [WooCommerce Extension](https://docs.knocommerce.com/en/articles/6150667-woocommerce-extension)
If you're looking for a particular solution on a particular platform, let us know about it by emailing KnoCommerce! We're always looking for recommendations, and if we have enough requests, we'll build it!
If you are using one of those platforms (or a custom build!), you can get started today with a custom script. Here's how to do that. 👇
---
# Start by Configuring KnoCommerce
## Set up Custom integration
**Step 1:** The first step in KnoCommerce is to log in to your account, go to the [Integrations page](https://app.knocommerce.com/main/settings/integrations), and click 'Connect' for the Custom integration.
**Step 2:** Next, you'll need to enter the store URL (the main page for your brand works best, i.e., [www.mybrandname.com](http://www.mybrandname.com)) and click Save.
**Step 3:** Once you save the Custom Integration, we will create an API Key that is associated with your account. It will live on the Custom Integration page, and have the format of XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX (format is a mixture of letters and numbers). Save this API Key for later; it will be called kno_id in your custom script setup -> kno_id = API Key.
---
## Find the Embed Script Snippet
**Step 4:** After you configure your custom integration and grab your API Key, you'll need to grab the embed script snippet from the KnoCommerce UI. Go to [Settings->Survey Settings](https://app.knocommerce.com/main/settings/embed) and navigate to the **Miscellaneous** tab. Then copy the Embed Script snippet and save it for later.
The snippet will look something like this:
```
```
---
# Configure Brand Confirmation Page Code
## Minimum Script
**Step 5:** Copy and paste the following ***minimum*** window.Kno JavaScript object into the code on the confirmation page.
This is the information that is REQUIRED to be passed from the brand to KnoCommerce so that our technology works correctly. We only recommend this be used for testing in staging environments, as there is more important information that is not required, but is very important for the functionality of certain features.
```
```
## Minimum Script Instructions
**Step 6:** Once you copy/paste the script into your store, you'll need to make some changes to it. Here are the changes you *need* to make:
- kno_id -> replace 'XXXX-XXXX-XXXX-XXXX' with your API Key found in Step 3
- customer.platform -> leave as 'CUSTOM' or change to the name of your brand's e-comm platform (i.e., 'Salesforce' or 'SFCC')
- customer.shop -> replace with your brand's static URL
- customer.email -> required (if no phone), replace with your platform's dynamic email variable
- customer.phone -> required (if no email), replace with your platform's dynamic phone variable
- order.id -> required (must be a string), replace with your platform order ID variable
- order.total_price -> required. Must be a number
- survey.selector -> required. Must be an HTML element on the confirmation page. We will add our survey widget as a sibling that will immediately follow the selector.
- script src -> required. Replace the full line with the full line you saved in Step 4
## Highly Recommended Script Additions
**Step 7:** Add the highly recommended attributes to the minimal script you already added to your confirmation page in Steps 5 & 6.
**Note:** These script additions are *not* required for the script to function correctly. You can collect survey responses without adding any additional attributes to the minimal script in Steps 5 & 6.
However, specific features within KnoCommerce depend on these attributes being present in the script, OR most brands realize they want these attributes because of what they allow you to do with your data in KnoCommerce.
- customer.lifetime_spent -> (number) replace with platform lifetime spend variable
- required to have a lifetime spend associated with survey responses in the [CSV Export](https://docs.knocommerce.com/en/articles/7208871-csv-exports)
- customer.lifetime_orders -> (number) replace with platform lifetime order count variable (order count = 1 is the customer's first order)
- required for lifetime orders, [Audiences](https://docs.knocommerce.com/en/articles/5555589-audiences) to show surveys to New Customers vs. Returning Customers
- required to have a lifetime order count associated with survey responses in the [CSV Export](https://docs.knocommerce.com/en/articles/7208871-csv-exports)
- order.total_price -> (number) replace with platform order total variable
- required for [Advanced Reports -> Order Attribution](https://app.knocommerce.com/main/reports/attribution) - check out [Order Attribution help doc](https://docs.knocommerce.com/en/articles/9135168-new-order-attribution-report)
- required for [Surveys -> Reports](https://app.knocommerce.com/main/data/) Attribution Report (settings toggle, then Attribution Reports)
- required for [Surveys -> Reports](https://app.knocommerce.com/main/data/) Pie Charts (settings toggle, then Pie Chart Reports)
- order.currency -> (string) default currency is USD. Change the currency to see reports in your store's currency
- order.customer_locale -> (string) formatted according to international country language standards
- We follow [Shopify's naming conventions for locales](https://shopify.dev/docs/themes/architecture/locales#name-locale-files), which uses the [IETF language tag nomenclature](https://en.wikipedia.org/wiki/IETF_language_tag)
- Required to use customer language for [Audiences](https://docs.knocommerce.com/en/articles/5555589-audiences) -> look at our [language survey help doc](https://docs.knocommerce.com/en/articles/7039009-target-survey-by-customer-language) for more info
- order.line_items -> The requirements for this are more complex, so we've created a [Custom Embed Line Items help doc](https://docs.knocommerce.com/en/articles/9273892-custom-embed-line-items-ingest) to explain
- required to utilize Product ID to create [Audiences](https://docs.knocommerce.com/en/articles/5555589-audiences) to filter data or send surveys to product purchasers
- order.product_category -> The requirements for product category/collection are more complex, so we've also created a [Product Category/Collection](https://docs.knocommerce.com/en/articles/9844925-product-category-collection) help doc to explain further
- required to utilize Product Category Title or Product Category ID Audiences for survey targeting or report filtering for specific product categories/collections
---
# Full Script Variables
Between the minimal required script attributes and the highly recommended attributes, you and your brand should be set up quite nicely to collect survey responses and utilize Kno's best features. But if you're super nerdy 🤓 like us and want to squeeze just a little bit more out of the integration, this section is for you.
Check out the full custom integration example file by clicking the button below. All possible variables that can be passed to KnoCommerce are included (though most are commented out at the bottom of the file).
[Download example html here](https://knocommerce.com/wp-content/uploads/2026/03/custom-example-scripthtml.zip)
---
# Obfuscating Customer Identifiers (Advanced)
**⚠️ This approach is not recommended as the default implementation.** It should only be used by brands with strict PII requirements. Please review the downsides below before proceeding.
The `customer.email` or `customer.phone` field is required because it serves as the customer identifier that powers survey targeting, event tracking, reporting, and retargeting behavior. At least one of these fields must be provided for the embed to function correctly.
For brands that need to avoid passing real customer PII, it is possible to create a synthetic email address using an internal customer ID. For example, if your internal customer ID is `125793468`, you could pass `125793468@yoursite.com` as the email value.
```
customer: {
platform: 'CUSTOM',
shop: 'yoursite.com',
email: '125793468@yoursite.com'
}
```
**Downsides:**
- **Survey Re-Exposure:** Customers who previously completed surveys under their real email or phone number will be treated as new respondents. They will see surveys again, which can result in inflated or double-counted survey data.
- **Breaks Third-Party Syncing:** This approach prevents data from syncing correctly to third-party integrations (e.g., Klaviyo, Yotpo) that rely on real customer identifiers like email or phone number to match customer profiles. If you plan to push survey data to other systems, this method will likely cause sync failures.
**⚠️ Again, this approach is not recommended unless you have strict PII requirements that outweigh the downsides listed above.** If you are unsure whether this is right for your use case, please reach out to our team before implementing it.
As always, if you need any clarification about anything in the file or this help doc, or you don't see something that you would like us to include, please let us know by emailing us at . We'd love to hear your questions and/or your feature requests!