touchstage-client

TouchStage Chat SDK

A customizable chat widget for providing interactive in-app tours and user guidance. Works with any web application without React dependencies.

Installation

npm install touchstage-client

Quick Start

// ES Modules
import { initChatWidget } from "touchstage-client";

// CommonJS
const { initChatWidget } = require("touchstage-client");

// Initialize the widget
await initChatWidget({
  apiKey: "YOUR_API_KEY",
  productId: "YOUR_PRODUCT_ID",
  userId: "USER_ID",
  userEmail: "[e-mail]", // Optional
  userName: "User Name", // Optional
  userRole: ["admin"], // Optional
  userPlan: "premium", // Optional
  userTenantId: "tenant-123", // Optional
  baseUrl: "https://api.yourcompany.com", // Optional - Custom API base URL
  isDarkMode: false, // Optional
  showChatButton: true, // Optional - controls chat button visibility
  initialVisible: false, // Optional - widget starts visible if true
  additionalData: {}, // Optional additional user data
});

Manual Integration via Script Tag

<!-- Add the JS -->
<script src="https://unpkg.com/touchstage-client/dist/chat-widget.umd.js"></script>

<script>
  window.initChatWidget({
    apiKey: "YOUR_API_KEY",
    productId: "YOUR_PRODUCT_ID",
    userId: "USER_ID",
    userEmail: "[e-mail]", // Optional
    userName: "User Name", // Optional
    userRole: ["admin"], // Optional
    userPlan: "premium", // Optional
    userTenantId: "tenant-123", // Optional
    baseUrl: "https://api.yourcompany.com", // Optional - Custom API base URL
    isDarkMode: false, // Optional
    showChatButton: true, // Optional
    initialVisible: false, // Optional
  });
</script>

Framework Integration Examples

Vue.js

<template>
  <div>
    <button @click="openChat">Open Chat</button>
  </div>
</template>

<script>
import {
  initChatWidget,
  openChatWidget,
  destroyChatWidget,
} from "touchstage-client";

export default {
  async mounted() {
    // Initialize widget when component mounts
    await initChatWidget({
      apiKey: "your-api-key",
      productId: "your-product-id",
      userId: this.$store.state.user.id,
      userEmail: this.$store.state.user.email,
      isDarkMode: this.$store.state.theme === "dark",
    });
  },
  methods: {
    async openChat() {
      await openChatWidget();
    },
  },
  async beforeUnmount() {
    // Clean up when component unmounts
    await destroyChatWidget();
  },
};
</script>

Angular

import { Component, OnInit, OnDestroy } from "@angular/core";
import {
  initChatWidget,
  openChatWidget,
  destroyChatWidget,
} from "touchstage-client";

@Component({
  selector: "app-root",
  template: '<button (click)="openChat()">Open Chat</button>',
})
export class AppComponent implements OnInit, OnDestroy {
  async ngOnInit() {
    // Initialize widget
    await initChatWidget({
      apiKey: "your-api-key",
      productId: "your-product-id",
      userId: "user-123",
      userEmail: "[e-mail]",
    });
  }

  async openChat() {
    await openChatWidget();
  }

  async ngOnDestroy() {
    // Clean up
    await destroyChatWidget();
  }
}

Svelte

<script>
  import { onMount, onDestroy } from 'svelte';
  import { initChatWidget, openChatWidget, destroyChatWidget } from "touchstage-client";

  onMount(async () => {
    // Initialize widget
    await initChatWidget({
      apiKey: 'your-api-key',
      productId: 'your-product-id',
      userId: 'user-123',
      userEmail: '[e-mail]'
    });
  });

  async function openChat() {
    await openChatWidget();
  }

  onDestroy(async () => {
    // Clean up
    await destroyChatWidget();
  });
</script>

<button on:click={openChat}>Open Chat</button>

React

import { useEffect } from "react";
import {
  initChatWidget,
  openChatWidget,
  destroyChatWidget,
} from "touchstage-client";

function App() {
  useEffect(() => {
    // Initialize widget
    initChatWidget({
      apiKey: "your-api-key",
      productId: "your-product-id",
      userId: "user-123",
      userEmail: "[e-mail]",
    });

    // Cleanup on unmount
    return () => {
      destroyChatWidget();
    };
  }, []);

  const openChat = async () => {
    await openChatWidget();
  };

  return (
    <div>
      <button onClick={openChat}>Open Chat</button>
    </div>
  );
}

