Feedback SDK for Web

Feedback SDK is a JavaScript library to collect user feedback through web browsers. The SDK supports multiple feedback form types including NPS, Satisfaction, Comment, Poll, and External Survey.

Installation

Option 1: NPM/Yarn Package

npm install @originallyus/feedback-web-sdk
# or
yarn add @originallyus/feedback-web-sdk

Then import it in your project:

import FeedbackSDK from "@originallyus/feedback-web-sdk";

Option 2: CDN (Browser)

Include the SDK script in your HTML. Replace <VERSION> with the version you want to use (e.g. v4.0.0):

<script src="https://cdnjs.originally.us/libs/feedback-web-sdk/v<VERSION>/feedbackSdk.min.js"></script>

Option 3: Manual Download

Download the built files from the libs directory and include them in your project:

• feedbackSdk.cjs.js - CommonJS format
• feedbackSdk.esm.js - ES Module format
• feedbackSdk.min.js - Browser UMD format (minified)

Content Security Policy (CSP)

If you're using Content Security Policy, add the following rules to allow the SDK to work:

script-src https://*.originally.us/
style-src https://*.originally.us/
img-src data: https://*.originally.us/
font-src https://*.originally.us/
connect-src https://*.originally.us/

Quick Start

Basic Usage

FeedbackSDK.Initialize(
  {
    appSec: "your-app-sec-here",
    packageId: "your.package.id",
    debug: false,
    language: "en",
    userId: "user123",
    eventTag: "page_view",
    metadata: { page: "homepage" },
  },
  function (didShown) {
    if (didShown) {
      console.log("Feedback form was shown");
    } else {
      console.log("No form was shown");
    }
  },
);

API Reference

Initialize

Initializes the Feedback SDK and displays the feedback form based on server-side configuration.

Syntax:

FeedbackSDK.Initialize(options, callback?)

Parameters:

