UserLoop SDK
Integrating UserLoop SDK onto Your Website
This guide will walk you through the process of integrating the UserLoop SDK onto your website to display surveys and collect user feedback. You can embed a UserLoop survey anywhere, from a simple page, to a checkout process on an ecommerce platform.
You can optionally pass through details about a customer and their order to help to help with analyzing and segmenting your survey responses.
The quickest way to embed a survey is from the 'Embed' menu, which will generate the script for you.
Prerequisites
Before you start, make sure you have:
- Your UserLoop SURVEY_ID (found in your UserLoop account)
- A target DOM element in your HTML where you'd like to display the survey (e.g., <div id="userloop_survey"></div>)
Integration Steps
Add the UserLoop script to the <head> of your HTML:
<script src="https://cdn.userloop.io/sdk/prod/userloop.js"></script>Inside the <body> of your HTML, add this div where you would like the survey to appear. Alternatively, you can specify an existing div in the configuration below.
<div id="userloop_survey"></div>Basic configuration. For a basic setup of the survey, you need to include this script somwhere on your page to pass the required configuration options
<script>
const SURVEY_ID = '1659708896167x106729433200066560';
const TARGET_ELEMENT = document.getElementById('userloop_survey');
const CONFIG = {
email_collection: true,
};
// Include the rest of your configuration script here...
</script>Passing customer and order details through to UserLoop
You can pass through details about the customer and their order along with their survey response information by injecting information into the UserLoop tag.
##Customer and Transaction Data:
Below is a list of fields you can pass through to UserLoop.
customer: (object) An object containing customer information. Available properties include:
email: (string) The customer's email address.
id: (string) A unique identifier for the customer.
transaction: (object) An object containing transaction data. Available properties include:
currency: (string) The currency code for the transaction (e.g., 'USD').
coupon_code: (string) The coupon code used for the transaction, if applicable.
order_creation_date: (string) The date and time of the order creation (e.g., '2021-07-01T10:00:00.00Z').
transaction_id: (string) A unique identifier for the transaction.
total: (number) The total value of the order
utm_campaign: (string) The UTM campaign name associated with the transaction.
utm_content: (string) The UTM content associated with the transaction.
utm_medium: (string) The UTM medium associated with the transaction.
utm_source: (string) The UTM source associated with the transaction.
utm_term: (string) The UTM term associated with the transaction.
products: (array) An array of objects, each containing product information:
id: (string) A unique identifier for the product.
name: (string) The name of the product.
platform: (string) The e-commerce platform used for the transaction.
source: (string) The source of the transaction (e.g., 'website').
Example
Here's an example of the UserLoop SDK which is declaring customer and transaction values, you will need to inject your own values into this.
// Survey configuration and target div
const SURVEY_ID = 'YOUR_SURVEY_ID';
const TARGET_ELEMENT = document.getElementById('userloop_survey');
const CONFIG = {
email_collection: true,
};
// Customer data
const customer = {
email: 'CUSTOMER_EMAIL',
id: 'CUSTOMER_ID',
};
// Transaction data
const transaction = {
currency: 'TRANSACTION_CURRENCY',
coupon_code: 'COUPON_CODE',
order_creation_date: 'ORDER_CREATION_DATE',
transaction_id: 'TRANSACTION_ID',
total: TRANSACTION_TOTAL,
utm_campaign: 'UTM_CAMPAIGN',
utm_content: 'UTM_CONTENT',
utm_medium: 'UTM_MEDIUM',
utm_source: 'UTM_SOURCE',
utm_term: 'UTM_TERM',
products: [
{
id: 'PRODUCT_ID_1',
name: 'PRODUCT_NAME_1',
},
{
id: 'PRODUCT_ID_2',
name: 'PRODUCT_NAME_2',
},
],
platform: 'ECOMMERCE_PLATFORM',
source: 'WEBSITE_SOURCE',
};
// Initialize the UserLoop SDK
window.addEventListener('DOMContentLoaded', function () {
const UL = UserLoop(SURVEY_ID, TARGET_ELEMENT, CONFIG, {
transaction: transaction,
customer: customer,
});
UL.init();
});Example for Shopify
Below is an example of embedding a UserLoop Survey to any page in Shopify, all the relevant variables are populated with Shopify Liquid tags.
<div id="userloop_survey"></div>
<script>
const SURVEY_ID = '1659708896167x106729433200066560';
const TARGET_ELEMENT = document.getElementById('userloop_survey');
const CONFIG = {
email_collection: true,
};
{% if customer %}
const customer = {
email: '{{ customer.email | escape }}',
id: '{{ customer.id }}',
};
{% else %}
const customer = {};
{% endif %}
{% if order %}
const transaction = {
currency: '{{ order.currency | escape }}',
coupon_code: '{{ order.discount_code | escape }}',
order_creation_date: '{{ order.created_at | date: "%Y-%m-%dT%H:%M:%S.%LZ" }}',
transaction_id: '{{ order.order_number }}',
total: {{ order.total_price }},
// Add UTM parameters if available
products: [
{% for line_item in order.line_items %}
{
id: '{{ line_item.product_id }}',
name: '{{ line_item.title | escape }}',
},
{% unless forloop.last %},{% endunless %}
{% endfor %}
],
platform: 'Shopify',
source: 'website',
};
{% else %}
const transaction = {};
{% endif %}
// Wait for the DOM to be ready
window.addEventListener('DOMContentLoaded', function () {
const UL = UserLoop(SURVEY_ID, TARGET_ELEMENT, CONFIG, {
transaction: transaction,
customer: customer,
});
UL.init();
});
</script>Example for Woocommerce
Below is an example of embedding a UserLoop Survey to any page in Woocommerce, all the relevant variables are populated with Woocommerce handlebars tags.
<div id="userloop_survey"></div>
<script>
const SURVEY_ID = '1659708896167x106729433200066560';
const TARGET_ELEMENT = document.getElementById('userloop_survey');
const CONFIG = {
email_collection: true,
};
<?php
$customer_email = '';
$customer_id = '';
if ( is_user_logged_in() ) {
$current_user = wp_get_current_user();
$customer_email = $current_user->user_email;
$customer_id = $current_user->ID;
}
?>
const customer = {
email: '<?php echo esc_js( $customer_email ); ?>',
id: '<?php echo esc_js( $customer_id ); ?>',
};
<?php
if ( function_exists( 'wc_get_order' ) && isset( $_GET['order-received'] ) ) {
$order_id = intval( $_GET['order-received'] );
$order = wc_get_order( $order_id );
if ( $order ) {
$order_data = $order->get_data();
$products = [];
foreach ( $order->get_items() as $item ) {
$product = $item->get_product();
$products[] = [
'id' => $product->get_id(),
'name' => $product->get_name(),
];
}
$transaction = [
'currency' => $order_data['currency'],
'coupon_code' => implode( ', ', $order->get_coupon_codes() ),
'order_creation_date' => $order_data['date_created']->date( 'Y-m-d\TH:i:s.\L\Z' ),
'transaction_id' => $order_data['id'],
'total' => $order_data['total'],
'products' => $products,
'platform' => 'WooCommerce',
'source' => 'website',
];
}
}
?>
const transaction = <?php echo json_encode( $transaction ?? new stdClass() ); ?>;
// Wait for the DOM to be ready
window.addEventListener('DOMContentLoaded', function () {
const UL = UserLoop(SURVEY_ID, TARGET_ELEMENT, CONFIG, {
transaction: transaction,
customer: customer,
});
UL.init();
});
</script>Updated on: 26/04/2023
Thank you!