Configuration Options

Parameter	Type	Required	Description
apiKey	string	Yes	Your TouchStage API key
productId	string	Yes	Your product ID from TouchStage dashboard
userId	string	Yes	Unique identifier for the current user
userEmail	string	No	User's email address
userName	string	No	User's display name
userRole	string[]	No	Array of user roles
userPlan	string	No	User's subscription plan
userTenantId	string	No	User's tenant/organization ID
baseUrl	string	No	Your product api base url
isDarkMode	boolean	No	Enable dark mode (default: false)
showChatButton	boolean	No	Show/hide chat button (default: true)
initialVisible	boolean	No	Start with widget visible (default: false)
additionalData	Record<string, any>	No	Any additional user data

API Reference

initChatWidget(config): Promise<void>

Initializes the chat widget with the provided configuration. Performs API health check and sets up the widget.

Parameters:

• config (InitConfig): Configuration object with required and optional properties

Returns: Promise that resolves when widget is successfully initialized

Throws: Error if API health check fails or required parameters are missing

setUserData(userData, widgetOptions?): void

Updates user data after initialization.

Parameters:

• userData (InitConfig): Updated user configuration
• widgetOptions (WidgetOptions, optional): Widget display options

openChatWidget(): Promise<boolean>

Opens/shows the chat widget.

Returns: Promise - true when widget is opened

closeChatWidget(): Promise<boolean>

Closes/hides the chat widget.

Returns: Promise - false when widget is closed

toggleChatWidget(): Promise<boolean>

Toggles the chat widget visibility.

Returns: Promise - new visibility state

isChatWidgetVisible(): Promise<boolean>

Checks if the chat widget is currently visible.

Returns: Promise - current visibility state

setBaseUrl(baseUrl): Promise<void>

Updates the API base URL.

Parameters:

• baseUrl (string): New API base URL

Returns: Promise

destroyChatWidget(): Promise<void>

Destroys the chat widget and cleans up resources.

Returns: Promise

Advanced Usage

Dynamic User Data Updates

// Using ES module import
import { setUserData } from "touchstage-client";

setUserData({
  apiKey: "your-api-key",
  productId: "your-product-id",
  userId: "new-user-id",
  userEmail: "[e-mail]",
  userRole: ["admin", "user"],
});

// Or using window object (for script tag loading)
window.setUserData({
  apiKey: "your-api-key",
  productId: "your-product-id",
  userId: "new-user-id",
  userEmail: "[e-mail]",
  userRole: ["admin", "user"],
});

Theme Management

// Initialize with dark mode
await initChatWidget({
  // ... other config
  isDarkMode: true,
});

Custom Base URL

// Use custom API endpoint
await initChatWidget({
  // ... other config
  baseUrl: "https://your-custom-api.com",
});

Integration Methods

Method 1: ES Module Import (Recommended for Frameworks)

import { initChatWidget, openChatWidget, closeChatWidget } from "touchstage-client";

await initChatWidget({...});
await openChatWidget();

Method 2: Script Tag (CDN Loading)

<script src="https://unpkg.com/touchstage-client/dist/chat-widget.umd.js"></script>
<script>
  window.initChatWidget({...});
  window.openChatWidget();
</script>

Error Handling

The widget includes built-in error handling and will throw errors for:

• Missing required configuration parameters (apiKey, productId, userId)
• API health check failures
• Network connectivity issues

Always wrap initialization in a try-catch block for production use:

try {
  await initChatWidget({
    apiKey: "YOUR_API_KEY",
    productId: "YOUR_PRODUCT_ID",
    userId: "USER_ID",
  });
  console.log("Widget initialized successfully");
} catch (error) {
  console.error("Failed to initialize widget:", error);
}

Browser Support

The widget supports all modern browsers:

• Chrome 60+
• Firefox 60+
• Safari 12+
• Edge 79+

Troubleshooting

Common Issues

• Widget not appearing: Check console for initialization errors
• API errors: Verify API key and product ID
• Styling conflicts: The widget uses CSS-in-JS to avoid conflicts

Debug Mode

Enable debug logging:

// Set debug mode in localStorage
localStorage.setItem("touchstage_debug", "true");

Support

For issues and questions:

• GitHub Issues: [TouchStage Repository]
• Documentation: [TouchStage Docs]
• Email: [e-mail]

Copyright

© TouchStage. All rights reserved.