5 SDK Integration Best Practices for Maximum Chatbot Revenue

Introduction

You've integrated the Sponsy SDK—congratulations! But integration is just the beginning. The difference between a mediocre and a high-performing monetization setup often comes down to implementation details.

In this guide, we'll share five best practices that top-performing publishers use to maximize their chatbot revenue.

1. Timing: Call the API at the Right Moment

The most common integration mistake is calling the recommendation API too early or too late in the conversation.

Too Early (Bad)

// DON'T: Immediately after user sends first message
onUserMessage(msg) {
  sponsy.getRecommendation(msg);  // User hasn't shown intent yet
}

Too Late (Also Bad)

// DON'T: After the conversation is basically over
onUserLeave() {
  sponsy.getRecommendation(lastMessage);  // User is already leaving
}

Just Right ✓

// DO: After bot response, when context is complete
onBotResponse(userMsg, botResponse) {
  // Now we have full context for intent detection
  const rec = await sponsy.getRecommendation({
    userMessage: userMsg,
    assistantMessage: botResponse
  });
  
  if (rec) {
    appendToChat(rec.html);
  }
}

The ideal timing is after your bot generates a response but before rendering it to the user. This gives Sponsy the full context needed for accurate intent detection.

2. Context: Send the Right Amount of Information

Sending too little context leads to poor intent detection. Sending too much wastes bandwidth and processing time.

Minimum Required Context

const request = {
  userMessage: lastUserMessage,      // Required
  assistantMessage: lastBotResponse, // Required
  sessionId: currentSessionId        // Required for pacing
};

Optional but Recommended

const request = {
  userMessage: lastUserMessage,
  assistantMessage: lastBotResponse,
  sessionId: currentSessionId,
  metadata: {
    vertical: 'travel',      // Your app's vertical
    locale: 'en-US',         // User's locale
    platform: 'web'          // web, ios, android
  }
};

What NOT to Send

• Full conversation history (unnecessary)
• PII like email, name, phone (privacy violation)
• Sensitive data like payment info (security risk)

3. Caching: Don't Hit the API Unnecessarily

Every unnecessary API call adds latency and potentially wastes your rate limit.

Implement Session-Level Caching

class SponsyClient {
  private sessionRecommendations = new Map();
  private lastCallTime = 0;
  private MIN_INTERVAL = 3000; // 3 seconds
  
  async getRecommendation(context) {
    const now = Date.now();
    
    // Rate limit client-side
    if (now - this.lastCallTime < this.MIN_INTERVAL) {
      return null;
    }
    
    // Check session cache
    const cacheKey = hash(context.userMessage);
    if (this.sessionRecommendations.has(cacheKey)) {
      return this.sessionRecommendations.get(cacheKey);
    }
    
    this.lastCallTime = now;
    const rec = await sponsy.getRecommendation(context);
    
    if (rec) {
      this.sessionRecommendations.set(cacheKey, rec);
    }
    
    return rec;
  }
}

Benefits

• Faster response times
• Lower API usage
• Better user experience

4. Error Handling: Fail Gracefully

Your chat should never break because of a monetization error.

Robust Error Handling

async function showRecommendation(context) {
  try {
    const rec = await sponsy.getRecommendation(context);
    
    if (rec?.html) {
      appendToChat(rec.html);
      trackImpression(rec.id);
    }
  } catch (error) {
    // Log for debugging, but don't break the chat
    console.error('[Sponsy] Recommendation failed:', error.message);
    
    // Optionally report to your error tracking
    if (process.env.NODE_ENV === 'production') {
      Sentry.captureException(error);
    }
    
    // Continue chat flow normally
    // User never sees any error
  }
}

Timeout Handling

const TIMEOUT = 2000; // 2 seconds max

async function getWithTimeout(context) {
  const controller = new AbortController();
  const timeoutId = setTimeout(() => controller.abort(), TIMEOUT);
  
  try {
    const rec = await sponsy.getRecommendation(context, {
      signal: controller.signal
    });
    clearTimeout(timeoutId);
    return rec;
  } catch (error) {
    if (error.name === 'AbortError') {
      console.warn('[Sponsy] Request timed out');
      return null;
    }
    throw error;
  }
}

5. Tracking: Measure Everything That Matters

You can't optimize what you don't measure. Implement comprehensive tracking from day one.

Essential Events to Track

// 1. Impression - when recommendation is shown
function onShow(recommendation) {
  analytics.track('sponsy_impression', {
    recommendationId: recommendation.id,
    category: recommendation.category,
    position: 'inline'
  });
}

// 2. Click - when user clicks the recommendation
function onClick(recommendation) {
  analytics.track('sponsy_click', {
    recommendationId: recommendation.id,
    category: recommendation.category
  });
}

// 3. Dismiss - when user dismisses
function onDismiss(recommendation) {
  analytics.track('sponsy_dismiss', {
    recommendationId: recommendation.id,
    reason: 'user_closed'
  });
}

// 4. Timeout - when recommendation wasn't shown
function onTimeout() {
  analytics.track('sponsy_timeout', {
    context: 'api_slow'
  });
}

Metrics to Monitor

Bonus: A/B Testing Your Integration

Once you have the basics right, experiment to find optimal settings:

Variables to Test

• Recommendation position: Inline vs. after response
• Pacing: 2 per session vs. 3 per session
• Timing: Immediate vs. 1-second delay
• Style: Card vs. text vs. minimal

Simple A/B Test Setup

const variant = getABVariant(sessionId); // 'A' or 'B'

const config = {
  A: { delay: 0, maxPerSession: 2 },
  B: { delay: 1000, maxPerSession: 3 }
};

await sleep(config[variant].delay);
if (sessionCount < config[variant].maxPerSession) {
  showRecommendation();
}

// Track which variant for analysis
analytics.track('sponsy_abtest', { variant });

Checklist: Before You Go Live

Use this checklist to ensure your integration is production-ready:

• API key stored securely (not in client-side code)
• Session ID properly generated and tracked
• Error handling implemented
• Timeout handling implemented
• Client-side rate limiting in place
• Analytics events firing correctly
• Tested on mobile and desktop
• Tested with slow network conditions
• Verified disclosure labels are visible

Conclusion

A well-implemented SDK integration is the foundation of successful chatbot monetization. By following these five best practices:

1. Time your API calls correctly
2. Send the right amount of context
3. Implement smart caching
4. Handle errors gracefully
5. Track everything that matters

You'll maximize your revenue while maintaining a great user experience.

Questions about implementation? Reach out to our team at support@sponsyai.com or check our documentation.