Markopolo Documentation

Appearance

Client-Side MarkTag Implementation ​

Complete implementation guide for client-side MarkTag - the fastest way to start tracking without DNS configuration.

Overview ​

Client-side MarkTag uses JavaScript-based tracking via mtag.markopolo.ai. It requires no DNS configuration and works instantly after generation.

Best for:

  • Immediate tracking needs
  • Testing and development
  • Merchants without DNS access
  • Quick proof of concept

Setup time: Instant (0 minutes)

Prerequisites ​

  • Partners API token (mp_live_...)
  • Access to merchant's website HTML

Complete Implementation Flow ​

Step 1: Create Merchant Account ​

Create a merchant account to associate with the MarkTag.

Request:

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": "Fashion Store"
  }'

Response:

json
{
  "merchantId": "550e8400-e29b-41d4-a716-446655440001"
}

Important: Save the merchantId for the next step.

Step 2: Generate Client-Side MarkTag ​

Generate a client-side MarkTag for the merchant.

Request:

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": "550e8400-e29b-41d4-a716-446655440001",
    "type": "client-side"
  }'

Response:

json
{
  "tagId": "client-abc123",
  "status": "active",
  "message": "New tag created successfully",
  "type": "client-side"
}

Step 3: Extract the TAG_ID ​

From the response, you'll need the tagId to construct your tracking script:

  • tagId: client-abc123 (example - use your actual tagId)
  • trackingDomain: mtag.markopolo.ai (fixed for client-side)

Step 4: Install the Tracking Script ​

Add the MarkTag tracking scripts to the merchant's website:

Option A: Direct HTML Installation ​

Add both scripts to the <head> section of every page:

html
<!DOCTYPE html>
<html>
  <head>
    <!-- MarkTag Initialization Script -->
    <script>
      window.mtrem = window.mtrem || [];
      function mtag() {
        mtrem.push(arguments);
      }
      mtag('init', 'https://mtag.markopolo.ai?tagId=client-abc123', {
        consent: true,
      });
    </script>

    <!-- MarkTag Loader Script -->
    <script async src="https://mtag.markopolo.ai/script"></script>

    <!-- Rest of your head content -->
    <title>Fashion Store</title>
  </head>
  <body>
    <!-- Your website content -->
  </body>
</html>

Important Notes:

  • Replace client-abc123 with your actual tagId from the API response (note: tagIds are case-sensitive)
  • The initialization script must come before the loader script
  • The URL format uses a query parameter: ?tagId=client-abc123

Configuration Options ​

The mtag("init", url, options) function accepts these configuration options:

javascript
mtag('init', 'https://mtag.markopolo.ai?tagId=client-abc123', {
  consent: true, // User consent for tracking (required in GDPR regions)
  // Additional options may be available - check with your account manager
});

Common Configuration Scenarios ​

Basic Implementation (with consent):

javascript
mtag('init', 'https://mtag.markopolo.ai?tagId=client-abc123', {
  consent: true,
});

Implementation without explicit consent (check local regulations):

javascript
mtag('init', 'https://mtag.markopolo.ai?tagId=client-abc123', {
  consent: false,
});

Option B: Dynamic Installation (JavaScript) ​

For single-page applications or dynamic insertion:

javascript
// Initialize tracking
window.mtrem = window.mtrem || [];
window.mtag = function () {
  window.mtrem.push(arguments);
};
window.mtag('init', 'https://mtag.markopolo.ai?tagId=client-abc123', {
  consent: true,
});

// Load the tracking script
const script = document.createElement('script');
script.src = 'https://mtag.markopolo.ai/script';
script.async = true;
document.head.appendChild(script);

Option C: Google Tag Manager ​

  1. Create a new tag in GTM
  2. Choose "Custom HTML" tag type
  3. Insert both scripts:
html
<script>
  window.mtrem = window.mtrem || [];
  function mtag() {
    mtrem.push(arguments);
  }
  mtag('init', 'https://mtag.markopolo.ai?tagId=client-abc123', {
    consent: true,
  });
</script>
<script async src="https://mtag.markopolo.ai/script"></script>
  1. Set trigger to "All Pages"
  2. Publish the container

Step 5: Verify Tracking is Working ​

Check that events are being received:

Request:

bash
curl -X GET "https://api-alpha.markopolo.ai/v1/partners/events?merchantId=550e8400-e29b-41d4-a716-446655440001&limit=5" \
  -H "Authorization: Bearer mp_live_YOUR_TOKEN"