| Parameter | Type | Required | Default | Description | | --------------- | ---------------- | -------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | appSec | string | Yes | X | Application security credential. Contact us to obtain this. | | packageId | string | Yes | X | Package identifier. Contact us to obtain this. | | debug | boolean | No | false | Enable debug mode. | | language | string | No | en | Language code (e.g., 'en', 'th', 'ms', 'ta'). | | userId | string \| null | No | X | User identifier for tracking | | eventTag | string | No | X | Event tag to associate with this feedback session | | event_tag | string | No | X | Alternative spelling for eventTag (legacy support) | | formSlug | string | No | X | Specific form slug to display (if configured in CMS) | | metadata | any | No | X | Additional metadata to send with the feedback | | deviceUuid | string | No | X | Custom device UUID (if not provided, SDK generates one) | | componentId | string | No | X | Custom component identifier | | backdropColor | string | No | transparent | Background overlay color and opacity when popup appears. Accepts any valid CSS color value (e.g., rgba(0,0,0,0.5), #00000080, transparent). The overlay creates a dimmed/blurred backdrop effect behind the popup (for screen width < 640). | | offsetTop | number | No | 50 | Distance in pixels from the top of the screen to the popup. Controls the vertical positioning of the popup when it appears (for screen width < 640). |

Callback Function:

function(didShown: boolean) => void

• didShown = true: Form was displayed and user completed or dismissed it
• didShown = false: No form was shown (due to timing rules, errors, etc.)

Example:

FeedbackSDK.Initialize(
  {
    appSec: "xxxxxxxxxxxxxxxx",
    packageId: "xx.xxxxxxxx.xxxxx",
    debug: false,
    language: "en",
    userId: "V12345678",
    eventTag: "redeem_event",
    formSlug: "alt_rating_form",
    metadata: "policy_987654321",
  },
  function (didShown) {
    if (didShown) {
      console.log("Form was shown");
      console.log("Form was shown");
    } else {
      console.log("No form was shown");
    }
  },
);

GetVersion

Returns the current SDK version number.

Syntax:

FeedbackSDK.GetVersion();

Returns: string - The SDK version number

Example:

const version = FeedbackSDK.GetVersion();
console.log("SDK Version:", version); // e.g., "4.0.0"

GetDidSubmit

Checks whether the user has submitted the feedback form. This function can be called at any time, but it's recommended to use it within the callback function.

Syntax:

FeedbackSDK.GetDidSubmit();

Returns: boolean - true if the form was submitted, false otherwise

Example:

FeedbackSDK.Initialize(
  {
    appSec: "xxx",
    packageId: "xxx",
    debug: false,
  },
  function (didShown) {
    if (didShown) {
      const didSubmit = FeedbackSDK.GetDidSubmit();
      if (didSubmit) {
        console.log("User submitted feedback!");
      } else {
        console.log("User dismissed the form");
      }
    }
  },
);

Inline View (Content Usefulness Survey)

For Content Usefulness surveys, you can display an inline version directly in your page content. The inline view will appear exactly where you place the custom element in your HTML/JSX.

How It Works

The SDK automatically registers the dfs-sdk-inline-view custom element when loaded. This is a native HTML custom element (Web Component) that can be used in any framework or vanilla HTML.

Important: The inline view will display at the exact location where you place the <dfs-sdk-inline-view /> element in your DOM. It will show the Content Usefulness survey buttons (e.g., "Yes" / "No" or custom button labels) when:

• The form type is configured as "Content Usefulness" in the CMS
• The inline view element is present in the DOM
• The form conditions are met (timing rules, etc.)
• You call FeedbackSDK.Initialize() with the appropriate options

Usage in React

In React applications, you can use the custom element directly:

import FeedbackSDK from "@originallyus/feedback-web-sdk";
import "@originallyus/feedback-web-sdk/libs/feedbackSdk.css";

function App() {
  useEffect(() => {
    // Initialize SDK
    FeedbackSDK.Initialize({
      appSec: "your-app-sec",
      packageId: "your.package.id",
      debug: false,
      language: "en",
      userId: "user123",
      eventTag: "page_view",
      formSlug: "content_usefulness-1", // Content Usefulness form
    });
  }, []);

  return (
    <div>
      <h1>My Article</h1>
      <p>Article content here...</p>

      {/* Inline view will appear here */}
      <dfs-sdk-inline-view cid="my-inline-view" />

      <p>More content below...</p>
    </div>
  );
}

TypeScript Support: The SDK includes TypeScript definitions for the custom element. If you get TypeScript errors, make sure you're importing the SDK types:

import "@originallyus/feedback-web-sdk";

Usage in HTML JavaScript

In plain HTML, simply add the custom element where you want the inline view to appear:

<!DOCTYPE html>
<html>
  <head>
    <link rel="stylesheet" href="path/to/feedbackSdk.css" />
    <script src="path/to/feedbackSdk.min.js"></script>
  </head>
  <body>
    <article>
      <h1>My Article</h1>
      <p>Article content here...</p>

      <!-- Inline view will appear here -->
      <dfs-sdk-inline-view cid="my-inline-view"></dfs-sdk-inline-view>

      <p>More content below...</p>
    </article>

    <script>
      // Initialize SDK
      FeedbackSDK.Initialize({
        appSec: "your-app-sec",
        packageId: "your.package.id",
        debug: false,
        language: "en",
        userId: "user123",
        eventTag: "page_view",
        formSlug: "content_usefulness-1", // Content Usefulness form
      });
    </script>
  </body>
</html>

Custom Element Props

The <dfs-sdk-inline-view /> custom element accepts the following props:

| Prop | Type | Required | Default | Description | | ----- | -------- | -------- | ------- | --------------------------------------------------------------------------------- | | cid | string | No | | Custom component ID. Use this to identify multiple inline views on the same page. |

Example with custom ID:

<dfs-sdk-inline-view cid="article-feedback-123" />

Positioning

The inline view will appear exactly where you place <dfs-sdk-inline-view /> in your DOM structure.

Complete Example (React)

import { useEffect, useState } from "react";
import FeedbackSDK from "@originallyus/feedback-web-sdk";
import "@originallyus/feedback-web-sdk/libs/feedbackSdk.css";

function ArticlePage() {
  const [sdkInitialized, setSdkInitialized] = useState(false);

  useEffect(() => {
    // Initialize SDK
    FeedbackSDK.Initialize(
      {
        appSec: "your-app-sec",
        packageId: "your.package.id",
        debug: true, // Set to true for testing
        language: "en",
        userId: "user123",
        eventTag: "article_view",
        formSlug: "content_usefulness-1", // Content Usefulness form
        metadata: { articleId: "123" },
      },
      (didShown) => {
        console.log("Inline view shown:", didShown);
        setSdkInitialized(true);
      },
    );
  }, []);

  return (
    <div>
      <header>
        <h1>My Article Title</h1>
      </header>

      <main>
        <article>
          <p>
            This is the article content. The inline view will appear right after
            this paragraph.
          </p>

          {/* Inline view appears here */}
          <dfs-sdk-inline-view cid="article-feedback" />

          <p>More article content continues below the inline view.</p>
        </article>
      </main>

      <footer>
        <p>Footer content</p>
      </footer>
    </div>
  );
}

Notes

• The inline view uses the same initialization options as the popup form
• Only Content Usefulness form types will display in the inline view
• The inline view will automatically show/hide based on server-side configuration and timing rules
• In debug mode (debug: true), the inline view will always appear when the form is available
• The inline view is responsive and will adapt to your page's styling

Debug Mode vs Production Mode

Debug Mode (debug: true)

• The feedback form is always shown when Initialize() is called
• Useful for testing and development
• Shows error messages via alerts and console logs

Production Mode (debug: false)

• The feedback form may not be shown every time
• Form display is controlled by server-side rules:
  • Frequency limits (once per hour/day/week)
  • User eligibility
  • Form availability
• This is expected behavior - the form only appears when conditions are met

Important: If the form doesn't appear in production mode, it's not a bug. The server determines when to show the form based on your configuration.

Delayed Form Display

The SDK supports delayed form display with the following features:

• Delay Time: Form can be configured to appear after a specific number of seconds
• Expiry Time: Delay configuration expires after a set time period
• Persistence: Delay state is saved in localStorage and persists across page reloads

The SDK automatically handles:

• Calculating remaining delay time after page reload
• Removing expired delay configurations
• Showing forms immediately if delay time has passed

Form Types

The SDK supports multiple feedback form types:

1. NPS (Net Promoter Score) - 0-10 rating scale
2. Satisfaction - 1-5 star rating
3. Comment - Free text feedback
4. Poll - Multiple choice questions
5. External Survey - Redirect to external survey URL

The form type is determined by your server-side configuration.

Error Handling

The SDK handles errors gracefully:

• Network errors: Form is hidden, callback is triggered with didShown = false
• Invalid configuration: Error logged, form is hidden
• Missing credentials: Warnings logged to console

In debug mode, errors are also displayed via browser alerts.

Browser Support

The SDK supports modern browsers:

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)