@oncue-ai/cue-js-sdk v1.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

# Using npm
npm install cue-sdk

# Using yarn
yarn add cue-sdk

# Using pnpm
pnpm add cue-sdk

🔌 Quick Start

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:

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)

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

User Identification

// 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

// 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:

// 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

// 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:

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 file for a complete React integration example.

🛠️ Advanced Usage

Check out the 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.

💬 Support

If you have any questions or issues, please contact support at support@cuesdk.com or visit our documentation.

📄 License

CUE SDK is licensed under the MIT License. See the LICENSE file for details.