Markopolo Documentation

Appearance

Website Builder Integration Guide ​

Enable analytics for thousands of websites built on your platform. This guide shows website builders how to integrate MarkTag as a native analytics feature.

Quick Start (2 Minutes) ​

Step 1: Get Your API Token ​

Contact partners@markopolo.ai to get your Partners API token (mp_live_*).

Step 2: Create Site Account ​

When a user creates a website on your platform:

bash
curl -X POST "https://api-alpha.markopolo.ai/v1/partners/merchant" \
  -H "Authorization: Bearer mp_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "User Website - example.com"
  }'

Step 3: Generate Analytics Tag ​

bash
curl -X POST "https://api-alpha.markopolo.ai/v1/partners/marktag/generate" \
  -H "Authorization: Bearer mp_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "YOUR_MERCHANT_ID",
    "type": "client-side"
  }'

Step 4: Auto-Inject Analytics ​

Automatically add tracking to all published sites:

html
<!-- Injected into site template header -->
<script>
  window.mtrem = window.mtrem || [];
  function mtag() { mtrem.push(arguments) }
  mtag("init", "https://mtag.markopolo.ai?tagId=YOUR_TAG_ID", {"consent": true});
</script>
<script async src="https://mtag.markopolo.ai/script"></script>

Analytics are now live! No user configuration needed.

Key Website Events ​

Track essential website interactions automatically:

1. Page Views (Automatic) ​

javascript
// Automatically tracked on page load
mtag('event', 'PageView', {
  page_title: document.title,
  page_location: window.location.href,
  page_path: window.location.pathname
});

2. Form Submissions ​

javascript
// Track contact forms, newsletter signups
mtag('event', 'Lead', {
  email: formData.email,
  phone: formData.phone,
  form_name: 'Contact Form',
  page_location: window.location.href
});

3. Button Clicks ​

javascript
// Track CTA and important button clicks
mtag('event', 'ButtonClick', {
  button_text: 'Get Started',
  button_url: '/signup',
  page_location: window.location.href
});

4. File Downloads ​

javascript
// Track PDF, document downloads
mtag('event', 'Download', {
  file_name: 'brochure.pdf',
  file_type: 'pdf',
  page_location: window.location.href
});

5. Video Engagement ​

javascript
// Track video plays
mtag('event', 'VideoPlay', {
  video_title: 'Product Demo',
  video_duration: 120,
  video_provider: 'youtube'
});

Platform Integration Example ​

Here's how to integrate analytics into your website builder:

javascript
class WebsiteBuilderAnalytics {
  constructor(apiToken) {
    this.apiToken = apiToken;
    this.sites = new Map();
  }

