integration

integrate your application to mosaic

Overview

This guide will walk you through the process of integrating Mosaic's API into your AI model or application. By following these steps, you'll be able to serve contextually relevant ads to your users and monetize your AI application.

Prerequisites

Before you begin, you'll need:

A Mosaic account with API access
Your unique API key for each AI model
Basic knowledge of making HTTP requests from your backend

Integration Steps

Step 1: Obtain API Key

Sign-up for a Mosaic account: HERE Each model in your ecosystem should have its own API key.

Step 2: Send Keywords and Context

Your integration should extract and send relevant keywords and user context from each conversation to the Mosaic API.

Step 3: Make API Calls

When appropriate in your application flow, make a call to the /api/fetch-ads endpoint with the conversation context and extracted keywords.

async function fetchAd(conversation, keywords, location, deviceInfo) {
  try {
    const response = await fetch('https://demo.xmosaic.ai/api/fetch-ads', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'mosaic-api-key': 'YOUR_API_KEY'
      },
      body: JSON.stringify({
        conversation,
        context_keywords: keywords,
        user_location: location,
        user_device_info: deviceInfo
      })
    });

    if (!response.ok) {
      const errorData = await response.json();
      console.error('Error fetching ad:', errorData);
      return null;
    }

    const data = await response.json();
    return data.advertisements[0];
  } catch (error) {
    console.error('Failed to fetch ad:', error);
    return null;
  }
}

Step 4: Display Advertisements

Use the campaign_markdown field from the response to display the advertisement in your application. This field contains ready-to-use markdown with proper tracking links.

function displayAd(ad) {
  if (!ad) return;

  // For markdown-based applications
  return ad.campaign_markdown;

  // For HTML applications
  // You might need to convert markdown to HTML or use the individual fields
  // to construct your own HTML
}

Step 5: Implement Error Handling

Implement proper error handling to gracefully manage cases where no ads are available or API calls fail.

async function getAndDisplayAd(conversation) {
  const keywords = extractKeywords(conversation);
  const userLocation = getUserLocation(); // Your implementation
  const deviceInfo = getDeviceInfo(); // Your implementation

  const ad = await fetchAd(conversation, keywords, userLocation, deviceInfo);

  if (ad) {
    return displayAd(ad);
  } else {
    // Graceful fallback when no ad is available
    return null;
  }
}

Testing Your Integration

To test your integration:

Make test API calls with the required parameters
Verify that ads are displayed correctly in your application
Test the click tracking by clicking on ads and verifying redirects
Check your Mosaic dashboard to confirm impressions and clicks are being recorded

Next Steps

After completing the basic integration:

Review the Best Practices guide
Analyze performance data in your Mosaic dashboard

authentication

endpoints

Monetize Your AI

Advertise Inside AI