Getting Started with Integration¶

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:

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

Next Steps¶

After completing the basic integration:

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