Sponsored Messaging SDK

SDK for interacting with the Sponsored Messaging API, with support for multiple JavaScript frameworks.

Installation

npm install sponsored-messaging-sdk
# or
yarn add sponsored-messaging-sdk

Usage

Vanilla JavaScript

ES Module Import

import SponsoredMessaging from 'sponsored-messaging-sdk';

const sdk = new SponsoredMessaging({
  apiBaseUrl: 'https://your-api-url.com',
  sourceAppId: 'your-app-id',
  chatContainerId: 'chatArea',
  sponsorshipMode: 'chat' // or 'message'
});

// Check sponsorship for a message
async function checkMessageSponsorship(userMessage, aiResponse) {
  try {
    const result = await sdk.checkSponsorship({
      userMessage,
      aiResponse
    });
    
    console.log('Is sponsored:', result.isSponsored);
    if (result.isSponsored) {
      console.log('Sponsor details:', result.sponsorDetails);
    }
    
    return result;
  } catch (error) {
    console.error('Error checking sponsorship:', error);
    return { isSponsored: false };
  }
}

Script Tag (UMD)

<script src="https://cdn.example.com/sponsored-messaging-sdk.umd.min.js"></script>
<script>
  const sdk = new SponsoredMessaging({
    apiBaseUrl: 'https://your-api-url.com',
    sourceAppId: 'your-app-id',
    chatContainerId: 'chatArea',
    sponsorshipMode: 'chat'
  });
  
  // Use the SDK as needed
</script>

React Integration

import React from 'react';
import { SponsoredMessagingProvider, useSponsoredMessaging } from 'sponsored-messaging-sdk';

// Wrap your app or component with the provider
function App() {
  return (
    <SponsoredMessagingProvider
      apiBaseUrl="https://your-sponsorship-api.com"
      sourceAppId="my-react-app"
      chatContainerId="chat-container"
      sponsorshipMode="message"
    >
      <ChatComponent />
    </SponsoredMessagingProvider>
  );
}

// Use the SDK in any child component
function ChatComponent() {
  const sdk = useSponsoredMessaging();
  const [messages, setMessages] = useState([]);
  
  const sendMessage = async (userMessage) => {
    // Add user message to chat
    setMessages(prev => [...prev, { type: 'user', content: userMessage }]);
    
    // Simulate AI response
    const aiResponse = `This is a response about "${userMessage}"`;
    
    try {
      // Check sponsorship
      const result = await sdk.checkSponsorship({
        userMessage,
        aiResponse,
        userSessionId: localStorage.getItem('user_session_id')
      });
      
      // Handle the result
      if (result.isSponsored) {
        setMessages(prev => [...prev, { 
          type: 'sponsored', 
          content: result.rawContent,
          sponsorData: result
        }]);
      } else {
        setMessages(prev => [...prev, { 
          type: 'ai', 
          content: result.rawContent || aiResponse 
        }]);
      }
    } catch (error) {
      console.error('Error checking sponsorship:', error);
      setMessages(prev => [...prev, { type: 'ai', content: aiResponse }]);
    }
  };
  
  return (
    <div id="chat-container">
      {/* Chat UI */}
    </div>
  );
}

API Reference

new SponsoredMessaging(options)

Initializes the SDK.

• options (Object): Configuration options.
  • apiBaseUrl (String, required): The base URL for the Sponsored Messaging API.
  • sourceAppId (String, required): Identifier for the source application using the SDK.
  • chatContainerId (String, required): The ID of the HTML element containing chat messages.
  • sponsorshipMode (String, optional): How to display sponsorship ('message' or 'chat'). Defaults to 'message'.

checkSponsorship(options)

Checks if a given AI response should be replaced with sponsored content.

• options (Object): Details for the sponsorship check.
  • userMessage (String, required): The user's input message.
  • aiResponse (String, required): The AI's generated response.
  • userSessionId (String, optional): A unique identifier for the user's session.
  • sourceAppId (String, optional): An identifier for the application using the SDK.
• Returns: Promise<Object> - Resolves with the API response or a default object { isSponsored: false, rawContent: aiResponse } on failure.

trackClick(options)

Tracks a user click on sponsored content.

• options (Object): Details for tracking the click.
  • campaignId (String, required): The ID of the campaign associated with the clicked content.
  • userSessionId (String, optional): A unique identifier for the user's session.
  • sourceAppId (String, optional): An identifier for the application using the SDK.
• Returns: Promise<void> - Resolves when the tracking request is sent. Errors are logged silently.

React Components

<SponsoredMessagingProvider>

React context provider that initializes the SDK and makes it available to child components.

• Props:
  • apiBaseUrl (String, required): The base URL for the Sponsored Messaging API.
  • sourceAppId (String, required): Identifier for the source application using the SDK.
  • chatContainerId (String, required): The ID of the HTML element containing chat messages.
  • sponsorshipMode (String, optional): How to display sponsorship ('message' or 'chat'). Defaults to 'message'.
  • children (ReactNode): Child components that will have access to the SDK.

useSponsoredMessaging()

React hook to access the SDK instance from any component within a SponsoredMessagingProvider.

• Returns: The initialized SponsoredMessaging instance.

Build Formats

The SDK is available in multiple formats:

• ESM (dist/sponsored-messaging-sdk.esm.js): For modern bundlers and environments that support ES modules.
• CommonJS (dist/sponsored-messaging-sdk.cjs.js): For Node.js and bundlers that support CommonJS.
• UMD (dist/sponsored-messaging-sdk.umd.js): For direct use in browsers via script tags.
• UMD (minified) (dist/sponsored-messaging-sdk.umd.min.js): Minified version for production use in browsers.