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

Create a new tag in GTM
Choose "Custom HTML" tag type
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>

Set trigger to "All Pages"
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();

    // Step 3: Return the tracking configuration
    return {
      merchantId: merchant.merchantId,
      tagId: marktag.tagId,
      status: marktag.status,
      trackingUrl: `https://mtag.markopolo.ai?tagId=${marktag.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 result = await integration.enableTrackingForMerchant({
  name: 'New Merchant'
});

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

Troubleshooting

No Events Appearing

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
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
Check for JavaScript errors
- Open browser console
- Look for any errors related to the MarkTag script

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:

Consider using server-side MarkTag for ad blocker resilience
Add instructions for users to whitelist mtag.markopolo.ai
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:

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

Best Practices

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

Migration from Other Tracking

If migrating from another analytics solution:

Install MarkTag alongside existing tracking
Verify MarkTag is collecting events properly
Run both in parallel for a testing period
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

View tracked events
Manage merchants
Explore server-side implementation for custom domains
Learn about preverified implementation for platform integration

Client-Side MarkTag Implementation ​

Overview ​

Prerequisites ​

Complete Implementation Flow ​

Step 1: Create Merchant Account ​

Step 2: Generate Client-Side MarkTag ​

Step 3: Extract the TAG_ID ​

Step 4: Install the Tracking Script ​

Option A: Direct HTML Installation ​

Configuration Options ​

Common Configuration Scenarios ​

Option B: Dynamic Installation (JavaScript) ​

Option C: Google Tag Manager ​

Step 5: Verify Tracking is Working ​

Integration Examples ​

React Application ​

Next.js Application ​

WordPress Plugin ​

Shopify Theme ​

Platform Integration ​

Troubleshooting ​

No Events Appearing ​

Script Blocked by Ad Blockers ​

Multiple MarkTags on Same Page ​

Best Practices ​

Migration from Other Tracking ​

API Reference ​

Generate Client-Side MarkTag ​

Next Steps ​

Client-Side MarkTag Implementation

Overview

Prerequisites

Complete Implementation Flow

Step 1: Create Merchant Account

Step 2: Generate Client-Side MarkTag

Step 3: Extract the TAG_ID

Step 4: Install the Tracking Script

Option A: Direct HTML Installation

Configuration Options

Common Configuration Scenarios

Option B: Dynamic Installation (JavaScript)

Option C: Google Tag Manager

Step 5: Verify Tracking is Working

Integration Examples

React Application

Next.js Application

WordPress Plugin

Shopify Theme

Platform Integration

Troubleshooting

No Events Appearing

Script Blocked by Ad Blockers

Multiple MarkTags on Same Page

Best Practices

Migration from Other Tracking

API Reference

Generate Client-Side MarkTag

Next Steps