Additional Configuration Options

The SDK can be configured with additional options. The options are passed as the third argument to the Fairing constructor (i.e. window.Faring = Faring(API_KEY, CUSTOMER_ID, opts)).

<script>
  ...
  const opts = {
    customer: {...},
    container: ...,
    conversion: {...},
    integrations: {...},
    config: {...}
  };
                                                  
  window.Faring = Faring(API_KEY, CUSTOMER_ID, opts);
  ...
</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 `opts.customer` Object

The customer object can be used to pass additional information about the customer or account to Fairing.

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 `opts.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/transaction or session.
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 `opts.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 opts 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 `opts.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 opts = {
    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 opts to the constructor to enable integrations
    window.Fairing = Fairing(API_KEY, CUSTOMER_ID, opts);
    Fairing.nextQuestion();
  };

</script>

The `opts.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 opts = {
    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 opts to the constructor to use the config options
    window.Fairing = Fairing(API_KEY, CUSTOMER_ID, opts);
    Fairing.nextQuestion();
  };

</script>

Additional Configuration Options

The opts.customer Object

The opts.conversion Object

The opts.container Property

The opts.integrations Object

The opts.config Object

The `opts.customer` Object

The `opts.conversion` Object

The `opts.container` Property

The `opts.integrations` Object

The `opts.config` Object