Server-Side MarkTag Implementation

Complete implementation guide for server-side MarkTag - enterprise-grade tracking on merchant's custom domain.

Overview

Server-side MarkTag enables tracking on the merchant's own domain (e.g., mtag.merchantsite.com). This provides first-party cookies, better ad blocker resilience, and full domain control.

Best for:

Enterprise merchants requiring domain control
First-party cookie requirements
Maximum ad blocker resilience
Custom subdomain needs

Setup time: 10-40 minutes (DNS propagation)

Prerequisites

Partners API token (mp_live_...)
Merchant must have DNS access
Ability to add CNAME records
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": "Enterprise Store",
    "domain": "enterprisestore.com"
  }'

Response:

json

{
  "merchantId": "mch_9d8c7b6a-5e4d-3c2b-1a0f-9e8d7c6b5a4d",
  "name": "Enterprise Store",
  "domain": "enterprisestore.com",
  "createdAt": "2024-01-15T11:00:00Z"
}

Important: Save the merchantId for the next step.

Step 2: Generate Server-Side MarkTag

Generate a server-side MarkTag with the desired tracking domain.

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": "mch_9d8c7b6a-5e4d-3c2b-1a0f-9e8d7c6b5a4d",
    "type": "server-side",
    "domain": "enterprisestore.com"
  }'

Response:

json

{
  "tagId": "server-xyz789",
  "record": {
    "type": "CNAME",
    "name": "mtag-h7k9",
    "value": "mts1.markopolo.ai",
    "ttl": 300
  },
  "status": "inactive",
  "message": "New tag created successfully",
  "type": "server-side"
}

Key fields:

status: inactive - Waiting for DNS verification
record: Contains the CNAME details to configure
tagId: server-xyz789 - Will be used in tracking code

Step 3: Configure DNS

The merchant must add a CNAME record to their DNS settings.

DNS Configuration Details

From the API response, use the record field to configure DNS:

Field	Value
Type	CNAME
Name	mtag
Value	mts1.markopolo.ai
TTL	300

DNS Provider Instructions

Cloudflare

Go to DNS management
Click "Add record"
Select Type: CNAME
Name: mtag
Target: mts1.markopolo.ai
Important: Proxy status: DNS only (gray cloud)
Save

GoDaddy

Navigate to DNS Management
Click "Add" in Records section
Type: CNAME
Host: mtag
Points to: mts1.markopolo.ai
TTL: 1 hour
Save

AWS Route 53

Go to Hosted zones
Select the domain
Click "Create record"
Record name: mtag
Record type: CNAME
Value: mts1.markopolo.ai
Create records

Namecheap

Go to Advanced DNS
Click "Add New Record"
Type: CNAME Record
Host: mtag
Value: mts1.markopolo.ai
TTL: Automatic
Save

Step 4: Wait for DNS Propagation

DNS changes typically propagate within:

Best case: 5-10 minutes
Average: 15-30 minutes
Maximum: Up to 48 hours (rare)

Check DNS Propagation

bash

# Using dig
dig mtag-h7k9.enterprisestore.com CNAME +short

# Expected output:
# mts1.markopolo.ai.

# Using nslookup
nslookup mtag-h7k9.enterprisestore.com

# Using online tool
curl -L https://dnschecker.org/#CNAME/mtag-h7k9.enterprisestore.com

Step 5: Verify DNS Configuration via API

Once DNS is configured, verify it through the API.

Request:

bash

curl -X POST https://api-alpha.markopolo.ai/v1/partners/marktag/verify \
  -H "Authorization: Bearer mp_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tagId": "server-xyz789",
    "subdomain": "mtag-h7k9.enterprisestore.com"
  }'

Response (422 - DNS Pending):

json

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "DNS verification pending. Please allow time for DNS propagation and try again",
    "statusCode": 422
  }
}

Response (200 - Verified):

json

{
  "verified": true
}

Step 6: Install the Tracking Script

Once DNS is verified (response: {"verified": true}), install the script on the website.

Extract TAG_ID and Domain

From the original MarkTag response:

tagId: server-xyz789
Tracking domain: mtag-h7k9.enterprisestore.com (using the generated subdomain from record.name)

The tracking implementation requires two script tags:

Installation Options

Option A: Direct HTML

html

<!DOCTYPE html>
<html>
  <head>
    <!-- Server-Side MarkTag Initialization -->
    <script>
      window.mtrem = window.mtrem || [];
      function mtag() {
        mtrem.push(arguments);
      }
      mtag(
        "init",
        "https://mtag-h7k9.enterprisestore.com?tagId=server-xyz789",
        {
          consent: true,
        },
      );
    </script>

    <!-- Server-Side MarkTag Loader -->
    <script async src="https://mtag-h7k9.enterprisestore.com/script"></script>

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

