The Fairing script can be dropped onto a page to start collecting response data immediately. Your Fairing API Key and a customer ID/account ID are the only required fields to get up and running. There are additional optional fields that can be sent to enhance other features within Fairing, but are not required to collect responses.

The snippet includes a default styling. If you want to override any of the default styling, reach out to the Fairing team.

Install Fairing on your site

Paste the script below just before the closing </body> tag and replace CUSTOMER_ID with whatever internal ID uniquely identifies a customer or account, e.g. an email address. Fairing uses this ID to determine which questions a customer has answered and is available in exports to associate responses with your internal data.

<script>
  (function() {
    const API_KEY = "PUT API KEY HERE";
    const CUSTOMER_ID = "PUT YOUR CUSTOMER EMAIL OR USER ID HERE";
    const s = document.createElement("script");
    
    s.src = "https://sdk.fairing.co/sdk/1.0.0-beta/fairing-1.0.0-beta.js";
    s.type = "module";
    s.defer = true;
    s.onload = function() {
      window.Fairing = Fairing(API_KEY, CUSTOMER_ID);
      Fairing.nextQuestion();
    };

    document.head.appendChild(s);
  })();
</script>

After your page loads, the Fairing SDK will append a container element to the body element and initialize the Question Stream. If there is a question available for the customer it will be displayed – this depends on the Question Stream configuration.

❗️
All customers will see questions they haven't answered yet
By default, a question will display for all customers who haven't answered it yet. To target only specific customers–for example new customers–conditionally render the script tag above for only those customers.

Testing Fairing

Test Page Template

If you want to experiment with the Fairing SDK before integrating, you can use this test page template.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">

    <title>
      Fairing Test Page
    </title>

    <style>
      body {
        font-family: sans-serif;
      }
    </style>
  </head>
  <body>
    <script>
      (function() {
        const API_KEY = "PUT API KEY HERE";
        const CUSTOMER_ID = "PUT A TEST CUSTOMER ID OR EMAIL HERE";
        const s = document.createElement("script");
        const opts = {
          config: {
            test_mode: true
          }
        };

        s.src = "https://sdk.fairing.co/sdk/1.0.0-beta/fairing-1.0.0-beta.js";
        s.type = "module";
        s.defer = true;
        s.onload = function(e) {
          window.Fairing = Fairing(API_KEY, CUSTOMER_ID, opts);
          Fairing.nextQuestion();
        };

        document.head.appendChild(s);
      })();
    </script>
  </body>
</html>

Enabling Test Mode

The Fairing SDK supports a test mode. In test mode, the Question Stream functions as it normally would, but views and responses are not stored. This makes it easier to test the integration and styling without polluting your Fairing account with test data. In a production environment, it can be used to troubleshoot integration issues on your live site. Test mode can be enabled in two ways:

Pass a configuration option to the constructor

See Additional Configuration. If you pass the test_mode configuration option to the constructor, the SDK will initialize in test mode. This option is best for development and staging environments.

Manually callenableTestMode anddisableTestMode

The Fairing instance exposes enableTestMode and disableTestMode functions. To manually enable or disable test mode: in the browser, open the Dev console and call Fairing.enableTestMode() or Fairing.disableTestMode(). These functions change the setting and reload the page to start the SDK in the desired mode.

Logging

To reduce log noise, the Fairing SDK does not log to the development console by default. To enable logging, call Fairing.enableLogging() from the development console. To disable logging, call Fairing.disableLogging().

Additional Configuration Options

The SDK can be configured with additional options. The options are passed as the third argument to the Fairing constructor.

<script>
  ...
  const options = {
		customer: {...},
    container: ...,
    conversion: {...},
    integrations: {...},
    config: {}
  };
                                                  
  window.Faring = Faring(API_KEY, CUSTOMER_ID, options);
                                               ^^^^^^^
  ...
</script>

The options object has the following properties.

Name	Type	Details
customer	`object`	Details about the customer.
conversion	`object`	Details about the conversion event associated with this customer.
container	`DOMNode` or `String`	A DOM element to contain the Question Stream.
integrations	`object`	Integrations configuration.
config	`object`	Configuration for SDK functionality.

The `options.customer` Object

The customer object can be used to pass additional information about the customer or account to Fairing. Currently, the only supported property is email.

Name	Type	Details
email	`string`	The customer or company's email address.
order_count	`string`	Used to determine if a customer is new or returning. If this value is 1, the customer is considered new, if it is greater than one, the customer is considered returning.

The `options.conversion` Object

The conversionobject represents details of the conversion event associated with the customer or account. These details can be provided to enhance Fairing's reporting.

