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を設定します。
• CMPからライブのTC文字列を渡します（例：_ _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)
    }
  ]
}

レスポンスフィールドの定義

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}"
  }
}