Framework Guides

Modified on Thu, Nov 14 at 11:13 AM

One can integrate SurveyTale App Survey SDK into their app using multiple options!

Checkout the options below that we provide! If you are looking for something else, we would be glad to help.

Prerequisites

Before getting started, make sure you have:

A web application (behind your user authentication system) in your desired framework is set up and running.

A SurveyTale account with access to your environment ID and API host. You can find these in the Setup Checklist in the Settings.

HTML

All you need to do is copy a <script> tag to your HTML head, and that’s about it!

HTML
index.html
<!-- START Surveytale Surveys -->
<script type="text/javascript">
!function(){
    var apiHost = "https://app.surveytale.com";
    var environmentId = "<your-environment-id>";
    var userId = "<your-user-id>"; //optional
    var t=document.createElement("script");t.type="text/javascript",t.async=!0,t.src=apiHost+"/js/surveytale.umd.cjs";var e=document.getElementsByTagName("script")[0];e.parentNode.insertBefore(t,e),setTimeout(function(){window.surveytale.init({environmentId: environmentId, apiHost: apiHost, userId: userId})},500)}();
</script>
<!-- END Surveytale Surveys -->

Required customizations to be made

environment-id

SurveyTale Environment ID.

api-host

URL of the hosted SurveyTale instance.

Now visit the Validate your Setup section to verify your setup!

ReactJS

Install the SurveyTale SDK using one of the package managers ie npm,pnpm,yarn. Note that zod is required as a peer dependency must also be installed in your project.

Install Surveytale JS library

npm

npm install @surveytale/js zod

pnpm

pnpm add @surveytale/js zod

yarn

yarn add @surveytale/js zod

Now, update your App.js/ts file to initialise Surveytale.

src/App.js - JavaScript

// other imports
import surveytale from "@surveytale/js";


if (typeof window !== "undefined") {
  surveytale.init({
    environmentId: "<environment-id>",
    apiHost: "<api-host>",
    userId: "<user-id>", //optional
  });
}


function App() {
  // your own app
}


export default App;

Required customizations to be made

environment-id

SurveyTale Environment ID.

api-host

URL of the hosted Surveytale instance.

Now visit the Validate your Setup section to verify your setup!

NextJS

NextJs projects typically follow two main conventions: the App Directory and the Pages Directory. To ensure smooth integration with the Surveytale SDK, which operates solely on the client side, follow the guidelines for each convention below:

App directory: You will have to define a new component in app/surveytale.tsx file and call it in your app/layout.tsx file.
Pages directory: You will have to visit your _app.tsx and just initialise SurveyTale there.

Code snippets for the integration for both conventions are provided to further assist you.

Install Surveytale JS library

npm

npm install @surveytale/js zod

pnpm

pnpm add @surveytale/js zod

yarn

yarn add @surveytale/js zod

App Directory

app/surveytale.tsx
Typescript
"use client";


import { usePathname, useSearchParams } from "next/navigation";
import { useEffect } from "react";
import surveytale from "@surveytale/js";


export default function SurveytaleProvider() {
  const pathname = usePathname();
  const searchParams = useSearchParams();


  useEffect(() => {
    surveytale.init({
      environmentId: "<environment-id>",
      apiHost: "<api-host>",
      userId: "<user-id>", //optional
    });
  }, []);


  useEffect(() => {
    surveytale?.registerRouteChange();
  }, [pathname, searchParams]);


  return null;
}

app/layout.tsx
Typescript
// other imports
import SurveytaleProvider from "./surveytale";


export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <SurveytaleProvider />
      <body>{children}</body>
    </html>
  );
}

Pages Directory

src/pages/_app.tsx
Typescript
// other import
import { useRouter } from "next/router";
import { useEffect } from "react";
import surveytale from "@surveytale/js";


if (typeof window !== "undefined") {
  surveytale.init({
    environmentId: "<environment-id>",
    apiHost: "<api-host>",
    userId: "<user-id>", //optional
  });
}