Expected Response:

json
{
  "events": [
    {
      "id": "evt_123456789",
      "muid": "user_abc123",
      "event_name": "PageView",
      "event_time": "2025-01-25T10:30:00.000Z",
      "raw_data": { "url": "https://fashionstore.com/", "title": "Home Page" }
    },
    {
      "id": "evt_987654321",
      "muid": "user_abc123",
      "event_name": "PageView",
      "event_time": "2025-01-25T10:35:00.000Z",
      "raw_data": {
        "url": "https://fashionstore.com/products",
        "title": "Products Page"
      }
    }
  ],
  "pagination": {
    "total": 2,
    "currentPage": 1,
    "totalPages": 1,
    "itemsPerPage": 5,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

✅ Success! You should see events within seconds of installing the script.

Integration Examples ​

React Application ​

jsx
// components/MarkTag.jsx
import { useEffect } from 'react';

const MarkTag = ({ tagId }) => {
  useEffect(() => {
    // Initialize tracking
    window.mtrem = window.mtrem || [];
    window.mtag = function () {
      window.mtrem.push(arguments);
    };
    window.mtag('init', `https://mtag.markopolo.ai?tagId=${tagId}`, {
      consent: true,
    });

    // Load the tracking script
    const script = document.createElement('script');
    script.src = 'https://mtag.markopolo.ai/script';
    script.async = true;
    document.head.appendChild(script);

    return () => {
      if (script.parentNode) {
        document.head.removeChild(script);
      }
    };
  }, [tagId]);

  return null;
};

// Usage in App.jsx
function App() {
  return (
    <>
      <MarkTag tagId="client-abc123" />
      {/* Rest of your app */}
    </>
  );
}

Next.js Application ​

jsx
// pages/_app.js or app/layout.js
import Script from 'next/script';

export default function RootLayout({ children }) {
  const tagId = 'client-abc123'; // Replace with your actual tagId

  return (
    <html>
      <head>
        <Script id="marktag-init" strategy="afterInteractive">
          {`
            window.mtrem = window.mtrem || [];
            function mtag() {
              mtrem.push(arguments);
            }
            mtag("init", "https://mtag.markopolo.ai?tagId=${tagId}", {
              consent: true,
            });
          `}
        </Script>
        <Script
          src="https://mtag.markopolo.ai/script"
          strategy="afterInteractive"
        />
      </head>
      <body>{children}</body>
    </html>
  );
}

WordPress Plugin ​

php
// In your WordPress plugin or theme functions.php
function add_marktag_tracking() {
    $tag_id = 'client-abc123'; // Replace with your actual tagId
    ?>
    <script>
      window.mtrem = window.mtrem || [];
      function mtag() {
        mtrem.push(arguments);
      }
      mtag("init", "https://mtag.markopolo.ai?tagId=<?php echo $tag_id; ?>", {
        consent: true,
      });
    </script>
    <script async src="https://mtag.markopolo.ai/script"></script>
    <?php
}
add_action('wp_head', 'add_marktag_tracking');

Shopify Theme ​

liquid
<!-- In theme.liquid, within the <head> tag -->
{% comment %} MarkTag Tracking {% endcomment %}
<script>
  window.mtrem = window.mtrem || [];
  function mtag() {
    mtrem.push(arguments);
  }
  mtag("init", "https://mtag.markopolo.ai?tagId=client-abc123", {
    consent: true,
  });
</script>
<script async src="https://mtag.markopolo.ai/script"></script>

Platform Integration ​

If you're a platform provider integrating for multiple merchants:

javascript
class MarkTagIntegration {
  constructor(apiToken) {
    this.apiToken = apiToken;
    this.apiBase = 'https://api-alpha.markopolo.ai/v1/partners';
  }

  async enableTrackingForMerchant(merchantData) {
    // Step 1: Create merchant
    const merchantResponse = await fetch(`${this.apiBase}/merchant`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${this.apiToken}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        name: merchantData.name,
      }),
    });
    const merchant = await merchantResponse.json();

    // Step 2: Generate client-side marktag
    const marktagResponse = await fetch(`${this.apiBase}/marktag/generate`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${this.apiToken}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        merchantId: merchant.merchantId,
        type: 'client-side',
      }),
    });
    const marktag = await marktagResponse.json();

    const merchantDetails = await fetch(
      `https://api-alpha.markopolo.ai/v1/partners/merchant/${merchant.merchantId}`,
      {
        headers: {
          Authorization: `Bearer ${this.apiToken}`,
        },
      },
    ).then(r => r.json());

    // Step 3: Return the tracking configuration
    return {
      merchantId: merchant.merchantId,
      tagId: merchantDetails.tagId,
      status: marktag.status,
      trackingUrl: `https://mtag.markopolo.ai?tagId=${merchantDetails.tagId}`,
      scriptUrl: 'https://mtag.markopolo.ai/script',
    };
  }

  // Helper to inject MarkTag scripts into merchant's site
  injectScript(tagId, config = { consent: true }) {
    // Initialize tracking
    window.mtrem = window.mtrem || [];
    window.mtag = function () {
      window.mtrem.push(arguments);
    };
    window.mtag('init', `https://mtag.markopolo.ai?tagId=${tagId}`, config);

    // Load the tracking script
    const script = document.createElement('script');
    script.src = 'https://mtag.markopolo.ai/script';
    script.async = true;
    document.head.appendChild(script);
  }

  // Generate HTML snippet for merchants to install
  generateHTMLSnippet(tagId, config = { consent: true }) {
    return `
<!-- MarkTag Tracking Start -->
<script>
  window.mtrem = window.mtrem || [];
  function mtag() {
    mtrem.push(arguments);
  }
  mtag("init", "https://mtag.markopolo.ai?tagId=${tagId}", ${JSON.stringify(config)});
</script>
<script async src="https://mtag.markopolo.ai/script"></script>
<!-- MarkTag Tracking End -->
    `.trim();
  }
}

