๐Ÿ“š Complete Integration Guide

Step-by-step instructions to integrate EmojiHouse ML API

โฑ๏ธ Total Time: 5 minutes
1

๐Ÿ”‘ Understanding Your API Key

โš ๏ธ IMPORTANT: What is an API Key?

Your API key is like a password that identifies your app to EmojiHouse. It allows you to:

  • Make requests to our ML analysis API
  • Track revenue attribution to your app
  • Receive your 70% share of generated revenue
  • Access analytics and performance data

๐Ÿ”’ Keep Your API Key Secure

  • โœ… Store in environment variables (recommended)
  • โœ… Use server-side code only (not in browser JavaScript)
  • โŒ Never commit to public repositories
  • โŒ Never share in screenshots or documentation

๐Ÿ’ก How Revenue Attribution Works

Your API key links all API calls to your developer account. When our ML generates value for advertisers, you automatically earn 70% of the revenue - no additional setup required!

2

๐Ÿ›ก๏ธ Setting Up Authentication

๐Ÿ“ Environment Variables (Recommended)

# .env file (create in your project root)
EMOJIHOUSE_API_KEY=your_api_key_here_from_dashboard

# Example: 
# EMOJIHOUSE_API_KEY=eh_live_a1b2c3d4e5f6g7h8i9j0
โš ๏ธ Add .env to your .gitignore file to prevent committing secrets

โš™๏ธ Server Configuration Examples

Node.js/Express:
// Load environment variables
require('dotenv').config();

const EMOJIHOUSE_API_KEY = process.env.EMOJIHOUSE_API_KEY;

if (!EMOJIHOUSE_API_KEY) {
    throw new Error('EMOJIHOUSE_API_KEY environment variable is required');
}
Python/Django/Flask:
# pip install python-dotenv
import os
from dotenv import load_dotenv

load_dotenv()

EMOJIHOUSE_API_KEY = os.getenv('EMOJIHOUSE_API_KEY')

if not EMOJIHOUSE_API_KEY:
    raise ValueError('EMOJIHOUSE_API_KEY environment variable is required')
PHP/Laravel:
load();

$apiKey = $_ENV['EMOJIHOUSE_API_KEY'];

if (empty($apiKey)) {
    throw new Exception('EMOJIHOUSE_API_KEY environment variable is required');
}
3

๐Ÿš€ Making Your First API Call

๐Ÿ“ก API Endpoint

POST https://ads.emojihouse.com/ml/analyze

This is the main endpoint for ML analysis that generates revenue

JavaScript/Node.js

const analyzeUser = async (sessionData) => {
  try {
    const response = await fetch('https://ads.emojihouse.com/ml/analyze', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        user_id: sessionData.userId,
        session_id: sessionData.sessionId,
        platform: 'web', // or 'mobile_app', 'desktop'
        session_duration: sessionData.duration, // seconds
        interactions: sessionData.interactions, // ['click', 'scroll', 'share']
        content_type: 'social_feed', // or 'product_page', 'article'
        context: 'discovery_mode' // or 'search_result', 'recommendation'
      })
    });

    if (!response.ok) {
      throw new Error(`API Error: ${response.status}`);
    }

    const result = await response.json();
    
    console.log('ML Analysis Result:');
    console.log('Trust Score:', result.emoji_score);
    console.log('Confidence:', result.confidence);
    console.log('Trust Level:', result.trust_level);
    
    return result;
    
  } catch (error) {
    console.error('EmojiHouse API Error:', error);
    throw error;
  }
};

// Example usage:
const sessionData = {
  userId: 'user_12345',
  sessionId: 'sess_' + Date.now(),
  duration: 180,
  interactions: ['scroll', 'click', 'share'],
};

analyzeUser(sessionData)
  .then(result => {
    // Revenue is automatically attributed to your account!
    console.log('Analysis complete, revenue tracking active');
  })
  .catch(error => {
    console.error('Failed:', error);
  });

Python/Django/Flask

import requests
import os
from datetime import datetime