export default function App({ Component, pageProps }: AppProps) {
  const router = useRouter();


  useEffect(() => {
    // Connect next.js router to Surveytale
    const handleRouteChange = surveytale?.registerRouteChange;
    router.events.on("routeChangeComplete", handleRouteChange);


    return () => {
      router.events.off("routeChangeComplete", handleRouteChange);
    };
  }, []);
  return <Component {...pageProps} />;
}

Required customizations to be made

environment-id

Surveytale Environment ID.

api-host

URL of the hosted Surveytale instance.

First we initialize the Surveytale SDK, ensuring that it only runs on the client side. To connect the Next.js router to Surveytale and ensure the SDK can keep track of every page change, we are registering the route change event.

Now visit the Validate your Setup section to verify your setup!

VueJs

Integrating the Surveytale SDK with Vue.js is a straightforward process. We will make sure the SDK is only loaded and used on the client side, as it's not intended for server-side usage.

Install Surveytale JS library

npm

npm install @surveytale/js

pnpm

pnpm add @surveytale/js

yarn

yarn add @surveytale/js

src/surveytale.js
JavaScript
import surveytale from "@surveytale/js";


if (typeof window !== "undefined") {
  surveytale.init({
    environmentId: "<environment-id>",
    apiHost: "<api-host>",
    userId: "<user-id>", //optional
  });
}


export default surveytale;

src/main.js
JavaScript
// other imports
import surveytale from "@/surveytale";


const app = createApp(App);


app.use(router);


app.mount("#app");


router.afterEach((to, from) => {
  if (typeof surveytale !== "undefined") {
    surveytale.registerRouteChange();
  }
});

Required customizations to be made

environment-id

SurveyTale Environment ID.

api-host

URL of the hosted SurveyTale instance.

Now visit the Validate your Setup section to verify your setup!

React Native

Install the Surveytale React Native SDK using one of the package managers, i.e., npm, pnpm, or yarn.

Install Surveytale JS library

npm

npm install @surveytale/react-native

pnpm

pnpm add @surveytale/react-native

yarn

yarn add @surveytale/react-native

Now, update your App.js/App.tsx file to initialize Surveytale:

src/App.js
JavaScript
// other imports
import Surveytale from "@surveytale/react-native";


const config = {
  environmentId: "<environment-id>",
  apiHost: "<api-host>",
  userId: "<user-id>",
};


export default function App() {
  return (
    <>
      {/* Your app content */}
      <Surveytale initConfig={config} />
    </>
  );
}

Required customizations to be made

environment-id

Surveytale Environment ID.

api-host

URL of the hosted Surveytale instance.

Validate your setup

Once you have completed the steps above, you can validate your setup by checking the Setup Checklist in the Settings. Your widget status indicator should go from this:

To this:

Debugging Surveytale Integration

Enabling Surveytale debug mode in your browser is a useful troubleshooting step for identifying and resolving complex issues. This section outlines how to activate debug mode, covers common use cases, and provides insights into specific debug log messages.

Activate Debug Mode

To activate Surveytale debug mode:

Via URL Parameter:

Enable debug mode mode by adding ?surveytaleDebug=true to your application's URL (e.g. https://example.com?surveytaleDebug=true or https://example.com?page=123&surveytaleDebug=true). This parameter will enable debugging for the current page.

View Debug Logs:

Open your browser's developer tools by pressing F12 or right-clicking and selecting "Inspect."
Navigate to the "Console" tab to view Surveytale debugging information.

How to Open Browser Console:

Google Chrome: Press F12 or right-click, select "Inspect," and go to the "Console" tab.
Firefox: Press F12 or right-click, select "Inspect Element," and go to the "Console" tab.
Safari: Press Option + Command + C to open the developer tools and navigate to the "Console" tab.
Edge: Press F12 or right-click, select "Inspect Element," and go to the "Console" tab.

Common Use Cases

Debug mode is beneficial for scenarios such as:

Verifying Surveytale initialization.
Identifying survey trigger issues.
Troubleshooting unexpected behavior.

Debug Log Messages

Debug log messages provide insights into:

API calls and responses.
Event tracking, survey triggers and form interactions.
Initialization errors.