// Usage
const integration = new MarkTagIntegration('mp_live_YOUR_TOKEN');
const trackingConfig = await integration.enableTrackingForMerchant({
  name: 'New Merchant',
});

// Generate HTML snippet for merchant
const htmlSnippet = integration.generateHTMLSnippet(trackingConfig.tagId);
console.log('Install this HTML snippet:', htmlSnippet);

Troubleshooting ​

No Events Appearing ​

  1. Check script installation

    • Open browser DevTools → Network tab
    • Reload the page
    • Look for requests to:
      • The initialization URL with your tagId parameter
      • https://mtag.markopolo.ai/script
    • Both should return 200 status

  2. Verify TAG_ID is correct

    • Ensure you're using the exact tagId from the API response
    • TAG_IDs are case-sensitive
    • The URL should be formatted as: ?tagId=client-abc123

  3. Check for JavaScript errors

    • Open browser console
    • Look for any errors related to the MarkTag script

  4. Verify merchant exists and has events

    bash
    curl -X GET "https://api-alpha.markopolo.ai/v1/partners/merchant?limit=10" \
  -H "Authorization: Bearer mp_live_YOUR_TOKEN"

Script Blocked by Ad Blockers ​

Some ad blockers may block third-party tracking domains. Solutions:

  1. Consider using server-side MarkTag for ad blocker resilience
  2. Add instructions for users to whitelist mtag.markopolo.ai
  3. Monitor the percentage of blocked users via event analytics

Multiple MarkTags on Same Page ​

Only one MarkTag should be installed per page. If you need to track for multiple merchants:

  1. Use a single merchant account for the domain
  2. Or implement page-level isolation (different pages for different merchants)

Best Practices ​

  1. Load Early - Place the script in <head> for earliest possible loading
  2. Use Async - Add async attribute to prevent blocking page load
  3. Single Instance - Ensure only one MarkTag script per page
  4. Cache Friendly - The script URL is static and can be cached
  5. HTTPS Only - Always load the script over HTTPS
  6. Monitor Events - Regularly check that events are being received

Migration from Other Tracking ​

If migrating from another analytics solution:

  1. Install MarkTag alongside existing tracking
  2. Verify MarkTag is collecting events properly
  3. Run both in parallel for a testing period
  4. Remove old tracking once confident in MarkTag data

API Reference ​

Generate Client-Side MarkTag ​

POST /v1/partners/marktag/generate

Request Body:

json
{
  "merchantId": "string",
  "type": "client-side"
}

Response:

json
{
  "tagId": "string",
  "status": "active",
  "message": "New tag created successfully",
  "type": "client-side"
}

Next Steps ​

Copyright © 2026 Markopolo AI