Partner Integration Guide

Quick Start (5 Minutes)

  1. Get Your Partner Key
    Contact contact@humsana.com to receive your unique API key and dashboard access.
  2. Add Our SDK

    Choose your preferred installation method:

    Option 1: CDN (Quickest)

    <script src="https://humsana.com/static/humsana-lite.js"></script> <script> const humsana = new HumsanaLite({ partnerKey: 'partner_hum_YOUR_KEY' }); </script>

    Option 2: NPM Package

    # Install the package npm install @humsana/sdk-lite # In your JavaScript: import HumsanaLite from '@humsana/sdk-lite'; const humsana = new HumsanaLite({ partnerKey: 'partner_hum_YOUR_KEY' });
    3. <script> const humsana = new HumsanaLite({ partnerKey: 'partner_hum_YOUR_KEY' }); </script>
  • Start Using Context
    Your AI can now access real-time behavioral context for smarter responses.

    • Integration Overview

    Humsana provides real-time behavioral context to make your AI assistant smarter. Your users don't need to sign up or install anything - just add our SDK and start delivering better AI experiences.

    Two Integration Modes

    SDK Lite (Start Here)

    Setup: 5 minutes
    User action required: None
    Accuracy: ~70%

    What your AI gets:

    SDK Auth (Enhanced Mode)

    Setup: User connects platforms (optional)
    User action required: OAuth consent
    Accuracy: ~95%

    Upgrade Flow from SDK Lite to SDK0Auth for your users

    Partners can use our hosted upgrade page to convert SDK Lite users to OAuth:

    // Option 1: Redirect to hosted upgrade page window.location.href = 'https://humsana.com/static/upgrade.html?partner=YOUR_KEY&user=USER_ID'; // Option 2: Open in popup window.open('https://humsana.com/static/upgrade.html?partner=YOUR_KEY&user=USER_ID', 'upgrade', 'width=800,height=600');

    Additional context available:

    API Reference

    Authentication

    Include your partner key in all requests:

    X-Partner-Key: partner_hum_YOUR_KEY

    Base URL

    https://humsana.com

    Core Endpoints

    Get Context (Lite)

    GET /api/v4/sdk/context/lite

    curl https://humsana.com/api/v4/sdk/context/lite \ -H "X-Partner-Key: partner_hum_xxx"

    Response:

    { "focus_score": 0.75, "interruptible": true, "energy_level": 0.6, "break_needed": false, "session_intensity": 0.4 }

    Get Context (Enhanced)

    GET /api/v4/sdk/context/auth

    Returns enhanced context when user has connected platforms.

    curl https://humsana.com/api/v4/sdk/context/auth \ -H "X-Partner-Key: partner_hum_xxx" \ -H "X-User-Key: user_123"

    Check Enhancement Benefits

    GET /api/v4/sdk/context/diff

    Shows the improvement users would get by connecting platforms.

    { "current_quality": 0.3, "potential_quality": 0.85, "improvement_factor": 2.8 }

    JavaScript SDK

    Initialization

    const humsana = new HumsanaLite({ partnerKey: 'partner_hum_YOUR_KEY', privacyLevel: 'standard', // minimal, standard, or rich debug: false });

    Methods

    // Get current context const context = await humsana.getContext(); // Check enhancement benefits const upgrade = await humsana.getUpgradeIncentive(); // Control tracking humsana.pause(); humsana.resume(); // Clean up humsana.destroy();

    Implementation Examples

    Adaptive AI Responses

    async function getAIResponse(userQuery) { const context = await humsana.getContext(); if (!context.interruptible) { // User is focused - keep it brief return generateConciseResponse(userQuery); } if (context.energy_level < 0.3) { // User is tired - simplify return generateSimpleResponse(userQuery); } return generateFullResponse(userQuery); }

    Smart Notification Timing

    async function sendNotification(message, priority) { const context = await humsana.getContext(); if (!context.interruptible && priority !== 'critical') { // Queue for later return queueForLater(message); } showNotification(message); }

    Prompting User to Connect Platforms

    async function checkContextQuality() { const diff = await humsana.getUpgradeIncentive(); if (diff.improvement_factor > 2.5) { showUpgradePrompt(`Get ${diff.improvement_factor}x better AI responses`); } }

    Privacy Levels

    Level Data Collected Use Case
    Minimal Basic activity patterns only Privacy-conscious users
    Standard Activity patterns + interaction velocity Most users (default)
    Rich Full behavioral patterns Power users wanting best AI

    Pricing

    Monthly Active Users Price
    First 1,000 FREE
    1,001 - 10,000 $0.10 per MAU
    10,001+ Volume pricing available

    Partner Dashboard

    Monitor your integration metrics at:

    https://humsana.com/static/partner_dashboard.html?key=partner_hum_xxx

    Track:

    FAQ

    Do my users need to sign up?
    No. SDK Lite works immediately with no user action required.

    What data do you store?
    We don't store user content. We only analyze behavioral patterns in real-time.

    How fast is the API?
    Average response time is 12-15ms (P99 < 20ms).

    Can I customize the integration?
    Yes, enterprise partners can white-label and customize the experience.

    What platforms can users connect?
    GitHub, Google (Gmail/Calendar), Spotify, Notion, Slack, and Linear.

    Support

    Technical Support: contact@humsana.com

    Next Steps

    1. Request your partner key
    2. Integrate the SDK (5 minutes)
    3. Test with your team
    4. Launch to users
    Get Your Partner Key