  async createSiteAnalytics(siteId, siteName, domain) {
    // Create merchant account for the site
    const merchant = await fetch('https://api-alpha.markopolo.ai/v1/partners/merchant', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${siteName} - ${domain}`
      })
    }).then(r => r.json());

    // Generate analytics tag
    const marktag = await fetch('https://api-alpha.markopolo.ai/v1/partners/marktag/generate', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        merchantId: merchant.merchantId,
        type: 'client-side'
      })
    }).then(r => r.json());

    // Store mapping
    this.sites.set(siteId, {
      merchantId: merchant.merchantId,
      tagId: marktag.tagId,
      domain: domain
    });

    return marktag.tagId;
  }

  getAnalyticsScript(siteId) {
    const site = this.sites.get(siteId);
    if (!site) return '';

    return `
      <script>
        window.mtrem = window.mtrem || [];
        function mtag() { mtrem.push(arguments) }
        mtag("init", "https://mtag.markopolo.ai?tagId=${site.tagId}", {"consent": true});
      </script>
      <script async src="https://mtag.markopolo.ai/script"></script>
    `;
  }

  // Auto-inject into site templates
  injectAnalytics(siteHtml, siteId) {
    const analyticsScript = this.getAnalyticsScript(siteId);
    // Insert before closing </head> tag
    return siteHtml.replace('</head>', `${analyticsScript}</head>`);
  }
}

// Usage in your platform
const analytics = new WebsiteBuilderAnalytics('mp_live_YOUR_TOKEN');

// When user creates a new site
const tagId = await analytics.createSiteAnalytics(
  'site-123',
  'My Business Site',
  'mybusiness.com'
);

// When publishing/rendering site
const finalHtml = analytics.injectAnalytics(siteTemplate, 'site-123');

Analytics Dashboard Integration ​

Option 1: Embedded Dashboard ​

Provide analytics directly in your builder interface:

javascript
// Fetch site analytics
async function getSiteAnalytics(merchantId, dateRange) {
  const response = await fetch(
    `https://api-alpha.markopolo.ai/v1/partners/events?merchantId=${merchantId}&startDate=${dateRange.start}&endDate=${dateRange.end}`,
    {
      headers: {
        'Authorization': `Bearer mp_live_YOUR_TOKEN`
      }
    }
  );

  const data = await response.json();
  return {
    pageViews: data.events.filter(e => e.eventName === 'PageView').length,
    uniqueVisitors: new Set(data.events.map(e => e.userId)).size,
    formSubmissions: data.events.filter(e => e.eventName === 'Lead').length,
    topPages: getTopPages(data.events)
  };
}

Option 2: Analytics Toggle ​

Let users enable/disable analytics:

javascript
class AnalyticsSettings {
  async toggleAnalytics(siteId, enabled) {
    if (enabled) {
      // Generate new tag if enabling
      const tagId = await this.createSiteAnalytics(siteId);
      await this.updateSiteSettings(siteId, { analyticsEnabled: true });
    } else {
      // Remove analytics script from site
      await this.updateSiteSettings(siteId, { analyticsEnabled: false });
    }
  }
}

Querying Analytics Data ​

Retrieve analytics for your users' sites:

Get Site Metrics ​

bash
# Page views for a site
curl -X GET "https://api-alpha.markopolo.ai/v1/partners/events?merchantId=MERCHANT_ID&eventName=PageView" \
  -H "Authorization: Bearer mp_live_YOUR_TOKEN"

# Form submissions
curl -X GET "https://api-alpha.markopolo.ai/v1/partners/events?merchantId=MERCHANT_ID&eventName=Lead" \
  -H "Authorization: Bearer mp_live_YOUR_TOKEN"

Display in Your Dashboard ​

javascript
// Show analytics in your builder dashboard
async function displaySiteMetrics(merchantId) {
  const events = await fetchEvents(merchantId);

  return {
    visitors: {
      today: events.filter(e => isToday(e.timestamp)).length,
      week: events.filter(e => isThisWeek(e.timestamp)).length,
      month: events.filter(e => isThisMonth(e.timestamp)).length
    },
    topPages: events
      .filter(e => e.eventName === 'PageView')
      .map(e => e.properties.page_path)
      .reduce((acc, page) => {
        acc[page] = (acc[page] || 0) + 1;
        return acc;
      }, {}),
    conversions: events.filter(e => e.eventName === 'Lead').length
  };
}

Testing Your Integration ​

1. Create Test Site ​

javascript
const testSite = await analytics.createSiteAnalytics(
  'test-site-1',
  'Test Site',
  'testsite.com'
);

2. Verify Script Injection ​

javascript
// Check if analytics script is present
const html = await getSiteHtml('test-site-1');
console.log(html.includes('mtag.markopolo.ai')); // Should be true

3. Test Event Tracking ​

javascript
// Simulate page view
mtag('event', 'PageView', {
  page_title: 'Test Page',
  page_location: 'https://testsite.com/test'
});

// Verify event was tracked
const events = await getEvents(testSite.merchantId);
console.log(events); // Should include the test event

Best Practices ​

Auto-Enable for All Sites ​

  • Generate analytics tags automatically when sites are created
  • No user action required for basic analytics

Privacy Compliance ​

  • Include analytics disclosure in your terms
  • Respect user privacy settings
  • Provide opt-out options

Performance ​

  • Load analytics script asynchronously
  • Don't block page rendering
  • Cache tag IDs to reduce API calls

Get Started Today ​

  1. Email partners@markopolo.ai for your API token
  2. Integrate analytics in 2 minutes
  3. Provide instant value to your users

Note: While this guide focuses on client-side tracking for instant setup, MarkTag also supports server-side tracking (using custom domains) and preverified tracking (using your platform's domain) for advanced use cases. Contact our team to learn more.

Quick Reference Checklist ​

✅ Initial Setup ​

  • [ ] Get Partners API token from partners@markopolo.ai
  • [ ] Create merchant accounts for each site
  • [ ] Generate client-side MarkTag for each site
  • [ ] Auto-inject tracking script into site templates

✅ Core Events ​

  • [ ] PageView - Automatic on every page load
  • [ ] Lead - Track form submissions
  • [ ] ButtonClick - Track CTA interactions
  • [ ] Download - Track file downloads
  • [ ] VideoPlay - Track video engagement

✅ Platform Features ​

  • [ ] Auto-enable analytics for new sites
  • [ ] Display metrics in builder dashboard
  • [ ] Provide analytics toggle in settings
  • [ ] Show real-time visitor counts

✅ Testing ​

  • [ ] Verify script injection in published sites
  • [ ] Test event tracking in browser console
  • [ ] Query events via API
  • [ ] Validate analytics dashboard data

Copyright © 2026 Markopolo AI