Brand Page APIs

การกำหนดเส้นทาง URL

เมื่อผู้ใช้ไปยัง URL ของแบรนด์เพจ แอปพลิเคชันของคุณจะดึง urlSlug จากเส้นทางและส่งไปยัง API สำหรับการให้บริการโฆษณา

โครงสร้าง URL: <https://{your-domain}/{prefix}/{urlSlug}>

ตัวอย่าง

เมื่อผู้ใช้เข้าชม: <https://www.retailer.com/brands/adidas:>

1. แอปพลิเคชันของคุณตรงกับเส้นทาง /brands/*
2. แยก adidasเป็น URLSlug
3. การโทร POST /ads/v3/brand-pages ในโฮสต์โฆษณาที่ได้รับมอบหมายด้วย "urlSlug": "adidas" และ catalogIdของคุณ
4. แสดงโมดูลเนื้อหาที่ส่งคืนบนเพจ

กฎการตรวจสอบความถูกต้องของส่วนท้าย

แบรนด์สร้างส่วนท้ายตามข้อจำกัดเหล่านี้:

• Characters: Lowercase letters (a–z), numbers (0–9), hyphens (-), and underscores (_).
• Length: Minimum 3 characters, maximum 100 characters.
• Uniqueness: Must be unique within the retailer’s catalog (catalogId).

• Immutability: Cannot be changed after the brand page campaign is live.
• Format: No leading or trailing hyphens (for example, -adidasor adidas- are not allowed).

การแคช

• อย่าแคชการตอบกลับจาก API การแสดงโฆษณา ส่งคําขอโดยตรงไปยัง Epsilon API เสมอเพื่อให้แน่ใจว่า:
  • แคมเปญแบรนด์เพจที่ถูกต้องจะถูกนำเสนอ (แคมเปญอาจถูกหยุดชั่วคราว อัปเดต หรือเปลี่ยนแปลง)
  • URL สำหรับติดตามประกอบด้วยรหัสระบุเฉพาะสำหรับการขอใช้งานแต่ละครั้ง เพื่อการระบุลักษณะที่แม่นยำ
  • จำนวนการแสดงผลยังคงความแม่นยำและไม่ได้รับผลกระทบจากการตอบสนองแคชที่ล้าสมัย

การพิจารณา SEO: ผู้ค้าปลีกอาจเลือกที่จะอนุญาตให้แบรนด์เพจถูกจัดทำดัชนีโดยเครื่องมือค้นหา การจัดทำดัชนีเนื้อหาแบรนด์เพจสามารถช่วยเพิ่มการมองเห็นได้ในการค้นหาอินทรีย์ เนื่องจากข้อความทั้งหมดในหน้าสามารถค้นพบได้โดยเครื่องมือค้นหา

การตั้งค่าพร็อกซีย้อนกลับ

เหตุผลที่คุณควรใช้พร็อกซีย้อนกลับ

ปัญหา: ตัวบล็อกโฆษณาและเครื่องมือรักษาความเป็นส่วนตัวมักบล็อกคำขอติดตามที่ส่งไปยังโดเมนโฆษณาโดยตรง

วิธีแก้ไข: ส่งเส้นทางคำขอการติดตามทั้งหมดผ่านโดเมนของคุณเอง เพื่อให้ปรากฏเป็นการเข้าชมของบุคคลที่หนึ่ง

❌ Blocked: user-browser → [third-party-tracking-domain]  
✅ Works:   user-browser → yoursite.com/[custom-path] → [third-party-tracking-domain]

• แทนที่ [third-party-tracking-domain] ด้วยเอนพอยต์การติดตาม Epsilon จริงที่ให้ไว้ระหว่างขั้นตอนการลงทะเบียน
• แทนที่ [custom-path] ด้วยพาธที่เป็นกลางและไม่ซ้ำกัน (เช่น /media-proxy, /assets-endpoint, หรือคำที่ไม่ใช่โฆษณา)

A reverse proxy is required for C2S (browser) tracking. It does not apply to S2S calls, which must be sent directly to the Epsilon tracking host (see Tracking – Server-to-Server (S2S)).

การกำหนดค่า

Your site must host a reverse proxy under a path such as https://www.retailer.com/{proxyPath}/. Browser (C2S) tracking requests to your domain on that path are forwarded to your regional tracking host (see Ad Serving API). Server-to-server tracking must not use this proxy.

พฤติกรรม:

• ยอมรับคำขอภายใต้… /epsilon/
• Forward to https://[region]-tracking.rmn.dotomi.com/ (see Ad Serving API for [region])
• รักษาส่วนต่อท้ายเส้นทางไฟล์
• ส่งต่อส่วนหัว HTTP ที่จําเป็น
• บังคับใช้ HTTPS (TLS 1.2+)

ส่วนหัวที่จำเป็น

ตัวอย่าง Apache

LoadModule ssl_module modules/mod_ssl.so
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.so
SSLProxyEngine on
RequestHeader add "X-Forwarded-Request-Path" "/epsilon"
RequestHeader add "RP-Host" "%{HTTP_HOST}s"
RequestHeader add "Referer" "%{HTTP_REFERER}s"
ProxyPass "/epsilon" "https://[region]-tracking.rmn.dotomi.com"
ProxyPassReverse "/epsilon" "https://[region]-tracking.rmn.dotomi.com/"

ตัวอย่าง NGINX

server {
    server_name www.retailer.com;
    location /epsilon/ {
        proxy_ssl_server_name on;
        rewrite ^/epsilon/(.*) /$1 break;
        proxy_pass https://[region]-tracking.rmn.dotomi.com;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Server $server_name;
        proxy_set_header RP-Host $host;
        proxy_set_header X-Forwarded-Request-Path "/epsilon";
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Referer $http_referer;
    }
}

API การแสดงโฆษณา

Epsilon serves brand pages from RMN hosts on *.rmn.dotomi.com. Substitute [region] with the segment Epsilon assigns for your deployment.

The ads API uses https://[region]-ads.rmn.dotomi.com; while tracking endpoints (impression pixels, click redirects, and S2S notification URLs) uses https://[region]-tracking.rmn.dotomi.com with the same [region] value.

In some setups, the base hostnames ads.rmn.dotomi.com and tracking.rmn.dotomi.com may be used. Epsilon will confirm the appropriate hostnames for your environment.

เอ็นพอยต์

POST https://[region]-ads.rmn.dotomi.com/ads/v3/brand-pages
Content-Type: application/json
Authorization: Basic <existing_api_key>

ข้อมูลเพย์โหลดคำขอ

{
  "id": "req-adidas-12345",
  "catalogId": "test-catalog-adidas",
  "urlSlug": "adidas",
  "site": {
    "domain": "www.retailer.com",
    "page": "https://www.retailer.com/brand/adidas",
    "ref": "https://www.retailer.com/search?q=shoes"
  },
  "device": {
    "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 ...",
    "ip": "192.168.1.100",
    "language": "en-US",
    "devicetype": 2,
    "os": "macOS",
    "geo": {
      "country": "USA",
      "region": "CA",
      "city": "San Francisco",
      "zip": "94105"
    }
  },
  "user": {
    "sessionId": "sess-abc123xyz",
    "customerId": "cust-789012",
    "dtmId": "dtm-456def"
  },
  "regs": {
    "gdpr": 1,
    "consent": "COwJqZAOwJqZAOAAAAENAXCAAAAAAAAAAAAAABpoAIAAAEpgAIAAAg1AAAICAIAAAEA"
  }
}

The regs values above illustrate the GDPR-applicable traffic:
gdpr is 1, and consentis a synthetic IAB TCF v2 consent string (correct shape and charset only).

ในสภาพแวดล้อมการผลิต:

• ตั้งค่า gdprจากกฎทางภูมิศาสตร์และกฎหมายของท่าน
• ส่ง สตริง TC แบบสด จาก CMP ของคุณ (ตัวอย่างเช่นผ่าน _ _tcfapi getTCData→ tcString)

สําหรับคําขอที่ไม่เป็นไปตาม GDPR ให้ใช้ "gdpr": 0 และละเว้น consentหรือใช้ ""

iabConsentString on tracking events: Every populated tracker slot (trackers.impression, trackers.click, trackers.addToCart) includes params.iabConsentString. When you provide regs.consent on the request, this value is the literal TC string.

When you omitted regs.consent, this value is the {TCF} macro placeholder - substitute the current TCF v2 string from your CMP (for example via __tcfapi getTCData → tcString) at fire time before sending any tracking request.

คำจำกัดความของฟิลด์ที่ร้องขอ

เพย์โหลดของการตอบกลับ

{
  "realizedAdId": "brandpage_djogXfHSYGZOZnnkzEKunWvdNYEKABIAGgwIwIPjzAYQ3byasAE=",
  "brandPageTemplateId": "6e9690ef-81d1-4fad-b2ce-749e22cceb10",
  "catalogId": "test-catalog-adidas",
  "urlSlug": "adidas",
  "theme": {
    "colors": {
      "background": "#F5F5F5",
      "text": {
        "heading": "#1a1a1a",
        "subheading": "#333333",
        "body": "#5f6368",
        "caption": "#9aa0a6",
        "link": "#1a73e8",
        "tagline": "#5f6368",
        "lines": "#e0e0e0"
      }
    },
    "buttons": {
      "primary": {
        "background": "#ff6600",
        "text": "#FFFFFF"
      },
      "secondary": {
        "background": "#FFFFFF",
        "text": "#ff6600"
      }
    }
  },
  "trackers": {
    "impression": {
      "type": "impression",
      "params": { "ts": "{TS}", "iabConsentString": "{TCF}" }
    }
  },
  "trackingTypes": {
    "impression":      ["client.impressionPixelUrls", "server.impressionEvent"],
    "productClick":    ["client.clickRedirect", "client.clickEvent", "server.clickEvent"],
    "productAddToCart": ["client.addToCartEvent", "server.addToCartEvent"],
    "link":            ["client.clickRedirect", "client.clickEvent", "server.clickEvent"],
    "interaction":     ["client.clickEvent", "server.clickEvent"]
  },
  "trackingTemplates": {
    "client": {
      "clickRedirect":       "/tracking/v3/click/redirect/brandpage_djog...?catalogId=test-catalog-adidas&...",
      "clickEvent":          "/tracking/v3/event/click/brandpage_djog...?catalogId=test-catalog-adidas&...",
      "addToCartEvent":      "/tracking/v3/event/add-to-cart/brandpage_djog...?catalogId=test-catalog-adidas&...",
      "impressionPixelUrls": [
        "/tracking/v3/impression/pixel/brandpage_djog...?catalogId=test-catalog-adidas&..."
      ]
    },
    "server": {
      "clickEvent":          "https://[region]-tracking.rmn.dotomi.com/tracking/v3/event/click/brandpage_djog...?...",
      "addToCartEvent":      "https://[region]-tracking.rmn.dotomi.com/tracking/v3/event/add-to-cart/brandpage_djog...?...",
      "impressionEvent":     "https://[region]-tracking.rmn.dotomi.com/tracking/v3/event/impression/brandpage_djog...?..."
    }
  },
  "contentData": [
    {
      "id": "hero-1",
      "brandPageModuleTemplateId": "hero-template-1",
      "contentType": "HERO",
      "order": 1,
      "tags": ["header"],
      "mediaUrl": "https://example.com/images/adidas-hero.jpg",
      "headline": "Impossible Is Nothing",
      "subheadline": "Spring Collection",
      "ctaText": "Explore",
      "ctaLink": "https://example.com/adidas/explore",
      "trackers": {
        "click": {
          "type": "link",
          "params": {
            "modId": "hero-1",
            "rurl": "https%3A%2F%2Fexample.com%2Fadidas%2Fexplore",
            "ts": "{TS}",
            "iabConsentString": "{TCF}"
          }
        }
      }
    },
    {
      "id": "text-1",
      "brandPageModuleTemplateId": "text-template-1",
      "contentType": "TEXT",
      "order": 2,
      "text": "Discover the latest Adidas collection featuring innovative designs and sustainable materials."
      // (No trackers for TEXT module, as it has no interactive elements)
    }
  ]
}

คำนิยามฟิลด์ของ Response

Theme Object

Every successful Brand Page API response includes a theme object: page-level colors and button styles configured for the brand. Apply these values when rendering (for example, map them to CSS custom properties or your design tokens). The JSON is produced by the ad server and delivered as returned - there is no separate step that rewrites the theme.

Color format: Theme color values follow the platform contract from upstream (campaign/configuration): each value is a # followed by six hexadecimal digits (hex6), for example, #ff6600. Do not expect other formats (short hex3, eight-digit hex, rgb(), hsl(), or named colors). The ad server does not revalidate color format at serve time; upstream supplies hex6 for every theme field.

Structure and semantics

• theme contains colors and buttons - both are required whenever theme is present.
• colors.background - page or canvas background (required hex6).
• colors.text - seven required roles: heading, subheading, body, caption, link, tagline, lines (lines/dividers). Each value is a hex6 string.
• buttons.primary and buttons.secondary - each requires background and text (button fill and label colors), each a hex6 string.
• Every path in the field reference table below is required. There are no optional color slots and no null values inside theme. (Sparse or omitted fields apply elsewhere, for example in contentData modules.)
• The theme is page-level -all modules on the Brand Page share the same theme.

Field reference

All paths in this table are required (non-null hex6 strings).

Example - (themeobject only):

"theme": {
  "colors": {
    "background": "#F5F5F5",
    "text": {
      "heading": "#1a1a1a",
      "subheading": "#333333",
      "body": "#5f6368",
      "caption": "#9aa0a6",
      "link": "#1a73e8",
      "tagline": "#5f6368",
      "lines": "#e0e0e0"
    }
  },
  "buttons": {
    "primary": {
      "background": "#ff6600",
      "text": "#FFFFFF"
    },
    "secondary": {
      "background": "#FFFFFF",
      "text": "#ff6600"
    }
  }
}

ต่อโหนด params(คีย์มาตรฐาน)

Template-dependent fields in contentData

Aside from core discriminators on each module (id, brandPageModuleTemplateId, contentType, order), property presence is not uniform across Brand Pages. Prefer feature detection - check each property before use - rather than treating every field in examples as mandatory.

The API may represent "no value" in several ways:

ตัวอย่างสำหรับประเภทโมดูลทั่วไป

ตารางผลิตภัณฑ์:

Each product row includes a product object (catalogId, productCode, sellerId), an order value, and trackers when the row is trackable. Product rows provide both a click slot (type: "productClick") and an addToCartslot (type: "productAddToCart") when the SKU is attributable.

{
  "product": {
    "catalogId": "550e8400-e29b-41d4-a716-446655440001",
    "productCode": "9221200653341",
    "sellerId": "2ae0aab9-44ce-40a0-b2b9-ae61681ad224"
  },
  "order": 1,
  "trackers": {
    "click": {
      "type": "productClick",
      "params": {
        "modId": "grid-1",
        "productCode": "9221200653341",
        "sellerId": "2ae0aab9-44ce-40a0-b2b9-ae61681ad224",
        "rurl": "{RURL}",
        "ts": "{TS}",
        "iabConsentString": "{TCF}"
      }
    },
    "addToCart": {
      "type": "productAddToCart",
      "params": {
        "modId": "grid-1",
        "productCode": "9221200653341",
        "sellerId": "2ae0aab9-44ce-40a0-b2b9-ae61681ad224",
        "rurl": "{RURL}",
        "ts": "{TS}",
        "qty": "{QTY}",
        "conVal": "{CONVERSION_VALUE}",
        "iabConsentString": "{TCF}"
      }
    }
  }
}

ฮีโร่:

Headline, subheadline, CTA text and link, image, overlay, and trackers.click for the CTA when present.

{
  "contentType": "HERO",
  "tags": [
    "header"
  ],
  "mediaUrl": "https://example.com/images/adidas-hero.jpg",
  "headline": "Impossible Is Nothing",
  "subheadline": "Spring Collection",
  "ctaText": "Explore",
  "ctaLink": "https://example.com/adidas/explore",
  "trackers": {
    "click": {
      "type": "link",
      "params": {
        "modId": "hero-1",
        "rurl": "https%3A%2F%2Fexample.com%2Fadidas%2Fexplore",
        "ts": "{TS}",
        "iabConsentString": "{TCF}"
      }
    }
  }
}

แกลเลอรีรูปภาพ:

An array of images, each with a URL, alt text, and caption. trackers.click for an image only when that image links out.

{
  "contentType": "IMAGE_GALLERY",
  "galleryImages": [
    {
      "url": "https://example.com/images/recipe-spaghetti-bolognese.jpg",
      "alt": "Spaghetti Bolognese",
      "caption": "Spaghetti Bolognese",
      "trackers": {
        "click": {
          "type": "link",
          "params": {
            "modId": "gallery-1",
            "rurl": "https%3A%2F%2Fexample.com%2Frecipes%2Fspaghetti",
            "ts": "{TS}",
            "iabConsentString": "{TCF}"
          }
        }
      }
    }
  ]
}

ข้อความ:

Headline and body text, with no trackersunless a link is present on a line.

{
  "contentType": "TEXT",
  "text": "Explore our newest arrivals designed for comfort, style, and performance."
}

รูปภาพ:

Includes an image URL, caption, alt text, optional link and trackers.click details when the image is clickable

{
  "contentType": "IMAGE",
  "imageUrl": "https://example.com/images/model.jpg",
  "caption": "New arrivals now available",
  "alt": "Model wearing summer collection",
  "trackers": { "click": { "type": "link", "params": { "modId": "image-1", "rurl": "https%3A%2F%2Fexample.com%2Fnew-arrivals", "ts": "{TS}", "iabConsentString": "{TCF}"
  }
}