Name	Type	Details
country_code	`string`	The 2-letter ISO country code where the conversion took place. This could be the country of the customer's address.
coupon_amount	`number`	If a coupon was used, the amount of the coupon.
coupon_code	`string`	If a coupon was used, the coupon code.
coupon_type	`string`	If a coupon was used, the type of coupon used. `percent`if it was a percentage discount. `fixed` if a fixed amount was discounted.
created_at	`string`	The ISO-8601 timestamp in UTC when the conversion happened. Defaults to now.
id	`string`	The id of the conversion event or transaction.
landing_page_path	`string`	The initial landing page that led to the conversion.
locality	`string`	The city where the conversion happened. This could be the city of the customer's address.
number	`string`	A reference number assigned to the conversion or transaction, often customer-facing or user-facing. If a conversion `number` is not provided, the `id` will be used as its value.
postcode	`string`	The post code where the conversion happened. This could be the post code of the customer's address.
referring_url	`string`	The URL that referred the conversion.
region	`string`	The region (state/province) where the conversion happened. This could be the state or province of the customer's address.
total_value	`number`	The total value of the conversion, after the coupon is applied. This could be a plan price or other internal value assigned to the conversion.
last_click_utm_campaign	`string`	The last click UTM campaign that led to the conversion.
last_click_utm_content	`string`	The last click UTM content that led to the conversion.
last_click_utm_medium	`string`	The last click UTM medium that led to the conversion.
last_click_utm_source	`string`	The last click UTM source that led to the conversion.
last_click_utm_term	`string`	The last click UTM term that led to the conversion.

The `options.container` Property

By default, Fairing will append a container element to the document's body and render questions inside the container. The container is styled as a full screen modal and will only display if there is a question for the customer. To render the Question Stream in a different container element, pass a DOM node as the container property of the optionsobject. If there is a question to display for the current customer, the SDK will add a fairing-container--is-active class to the element so that it's visibility can be controlled via CSS. Be sure to declare the container-type: size CSS property on the container element. Fairing's CSS uses container queries based on the container size for its responsive design.

Example

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">

    <title>
      Fairing Test Page
    </title>

    <style>
      body {
        font-family: sans-serif;
      }
      
      /* Set the container-type property on the custom container
      #my_custom_container {
      	container-type: size;
      }
    </style>
  </head>
  <body>
    <!-- Add the custom container element to the DOM -->
    <div id="my_custom_container">
    </div>
    
    <script>
      (function() {
        const container = document.getElementById("my_custom_container");
        ...
        
        // Add the container as the value of the container property
        // on the options object
        const opts = {
          container: container
        };

        ...
        
        s.onload = function(e) {
          // Pass the options to the constructor to use the custom container
          window.Fairing = Fairing(API_KEY, CUSTOMER_ID, opts);
          Fairing.nextQuestion();
        };

        document.head.appendChild(s);
      })();
    </script>
  </body>
</html>

The `options.integrations` Object

The Fairing SDK can be configured to push events to Google Analytics, Google Tag Manager, or Rockerbox when a question is viewed or a response is provided. To enable these integrations, set the integrations property to true.

Name	Type	Details
`ga`	`boolean`	Enable the Google Analytics integration. Defaults to `false`.
`gtm`	`boolean`	Enable the Google Tag Manager integration. Defaults to `false`.
`rockerbox`	`boolean`	Enable the Rockerbox integration. Defaults to `false`.

<script>
  ...

	const options = {
    integrations: {  
  		ga: true,          // Set to true to fire Google Analytics events  
    	gtm: true,         // Set to true to fire Google Tag Manager events  
      rockerbox: true    // Set to true to fire Rockerbox events
    }
  }

  ...

  s.onload = function(e) {
    // Pass the options to the constructor to use the custom container
    window.Fairing = Fairing(API_KEY, CUSTOMER_ID, opts);
    Fairing.nextQuestion();
  };

</script>

The `options.config` Object

Name	Type	Details
`test_mode`	`boolean`	Enable test mode. Defaults to `false`.
`dismissible`	`boolean`	Allows questions to be dismissed if the SDK is displaying as a modal. Defaults to `false`.
`display_success_message`	`boolean`	Determines whether a thank you message is shown after all questions are answered. Defaults to `true`.

<script>
  ...

	const options = {
  	config: {
    	test_mode: true,                  // Enable test mode  
      dismissible: true,                // Allow question modal to be dismissed
      display_success_message: true     // Display thank you message
    }
  }

  ...

  s.onload = function(e) {
    // Pass the options to the constructor to use the custom container
    window.Fairing = Fairing(API_KEY, CUSTOMER_ID, opts);
    Fairing.nextQuestion();
  };

</script>

Custom Snippet

Install Fairing on your site

❗️
All customers will see questions they haven't answered yet

Testing Fairing

Test Page Template

Enabling Test Mode

Logging

Additional Configuration Options

The `options.customer` Object

The `options.conversion` Object

The `options.container` Property

The `options.integrations` Object

The `options.config` Object

Install Fairing on your site

❗️All customers will see questions they haven't answered yet

Testing Fairing

Test Page Template

Enabling Test Mode

Logging

Additional Configuration Options

The options.customer Object

The options.conversion Object

The options.container Property

The options.integrations Object

The options.config Object

❗️
All customers will see questions they haven't answered yet

The `options.customer` Object

The `options.conversion` Object

The `options.container` Property

The `options.integrations` Object

The `options.config` Object