Client Methods
Direct API methods available on the EarnLayerClient instance.
Overview
Access the client via useEarnLayerClient() hook:
const { client } = useEarnLayerClient();initializeConversation(options?)
Initializes a new conversation and returns conversation metadata.
Signature
initializeConversation(options?: {
visitorId?: string;
adTypes?: ('hyperlink' | 'thinking' | 'banner')[];
frequency?: 'low' | 'normal' | 'high';
demoMode?: boolean;
}): Promise<Conversation>Parameters
visitorId (optional)
Type: string
Custom visitor ID for tracking.
adTypes (optional)
Type: ('hyperlink' | 'thinking' | 'banner')[]
Default: ['hyperlink', 'thinking', 'banner']
Types of ads to enable for this conversation.
frequency (optional)
Type: 'low' | 'normal' | 'high'
Default: 'normal'
Ad frequency setting.
demoMode (optional)
Type: boolean
Default: false
Enable demo mode to see all demo ads regardless of partnerships.
true- Shows ALL demo ads (for testing/development)false- Shows only real ads where you have partnerships configured (for production)
Use during:
- Initial integration testing
- Development and QA
- Creator onboarding and training
Important: Demo ads don’t generate revenue. Always set to false or omit in production.
Note: SDK uses camelCase (demoMode) in TypeScript/JavaScript. MCP headers use snake_case (x-demo-mode) but that’s handled internally.
Returns
interface Conversation {
conversation_id: string;
creator_id: string;
ad_settings: object;
status: string;
created_at: string;
}Example
const { client } = useEarnLayerClient();
// Initialize with defaults (production mode)
const conversation = await client.initializeConversation();
console.log('Conversation ID:', conversation.conversation_id);
// Initialize with options
const conversation = await client.initializeConversation({
visitorId: 'user_123',
adTypes: ['banner', 'thinking'],
frequency: 'low'
});
// Testing with demo mode
const conversation = await client.initializeConversation({
demoMode: true
});
// Environment-based demo mode (recommended)
const conversation = await client.initializeConversation({
demoMode: process.env.NODE_ENV === 'development'
});Error Handling
try {
const conversation = await client.initializeConversation();
} catch (error) {
if (error.message.includes('401')) {
console.error('Invalid API key');
} else if (error.message.includes('timeout')) {
console.error('Request timed out after 10 seconds');
} else {
console.error('Failed to initialize:', error);
}
}getDisplayAd(conversationId, adType?)
Fetches a display ad for the conversation.
Signature
getDisplayAd(
conversationId: string,
adType?: string
): Promise<DisplayAd | null>Parameters
conversationId (required)
Type: string
Conversation ID (must be non-empty).
adType (optional)
Type: string
Filter by ad type.
Returns
Promise<DisplayAd | null> - Returns null if no ads available (404).
Example
const { client, conversationId } = useEarnLayerClient();
const ad = await client.getDisplayAd(conversationId);
if (ad === null) {
console.log('No ads available');
} else {
console.log('Got ad:', ad.title);
}
// With ad type filter
const bannerAd = await client.getDisplayAd(conversationId, 'banner');Error Handling
try {
const ad = await client.getDisplayAd(conversationId);
} catch (error) {
if (error.message.includes('Invalid conversationId')) {
console.error('conversationId cannot be empty');
} else if (error.message.includes('timeout')) {
console.error('Request timed out');
} else {
console.error('Error fetching ad:', error);
}
}trackImpression(impressionId)
Tracks when an ad impression occurs. Automatically retries up to 3 times.
Signature
trackImpression(impressionId: string): Promise<boolean>Parameters
impressionId (required)
Type: string
Impression ID from the ad object.
Returns
Promise<boolean> - true if tracked successfully, false if all retries failed.
Example
const { client } = useEarnLayerClient();
const success = await client.trackImpression(ad.impressionId);
if (!success) {
console.warn('Failed to track impression after 3 retries');
}trackClick(impressionId)
Tracks when a user clicks an ad. Automatically retries up to 3 times.
Signature
trackClick(impressionId: string): Promise<boolean>Parameters
impressionId (required)
Type: string
Impression ID from the ad object.
Returns
Promise<boolean> - true if tracked successfully, false if all retries failed.
Example
const { client } = useEarnLayerClient();
const success = await client.trackClick(ad.impressionId);
if (!success) {
console.warn('Failed to track click after 3 retries');
}confirmHyperlinkImpressions(conversationId, messageText)
Confirms hyperlink ad impressions in an LLM response message.
Signature
confirmHyperlinkImpressions(
conversationId: string,
messageText: string
): Promise<{
confirmed_count: number;
impression_ids: string[];
}>Parameters
conversationId (required)
Type: string
Conversation ID (must be non-empty).
messageText (required)
Type: string
AI response text containing hyperlink ads (must be non-empty).
Returns
interface ConfirmResult {
confirmed_count: number; // Number of ads confirmed
impression_ids: string[]; // Array of impression IDs
}Example
const { client, conversationId } = useEarnLayerClient();
const handleSendMessage = async (message: string) => {
const response = await fetch('/api/chat', {
method: 'POST',
body: JSON.stringify({ message, conversationId })
});
const data = await response.json();
const aiResponseText = data.response;
// Confirm impressions
const result = await client.confirmHyperlinkImpressions(
conversationId,
aiResponseText
);
console.log(`Confirmed ${result.confirmed_count} ad impressions`);
};Error Handling
try {
const result = await client.confirmHyperlinkImpressions(
conversationId,
messageText
);
} catch (error) {
if (error.message.includes('Invalid conversationId')) {
console.error('conversationId is required');
} else if (error.message.includes('Invalid messageText')) {
console.error('messageText is required');
} else if (error.message.includes('timeout')) {
console.error('Request timed out after 10 seconds');
} else {
console.error('Error confirming impressions:', error);
}
}Features Included in All Methods
- 10-second timeout with AbortController
- Input validation (where applicable)
- Automatic retry with exponential backoff (
trackImpression,trackClick) - Detailed error messages
- Automatic error logging to console