def analyze_user_session(session_data):
    # Analyze user session with EmojiHouse ML API
    # Returns ML analysis result and starts revenue tracking
    try:
        # API call to EmojiHouse
        response = requests.post(
            'https://ads.emojihouse.com/ml/analyze',
            headers={
                'Content-Type': 'application/json'
            },
            json={
                'user_id': session_data['user_id'],
                'session_id': session_data['session_id'],
                'platform': session_data.get('platform', 'web'),
                'session_duration': session_data.get('duration', 0),
                'interactions': session_data.get('interactions', []),
                'content_type': session_data.get('content_type', 'general'),
                'context': session_data.get('context', 'discovery_mode')
            },
            timeout=10
        )
        
        response.raise_for_status()  # Raise exception for HTTP errors
        result = response.json()
        
        print(f"ML Analysis Result:")
        print(f"Trust Score: {result['emoji_score']:.3f}")
        print(f"Confidence: {result['confidence']:.3f}")
        print(f"Trust Level: {result['trust_level']}")
        print(f"Processing Time: {result.get('total_processing_ms', 0):.1f}ms")
        
        # Revenue is automatically attributed to your account!
        
        return result
        
    except requests.exceptions.RequestException as e:
        print(f"EmojiHouse API Error: {e}")
        raise
    except Exception as e:
        print(f"Unexpected error: {e}")
        raise

# Example usage in Django view:
def user_activity_view(request):
    session_data = {
        'user_id': f"user_{request.user.id}",
        'session_id': f"sess_{int(datetime.now().timestamp())}",
        'platform': 'web',
        'duration': 180,  # 3 minutes
        'interactions': ['scroll', 'click', 'like'],
        'content_type': 'social_feed',
        'context': 'homepage_browse'
    }
    
    try:
        ml_result = analyze_user_session(session_data)
        
        # Use the ML result in your app logic
        if ml_result['trust_level'] == 'HIGH':
            # Show premium content
            pass
        
        return JsonResponse({
            'success': True,
            'trust_score': ml_result['emoji_score']
        })
        
    except Exception as e:
        return JsonResponse({
            'success': False,
            'error': str(e)
        })

# Example usage in Flask:
from flask import Flask, request, jsonify

@app.route('/analyze-session', methods=['POST'])
def analyze_session():
    data = request.get_json()
    
    try:
        result = analyze_user_session(data)
        return jsonify({
            'success': True,
            'trust_score': result['emoji_score'],
            'confidence': result['confidence']
        })
    except Exception as e:
        return jsonify({
            'success': False,
            'error': str(e)
        }), 500

PHP/Laravel

 $sessionData['user_id'],
        'session_id' => $sessionData['session_id'],
        'platform' => $sessionData['platform'] ?? 'web',
        'session_duration' => $sessionData['duration'] ?? 0,
        'interactions' => $sessionData['interactions'] ?? [],
        'content_type' => $sessionData['content_type'] ?? 'general',
        'context' => $sessionData['context'] ?? 'discovery_mode'
    ]);
    
    $ch = curl_init('https://ads.emojihouse.com/ml/analyze');
    
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json'
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 10);
    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    $error = curl_error($ch);
    curl_close($ch);
    
    if ($error) {
        throw new Exception("cURL Error: " . $error);
    }
    
    if ($httpCode !== 200) {
        throw new Exception("API Error: HTTP $httpCode");
    }
    
    $result = json_decode($response, true);
    
    if (!$result) {
        throw new Exception("Invalid JSON response");
    }
    
    echo "ML Analysis Result:\n";
    echo "Trust Score: " . number_format($result['emoji_score'], 3) . "\n";
    echo "Confidence: " . number_format($result['confidence'], 3) . "\n";
    echo "Trust Level: " . $result['trust_level'] . "\n";
    echo "Processing Time: " . ($result['total_processing_ms'] ?? 0) . "ms\n";
    
    // Revenue is automatically attributed to your account!
    
    return $result;
}

