Deway Web SDK

A lightweight TypeScript SDK for adding an AI-powered user engagement engine by Deway to your web app.

Quick Install with AI Assistant

Copy and paste this prompt to your AI coding assistant (Claude, Copilot, etc.) to get Deway set up with best practices:

Install and integrate the Deway Web SDK (@deway-ai/web-sdk) into my project.

PACKAGE INFO:
- Name: @deway-ai/web-sdk
- Purpose: Lightweight TypeScript SDK that adds an AI-powered user engagement engine
- Supports: React, Next.js, Vue, Nuxt, Angular, and vanilla JS
- Includes full TypeScript definitions

TASKS:
1. Detect my framework and package manager (npm, pnpm, or yarn) from lock files
2. Install the SDK using the detected package manager
3. For vanilla JS/HTML projects: Use the CDN script instead:
   <script src="https://unpkg.com/@deway-ai/web-sdk/dist/loader.umd.js"></script>
4. Initialize early in the app lifecycle (use appropriate lifecycle hook for the framework):
   - Import: import Deway from '@deway-ai/web-sdk'
   - Call Deway.init() with the appKey:
     Deway.init({ appKey: 'your-deway-app-key' })
5. Identify users after authentication:
   if (user?.id) Deway.identify(user.id);

IMPLEMENTATION NOTES:
- Follow my existing project structure and code style conventions
- Use appropriate lifecycle hooks: React (useEffect), Vue (onMounted), Angular (ngOnInit)

FIRST analyze my project structure and detect the framework and package manager. Then and only then implement the Deway Web SDK integration accordingly.

Installation

npm install @deway-ai/web-sdk
# or
pnpm add @deway-ai/web-sdk
# or
yarn add @deway-ai/web-sdk

Quick Start

Basic Integration

import Deway from '@deway-ai/web-sdk';

// Initialize the SDK
Deway.init({
    appKey: 'your-app-key'
});

// Identify a user
Deway.identify('user-123');

Note: Deway.init() must be called before other methods. User identification via Deway.identify() enables activity tracking.

HTML/JavaScript Integration

<script src="https://unpkg.com/@deway-ai/web-sdk/dist/loader.umd.js"></script>
<script>
    Deway.init({
        appKey: 'your-app-key'
    });

    Deway.identify('user-123');
</script>

Configuration

Deway.init({
    appKey: string,                               // Required: Your Deway app key
    apiEndpoint: string | undefined,              // Optional: Custom API endpoint
    wsEndpoint: string | undefined,               // Optional: Custom WebSocket endpoint
    isDevelopment: boolean | undefined,           // Optional: Enable dev mode logging (default: false)
    autoShowBookmark: boolean | undefined,        // Optional: Auto-show bubble (default: true)
    bubbleConfig: BubbleConfig | undefined,       // Optional: Bubble appearance customization
});

BubbleConfig

Customize the chat bubble appearance:

interface BubbleConfig {
    position?: BubblePosition;  // Position on screen
}

enum BubblePosition {
    BOTTOM_LEFT = "bottom-left",
    BOTTOM_RIGHT = "bottom-right"  // default
}

Example with Custom Configuration

Deway.init({
    appKey: 'your-app-key',
    isDevelopment: true,
    autoShowBookmark: true,
    bubbleConfig: {
        position: 'bottom-left'
    }
});

API Reference

Deway.init(config)

Initialize the SDK with configuration options. Must be called before using other methods.

Deway.identify(userId)

Associate a user ID with the current session for personalized experiences.

Deway.reportEvent(name, params)

Report a custom event with the given name and parameters.

Parameters:

• name (string): Event name (will be normalized: trimmed, lowercased, special characters replaced with underscores)
• params (object): Event parameters as a plain object

Example:

Deway.reportEvent('Product Purchased', {
    product_id: 'ABC-123',
    quantity: 5,
    price: 99.99
});
// Event sent with normalized name: "product_purchased"

Deway.setUserProfile(userProfile)

Set or update the user profile for the currently identified user.

Parameters:

• userProfile (object): User profile data as a plain object. Can contain any JSON-serializable properties.

Example:

Deway.setUserProfile({
    name: 'Jane Doe',
    email: '[email protected]',
    age: 28,
    preferences: {
        theme: 'dark',
        notifications: true
    }
});

Notes:

• Profile is upserted (created if new, replaced if exists)
• Profile data completely replaces existing profile on each call

Deway.showBookmark(config?)

Show the AI chat bookmark. Optional configuration for appearance customization.

Deway.hideBookmark()

Hide the AI chat bookmark.

Deway.isBookmarkVisible()

Check if the bookmark is currently visible.

Deway.destroy()

Clean up SDK resources and stop all tracking.

Framework Examples

React

import {useEffect} from 'react';
import Deway from '@deway-ai/web-sdk';

function App() {
    useEffect(() => {
        Deway.init({
            appKey: 'your-app-key'
        });

        // Identify user when available
        if (user?.id) {
            Deway.identify(user.id);
        }
    }, [user?.id]);

    return <div>Your App</div>;
}

Vue

<script setup>
  import {onMounted} from 'vue';
  import Deway from '@deway-ai/web-sdk';

  onMounted(() => {
    Deway.init({
      appKey: 'your-app-key'
    });
  });
</script>

Angular

import {Component, OnInit} from '@angular/core';
import Deway from '@deway-ai/web-sdk';

@Component({
    selector: 'app-root',
    template: '<div>Your App</div>'
})
export class AppComponent implements OnInit {
    ngOnInit() {
        Deway.init({
            appKey: 'your-app-key'
        });
    }
}

Features

• AI-powered user engagement and assistance: Interactive chat interface for user support
• Automatic user behavior analysis: Intelligent tracking and understanding of user interactions
• Framework-agnostic integration: Works with React, Vue, Angular, and vanilla JavaScript
• Full TypeScript support: Complete type definitions included
• Lightweight: Minimal bundle size impact

Edge Cases & Internal Behavior

Error Handling

The SDK handles all errors internally. Callers don't need try-catch blocks around SDK methods. Failed operations are logged to the console and retried automatically when appropriate.

State Persistence

User identification and settings persist across page reloads via localStorage. Once a user is identified, they remain identified until Deway.destroy() is called or localStorage is cleared.

Multiple init() Calls

Calling Deway.init() multiple times is safe. Subsequent calls after the first are ignored.

Automatic Retries

Failed API calls and uploads are automatically retried with exponential backoff. No manual intervention required.

Call Queue

All SDK calls should be called after the SDK is initialized via Deway.init(), and the user is identified via Deway.identify(). In case a call is made before init or identify the SDK queues the call internally and eventually executed once the prerequisite calls were made.

Troubleshooting

Bubble doesn't appear

• Check autoShowBookmark is set to true OR manually call Deway.showBookmark()
• Verify Deway.init() was called with valid appKey
• Check browser console for initialization errors

User identification not working

• Ensure Deway.init() is called before Deway.identify()
• User ID must be non-empty string
• Check browser console for error logs