Option B: Dynamic Installation

javascript

// For single-page applications
// Initialize tracking
window.mtrem = window.mtrem || [];
window.mtag = function () {
  window.mtrem.push(arguments);
};
window.mtag(
  "init",
  "https://mtag-h7k9.enterprisestore.com?tagId=server-xyz789",
  {
    consent: true,
  },
);

// Load the tracking script
const script = document.createElement("script");
script.src = "https://mtag-h7k9.enterprisestore.com/script";
script.async = true;
document.head.appendChild(script);

Step 7: Verify Tracking

Confirm events are being received.

Request:

bash

curl -X GET "https://api-alpha.markopolo.ai/v1/partners/events?merchantId=mch_9d8c7b6a-5e4d-3c2b-1a0f-9e8d7c6b5a4d&limit=5" \
  -H "Authorization: Bearer mp_live_YOUR_TOKEN"

Expected Response:

json

{
  "events": [
    {
      "eventId": "evt_789012",
      "type": "pageview",
      "url": "https://enterprisestore.com/",
      "timestamp": "2024-01-15T11:35:00Z",
      "domain": "mtag-h7k9.enterprisestore.com",
      "firstParty": true
    },
    {
      "eventId": "evt_789013",
      "type": "click",
      "url": "https://enterprisestore.com/products",
      "timestamp": "2024-01-15T11:35:30Z"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalItems": 2
  }
}

✅ Success! Events are now being tracked through the merchant's domain.

DNS Troubleshooting

Common Issues and Solutions

Issue: DNS Not Propagating

Symptoms: Verification keeps returning pending_dns

Diagnostic Steps:

bash

# Check if CNAME exists
dig mtag-h7k9.enterprisestore.com CNAME

# Check from Google's DNS
dig @8.8.8.8 mtag-h7k9.enterprisestore.com CNAME

# Check from Cloudflare's DNS
dig @1.1.1.1 mtag-h7k9.enterprisestore.com CNAME

Solutions:

Verify CNAME record is saved in DNS provider
Check for typos in hostname or target
Ensure no conflicting A/AAAA records exist
Wait additional time for propagation

Clear local DNS cache:

bash

# macOS
sudo dscacheutil -flushcache

# Linux
sudo systemd-resolve --flush-caches

# Windows
ipconfig /flushdns

Issue: Cloudflare Orange Cloud Enabled

Symptoms: CNAME points to Cloudflare proxy instead of tracking.markopolo.ai

Solution:

Go to Cloudflare DNS settings
Find the CNAME record
Click the orange cloud icon to turn it gray (DNS only)
Wait 5 minutes and verify again

Issue: Conflicting Records

Symptoms: Cannot add CNAME, error about existing records

Solution:

Check for existing A or AAAA records for the same subdomain
Remove conflicting records
Add CNAME record
Example check:
bash
```
dig mtag-h7k9.enterprisestore.com ANY
```

Issue: SSL Certificate Errors

Symptoms: HTTPS errors when loading the tracking script

Diagnostic:

bash

curl -I https://mtag-h7k9.enterprisestore.com/health

Solution:

Ensure CNAME is correctly pointing to tracking.markopolo.ai
SSL certificates are automatically provisioned after verification
May take 5-10 minutes after DNS verification

Important DNS Notes

Subdomain Generation:

The API automatically generates a unique subdomain (e.g., mtag-h7k9)
You cannot choose your own subdomain
Each marktag gets its own unique subdomain identifier
The subdomain format is always mtag-xxxx where xxxx is a 4-character code
For multiple environments (staging, production), generate separate marktags - each will get its own unique subdomain

Migration from Client-Side

If migrating from client-side to server-side MarkTag:

Step 1: Setup Server-Side in Parallel

Keep client-side MarkTag active
Generate server-side MarkTag
Configure DNS
Wait for verification

Step 2: Install Both Scripts Temporarily

html

<!-- Temporary: both tracking implementations during migration -->

<!-- Client-Side MarkTag -->
<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>

<!-- Server-Side MarkTag -->
<script>
  // Note: Using same mtrem/mtag is fine, both will be processed
  mtag("init", "https://mtag-h7k9.enterprisestore.com?tagId=server-xyz789", {
    consent: true,
  });
</script>
<script async src="https://mtag-h7k9.enterprisestore.com/script"></script>

Step 3: Verify Server-Side is Working

bash

# Check events from server-side domain
curl -X GET "https://api-alpha.markopolo.ai/v1/partners/events?tagId=server-xyz789" \
  -H "Authorization: Bearer mp_live_YOUR_TOKEN"

Step 4: Remove Client-Side

Once confirmed, remove the client-side scripts:

html

<!-- Only server-side now -->
<script>
  window.mtrem = window.mtrem || [];
  function mtag() {
    mtrem.push(arguments);
  }
  mtag("init", "https://mtag-h7k9.enterprisestore.com?tagId=server-xyz789", {
    consent: true,
  });
</script>
<script async src="https://mtag-h7k9.enterprisestore.com/script"></script>

Best Practices

Subdomain Configuration - Use the exact subdomain provided by the API response (e.g., mtag-h7k9)
TTL Settings - Start with lower TTL (300-3600) during setup, increase later
DNS Monitoring - Set up monitoring for CNAME record
SSL Verification - Always verify HTTPS is working before installing script
Parallel Testing - Run alongside existing tracking tools during initial setup
Documentation - Document the DNS configuration for merchant's records

API Reference

Generate Server-Side MarkTag

POST /v1/partners/marktag

Request Body:

json

{
  "merchantId": "string",
  "type": "server_side",
  "domain": "string"
}

Response:

json

{
  "tagId": "string",
  "record": {
    "type": "CNAME",
    "name": "mtag-h7k9",
    "value": "mts1.markopolo.ai",
    "ttl": 300
  },
  "status": "inactive",
  "message": "New tag created successfully",
  "type": "server-side"
}

Verify DNS Configuration

POST /v1/partners/marktag/verify

Request Body:

json

{
  "tagId": "string",
  "subdomain": "string"
}

Response (200 - Success):

json

{
  "verified": true
}

Next Steps

Monitor events after installation
Manage multiple merchants
Explore client-side implementation for quick setup
Learn about preverified implementation for platform integration

Server-Side MarkTag Implementation ​

Overview ​

Prerequisites ​

Complete Implementation Flow ​

Step 1: Create Merchant Account ​

Step 2: Generate Server-Side MarkTag ​

Step 3: Configure DNS ​

DNS Configuration Details ​

DNS Provider Instructions ​

Cloudflare ​

GoDaddy ​

AWS Route 53 ​

Namecheap ​

Step 4: Wait for DNS Propagation ​

Check DNS Propagation ​

Step 5: Verify DNS Configuration via API ​

Step 6: Install the Tracking Script ​

Extract TAG_ID and Domain ​

Installation Options ​

Option A: Direct HTML ​

Option B: Dynamic Installation ​

Step 7: Verify Tracking ​

DNS Troubleshooting ​

Common Issues and Solutions ​

Issue: DNS Not Propagating ​

Issue: Cloudflare Orange Cloud Enabled ​

Issue: Conflicting Records ​

Issue: SSL Certificate Errors ​

Important DNS Notes ​

Migration from Client-Side ​

Step 1: Setup Server-Side in Parallel ​

Step 2: Install Both Scripts Temporarily ​

Step 3: Verify Server-Side is Working ​

Step 4: Remove Client-Side ​

Best Practices ​

API Reference ​

Generate Server-Side MarkTag ​

Verify DNS Configuration ​

Next Steps ​

Server-Side MarkTag Implementation

Overview

Prerequisites

Complete Implementation Flow

Step 1: Create Merchant Account

Step 2: Generate Server-Side MarkTag

Step 3: Configure DNS

DNS Configuration Details

DNS Provider Instructions

Cloudflare

GoDaddy

AWS Route 53

Namecheap

Step 4: Wait for DNS Propagation

Check DNS Propagation

Step 5: Verify DNS Configuration via API

Step 6: Install the Tracking Script

Extract TAG_ID and Domain

Installation Options

Option A: Direct HTML

Option B: Dynamic Installation

Step 7: Verify Tracking

DNS Troubleshooting

Common Issues and Solutions

Issue: DNS Not Propagating

Issue: Cloudflare Orange Cloud Enabled

Issue: Conflicting Records

Issue: SSL Certificate Errors

Important DNS Notes

Migration from Client-Side

Step 1: Setup Server-Side in Parallel

Step 2: Install Both Scripts Temporarily

Step 3: Verify Server-Side is Working

Step 4: Remove Client-Side

Best Practices

API Reference

Generate Server-Side MarkTag

Verify DNS Configuration

Next Steps