// Example usage in Laravel Controller:
class UserActivityController extends Controller {
    public function analyzeSession(Request $request) {
        $sessionData = [
            'user_id' => 'user_' . $request->user()->id,
            'session_id' => 'sess_' . time(),
            'platform' => 'web',
            'duration' => 180,
            'interactions' => ['scroll', 'click', 'share'],
            'content_type' => 'product_page',
            'context' => 'shopping_browse'
        ];
        
        try {
            $result = analyzeUserSession($sessionData);
            
            return response()->json([
                'success' => true,
                'trust_score' => $result['emoji_score'],
                'confidence' => $result['confidence']
            ]);
            
        } catch (Exception $e) {
            return response()->json([
                'success' => false,
                'error' => $e->getMessage()
            ], 500);
        }
    }
}

// Simple PHP usage:
$sessionData = [
    'user_id' => 'user_12345',
    'session_id' => 'sess_' . time(),
    'platform' => 'web',
    'duration' => 120,
    'interactions' => ['click', 'scroll'],
    'content_type' => 'article',
    'context' => 'reading_mode'
];

try {
    $result = analyzeUserSession($sessionData);
    echo "Analysis complete! Revenue tracking is now active.\n";
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

?>
4

๐Ÿ“Š Understanding the API Response

๐Ÿ“ Example Response

{
  "emoji_score": 0.847,           // Trust score: 0.0 to 1.0 (higher = more trustworthy)
  "confidence": 0.923,            // ML confidence: 0.0 to 1.0 (higher = more reliable)
  "trust_level": "HIGH",          // Human-readable: LOW, MEDIUM, HIGH
  "request_id": "ml_1759596522_1234",
  "total_processing_ms": 3.2,     // Response time in milliseconds
  
  // Revenue & Optimization (automatic)
  "revenue_optimization": {
    "bid_adjustment": 1.2,        // Recommended bid multiplier
    "expected_ltv_multiplier": 2.1 // Lifetime value prediction
  },
  
  // Privacy & Compliance
  "privacy_compliant": true,
  "gdpr_compliant": true,
  "ccpa_compliant": true,
  
  // System Status
  "api_version": "2.1.0",
  "timestamp": "2025-10-04T16:48:42.277606"
}

๐ŸŽฏ Key Metrics

  • emoji_score: Main trust metric (0-1)
  • confidence: How reliable the score is
  • trust_level: Easy-to-use category

๐Ÿ’ฐ Revenue Info

  • Revenue is attributed automatically
  • You earn 70% of generated value
  • No additional API calls needed
5

๐Ÿ’ฐ Revenue Tracking & Payouts

๐ŸŽ‰ Automatic Revenue Attribution

Every API call automatically:

  • Tracks revenue attribution to your developer account
  • Calculates your 70% share of generated value
  • Updates your dashboard in real-time
  • Prepares automatic Stripe payouts when you reach $5
75%
ML Confidence Required
Only high-quality predictions generate revenue
70%
Developer Share
You keep 70% of all attributed revenue
$5
Minimum Payout
Automatic Stripe transfers
6

๐Ÿงช Testing & Troubleshooting

๐Ÿ” Quick Test

# Test with curl (replace with your data)
curl -X POST https://ads.emojihouse.com/ml/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "test_user_123",
    "session_id": "test_session_456",
    "platform": "web",
    "session_duration": 120,
    "interactions": ["click", "scroll"],
    "content_type": "general",
    "context": "testing"
  }'

โŒ Common Errors

  • 400 Bad Request: Missing required fields
  • 500 Server Error: Temporary issue, retry
  • Timeout: Network issue, check connection
  • Invalid JSON: Check response parsing

โœ… Success Indicators

  • 200 Response: API call successful
  • emoji_score present: ML analysis complete
  • confidence > 0.75: Revenue generated
  • request_id: Unique tracking ID

โšก Advanced Features

๐Ÿ”„ Batch Processing

Process multiple users at once for better performance

POST /ml/predict/batch

๐Ÿ“Š Analytics

Real-time analytics and performance metrics

GET /analytics/trust-distribution

๐Ÿ” Privacy Mode

Enhanced privacy compliance for sensitive data

options.privacy_mode = true

๐Ÿ’ฐ Revenue Tracking

Built-in revenue attribution and optimization

GET /monetize/revenue