Markopolo Documentation

Appearance

MarkTag Implementation Guide ​

This guide explains how to connect the Partners API responses with the MarkTag SDK. The SDK requires two parameters (TAG_DOMAIN and TAG_ID) that you'll extract from the API responses.

Overview ​

The Web SDK Installation Guide shows the tracking script that needs to be installed on merchant websites. This guide explains how to get the required values from the Partners API:

  • TAG_DOMAIN: Obtained from the subdomain field in API responses - this replaces {{TAG_DOMAIN}} in the SDK installation script
  • TAG_ID: Obtained from the tagId field in API responses - this replaces {{TAG_ID}} in the SDK installation script

Using Generate MarkTag Response ​

When you generate a MarkTag using POST /v1/partners/marktag/generate, you'll receive:

json
{
  "record": {
    "type": "CNAME",
    "name": "mtag-abc",
    "meta": {
      "subdomain": "mtag-abc.yourpartner.com"
    },
    "value": "mts2.markopolo.ai",
    "ttl": 3600
  },
  "tagId": "ABC123",
  "status": "inactive",
  "message": "New tag created successfully"
}

Mapping to SDK Parameters ​

Extract these values for the SDK installation:

  • TAG_DOMAIN (for {{TAG_DOMAIN}} in SDK): Use record.meta.subdomain → mtag-abc.yourpartner.com
  • TAG_ID (for {{TAG_ID}} in SDK): Use tagId → ABC123

Using Get Merchants Response ​

When you retrieve merchants using GET /v1/partners/merchant, you'll receive:

json
{
  "merchants": [
    {
      "merchantId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Example Merchant",
      "createdAt": "2025-01-25T10:30:00Z",
      "marktags": [
        {
          "tagId": "XYZ789",
          "subdomain": "mtag-xyz.yourpartner.com",
          "status": "inactive",
          "createdAt": "2025-01-25T10:30:00Z"
        },
        {
          "tagId": "DEF456",
          "subdomain": "mtag.merchant.com",
          "status": "active",
          "createdAt": "2025-01-26T10:30:00Z"
        }
      ]
    }
  ]
}

Mapping to SDK Parameters ​

Extract these values for the SDK installation:

  • TAG_DOMAIN (for {{TAG_DOMAIN}} in SDK): Use subdomain → mtag.merchant.com
  • TAG_ID (for {{TAG_ID}} in SDK): Use tagId → DEF456

Implementing MarkTag on the Website ​

Once you have extracted the TAG_DOMAIN and TAG_ID values from the API response, use them to replace the placeholders in the SDK installation script.

Step 1: Review the SDK Template ​

The MarkTag SDK provides this template that needs to be added to the <head> section of every page:

html
<script>
  window.mtrem = window.mtrem || [];
  function mtag() {
    mtrem.push(arguments);
  }
  mtag("init", "{{TAG_DOMAIN}}?tagId={{TAG_ID}}", { consent: true });
</script>

<script
  async
  type="text/javascript"
  src="https://{{TAG_DOMAIN}}/script"
></script>

Step 2: Replace SDK Placeholders with API Values ​

Replace {{TAG_DOMAIN}} and {{TAG_ID}} from the SDK template with the actual values from your API response:

Example using Generate MarkTag response:

html
<script>
  window.mtrem = window.mtrem || [];
  function mtag() {
    mtrem.push(arguments);
  }
  mtag("init", "https://mtag-abc.yourpartner.com?tagId=ABC123", {
    consent: true,
  });
</script>

<script
  async
  type="text/javascript"
  src="https://mtag-abc.yourpartner.com/script"
></script>

Example using Get Merchants response (active tag):

html
<script>
  window.mtrem = window.mtrem || [];
  function mtag() {
    mtrem.push(arguments);
  }
  mtag("init", "https://mtag.merchant.com?tagId=DEF456", { consent: true });
</script>

<script
  async
  type="text/javascript"
  src="https://mtag.merchant.com/script"
></script>

Complete Implementation Example ​

Here's a complete example showing how to integrate the Partners API with your platform:

1. Generate MarkTag for a Merchant ​

javascript
// Generate a MarkTag
const response = await fetch(
  "https://api-alpha.markopolo.ai/v1/partners/marktag/generate",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer mp_live_YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      merchantId: "550e8400-e29b-41d4-a716-446655440000",
      domain: "example.com",
    }),
  },
);

const data = await response.json();

2. Extract Parameters from Response ​

javascript
// Extract the necessary parameters
const tagDomain = data.record.meta?.subdomain || data.subdomain;
const tagId = data.tagId;

console.log("TAG_DOMAIN:", tagDomain); // e.g., "mtag-abc.yourpartner.com"
console.log("TAG_ID:", tagId); // e.g., "ABC123"

3. Generate the Tracking Code ​

javascript
// Generate the tracking code for the merchant
const trackingCode = `
<script>
  window.mtrem = window.mtrem || [];
  function mtag() { mtrem.push(arguments) };
  mtag("init", "https://${tagDomain}?tagId=${tagId}", {"consent":true});
</script>

<script async type="text/javascript" src="https://${tagDomain}/script"></script>
`;

// Provide this code to your merchant to add to their website
console.log("Add this code to your website <head>:", trackingCode);

Important Notes ​

Status Field ​

  • active: The MarkTag is verified and collecting events
  • inactive: The MarkTag needs DNS verification (for custom domains) or hasn't been installed yet

Preverified vs Custom Domains ​

  • Preverified domains (under your partner domain): Activate instantly, no DNS setup required by merchant
  • Custom domains: Require the merchant to add CNAME records and verify through the API

Multiple MarkTags ​

A merchant can have multiple MarkTags:

  • One for their primary domain
  • Additional tags for subdomains or other properties
  • Choose the appropriate tag based on where it will be installed

Next Steps ​

  1. For Preverified Domains: The tracking code can be installed immediately
  2. For Custom Domains:
    • Merchant must add the CNAME record provided in the response
    • Use the Verify MarkTag endpoint to check DNS setup
    • Once verified, install the tracking code

Additional Resources ​

Copyright © 2026 Markopolo AI