npm package: @oncue-ai/cue-js-sdk
Description: A powerful and easy-to-use SDK for AI applications to integrate contextual ads
Author: Oncue AI
Latest version: 1.0.0

# CUE SDK 

A powerful and easy-to-use TypeScript SDK for integrating contextual ads into your AI applications.

## 🚀 Features

- **Easy Integration**: Get up and running with just a few lines of code
- **TypeScript First**: Built with TypeScript for excellent type safety and developer experience
- **Contextual Ads**: Display relevant, non-intrusive ads based on the current context
- **Multiple Ad Formats**: Support for text, banner, and native ad formats
- **Advanced Targeting**: Target ads based on user interactions and content
- **Analytics**: Built-in event tracking for insights and optimization
- **Privacy-Focused**: GDPR & CCPA compliant with user consent management
- **Framework Agnostic**: Works with any JavaScript framework (React, Vue, Angular, etc.)
- **Modular Design**: Use only what you need to keep your bundle size small

## 📦 Installation

```bash
# Using npm
npm install cue-sdk

# Using yarn
yarn add cue-sdk

# Using pnpm
pnpm add cue-sdk
```

## 🔌 Quick Start

```typescript
import { CueSDK } from 'cue-sdk';

// Initialize the SDK
const cue = new CueSDK({
  publisherId: 'your-publisher-id',
});

// Set the current context for better ad targeting
cue.setContext({
  query: 'how to build a website',
  keywords: ['website', 'development', 'html']
});

// Display an ad in a container
cue.ui.createAndRenderAd({
  parent: 'ad-container',
  placement: 'contextual',
  format: 'text'
});
```

## 📚 Documentation

### Initialization

Initialize the SDK with your publisher ID and options:

```typescript
import { CueSDK } from 'cue-sdk';

const cue = new CueSDK({
  publisherId: 'your-publisher-id',      // Required
  debug: true,                          // Optional: Enable debug logging
  autoInitialize: true,                 // Optional: Automatically initialize the SDK
  adPlacement: 'contextual',            // Optional: Default ad placement style
  onInitialized: (sdk) => {             // Optional: Callback when SDK is initialized
    console.log('SDK initialized!');
  }
});

// If autoInitialize is false, you need to call initialize manually:
cue.initialize().then(() => {
  console.log('SDK initialized!');
}).catch(error => {
  console.error('Failed to initialize SDK:', error);
});
```

### Ad Formats

CUE SDK supports the following ad formats:

- **Text**: Simple text-based ads with a title, description, and call to action
- **Banner**: Image-based ads perfect for headers, footers, or sidebar placements
- **Native**: Rich ad units that blend seamlessly with your application's look and feel

### User Consent (GDPR/CCPA)

```typescript
// Set user consent preferences
cue.setConsent({
  advertising: true, // Allow personalized advertising
  analytics: true    // Allow analytics tracking
});
```

### User Identification

```typescript
// Identify a logged-in user
cue.user.identify('user-123', {
  email: 'user@example.com',
  name: 'John Doe',
  plan: 'premium'
});

// Update user traits
cue.user.setTraits({
  preferences: {
    theme: 'dark',
    notifications: 'weekly'
  }
});

// Log out a user
cue.user.logout();
```

### Context Setting

```typescript
// Set the current context for better ad targeting
cue.setContext({
  query: 'how to build a website',
  page: 'search-results',
  keywords: ['website', 'development', 'html', 'css'],
  custom: {
    category: 'web-development',
    difficulty: 'beginner'
  }
});
```

### Displaying Ads

There are multiple ways to display ads:

```typescript
// Method 1: Request and render an ad in a specified container
cue.ads.requestAd({
  placement: 'contextual',
  format: 'text',
  container: 'ad-container'
});

// Method 2: Create and render in one step
cue.ui.createAndRenderAd({
  parent: document.getElementById('content'),
  placement: 'banner',
  format: 'banner'
});

// Method 3: Request an ad and handle it yourself
cue.ads.requestAd({
  placement: 'sidebar',
  format: 'native',
  onAdLoaded: (adData) => {
    console.log('Ad loaded:', adData);
    // Render it manually or use SDK
    cue.ads.renderAd('my-container', adData);
  }
});
```

### Analytics

```typescript
// Track custom events
cue.analytics.trackEvent('button_click', {
  button_id: 'sign-up',
  page: 'landing'
});

// Ad impressions and clicks are tracked automatically
```

## ⚛️ React Integration

CUE SDK provides a simple way to integrate with React:

```tsx
import React from 'react';
import { CueProvider, CueAd, useCue } from 'cue-sdk/react';

function App() {
  return (
    <CueProvider publisherId="your-publisher-id">
      <div className="app">
        <header>
          <h1>My App</h1>
        </header>
        
        <main>
          <div className="content">
            <h2>Content</h2>
            <p>This is the main content of the page.</p>
            
            {/* Display a contextual text ad */}
            <CueAd placement="contextual" format="text" />
          </div>
          
          <aside className="sidebar">
            {/* Display a native ad in the sidebar */}
            <CueAd placement="sidebar" format="native" />
          </aside>
        </main>
      </div>
    </CueProvider>
  );
}
```

See the [examples/react-integration.tsx](./examples/react-integration.tsx) file for a complete React integration example.

## 🛠️ Advanced Usage

Check out the [examples](./examples) directory for more detailed usage examples.

## 📊 Dashboard

Monitor your ad performance, manage campaigns, and analyze user engagement through our comprehensive dashboard at [dashboard.cuesdk.com](https://dashboard.cuesdk.com).

## 💬 Support

If you have any questions or issues, please contact support at support@cuesdk.com or visit our [documentation](https://docs.cuesdk.com).

## 📄 License

CUE SDK is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.