自定义元数据支持 custom-metadata-support

最近更新： 2026年5月19日

主题：
{"id":"fd307ce7-56f5-4ee3-af68-a7833ff6e85e"}

创建对象：

{"id":"b69b2659-1057-424e-8fc5-ed9e016dc554"},{"id":"c66ffd68-0f65-42bb-aa23-b4020f12e0bd"},{"id":"ff6a42d2-313e-452e-93a6-792e4fad9ff8"}

媒体收集API允许您在sessionStart、adStart和chapterStart事件中随标准参数一起发送自定义键值对。自定义元数据通过相应的媒体关闭事件转发到Adobe Analytics。

要使此数据在Analysis Workspace中可用，客户必须定义自定义eVar并配置处理规则，以根据其用例填充这些数据。在映射到eVar或prop后，如果配置了Analytics源连接器，则数据也可以通过相应的eVar路径在Adobe Experience Platform中可用。

对于使用Experience Edge的基于XDM的实施，请参阅自定义元数据支持 — XDM格式。

概述

自定义元数据作为customMetadata对象包含在请求正文中，位于params键旁边。它适用于三种事件类型：

事件

元数据应用于

sessionStart

主要内容（整个会话）

adStart

个人广告

chapterStart

内容章节或区段

结构

自定义元数据是事件级别的平面对象（键值对），与params键一起使用：

{
  "playerTime": {
    "playhead": 0,
    "ts": 1646938800000
  },
  "eventType": "sessionStart",
  "params": {
    "analytics.trackingServer": "example.sc.omtrdc.net",
    "analytics.reportSuite": "example-rsid",
    "visitor.marketingCloudOrgId": "0123456789@AdobeOrg",
    "media.id": "sample-video-id",
    "media.length": 3600,
    "media.contentType": "vod",
    "media.playerName": "HTML5 Player",
    "media.channel": "Sports"
  },
  "customMetadata": {
    "field": "value"
  }
}

按事件类型列出的必需参数

事件

必需params

sessionStart

analytics.trackingServer, analytics.reportSuite, visitor.marketingCloudOrgId, media.id, media.length, media.contentType, media.playerName, media.channel

adStart

media.ad.id, media.ad.length, media.ad.podPosition, media.ad.playerName

chapterStart

media.chapter.length, media.chapter.offset, media.chapter.index

关键命名要求

避免在自定义元数据键中使用media.前缀 — 它映射到标准媒体字段，并且可能会在Analytics报表中覆盖它们
a.前缀是为Adobe标准元数据保留的，不得使用

主内容自定义元数据

与sessionStart一起发送。适用于被跟踪的主媒体，并在整个广告和章节调用中保持可用。此处定义的任何自定义元数据都将由媒体后端在相应的关闭调用中自动合并。它将与为广告和章节定义的任何特定自定义元数据一起包含。

curl -X POST "https://{uri}/api/v1/sessions" \
--header 'Content-Type: application/json' \
--data '{
  "playerTime": {
    "playhead": 0,
    "ts": 1646938800000
  },
  "eventType": "sessionStart",
  "params": {
    "analytics.trackingServer": "example.sc.omtrdc.net",
    "analytics.reportSuite": "example-rsid",
    "analytics.visitorId": "visitor123",
    "visitor.marketingCloudOrgId": "0123456789@AdobeOrg",
    "media.id": "sample-video-id",
    "media.name": "Sample Video",
    "media.length": 3600,
    "media.contentType": "vod",
    "media.playerName": "HTML5 Player",
    "media.channel": "Sports"
  },
  "customMetadata": {
    "contentCategory": "Live Sports",
    "leagueType": "Professional",
    "broadcastRights": "Premium"
  }
}'

广告自定义元数据

与adStart一起发送。特定于每个单独广告。来自sessionStart的自定义元数据也将由广告关闭调用上的媒体后端与此处定义的任何特定于广告的自定义元数据自动合并。

curl -X POST "https://{uri}/api/v1/sessions/{sid}/events" \
--header 'Content-Type: application/json' \
--data '{
  "playerTime": {
    "playhead": 30,
    "ts": 1646938830000
  },
  "eventType": "adStart",
  "params": {
    "media.ad.id": "summer-sale-2026",
    "media.ad.name": "Summer Sale Ad",
    "media.ad.length": 30,
    "media.ad.playerName": "HTML5 Player",
    "media.ad.podPosition": 1
  },
  "customMetadata": {
    "campaignId": "SUMMER2026",
    "targetAudience": "18-34",
    "adFormat": "skippable"
  }
}'

章节自定义元数据

与chapterStart一起发送。特定于每个内容章节或区段。来自sessionStart的自定义元数据也将由媒体后端在章节关闭调用中自动合并，以及此处定义的任何特定于章节的自定义元数据。

curl -X POST "https://{uri}/api/v1/sessions/{sid}/events" \
--header 'Content-Type: application/json' \
--data '{
  "playerTime": {
    "playhead": 600,
    "ts": 1646938200000
  },
  "eventType": "chapterStart",
  "params": {
    "media.chapter.friendlyName": "Introduction",
    "media.chapter.length": 300,
    "media.chapter.index": 1,
    "media.chapter.offset": 600
  },
  "customMetadata": {
    "chapterType": "tutorial",
    "difficulty": "beginner",
    "instructor": "Jane Smith"
  }
}'

行为

所有自定义元数据值必须是字符串。发送之前转换数字和布尔值。
自定义元数据显示在Analytics中，前缀为c.（例如，contentCategory→c.contentCategory）
通过Analytics处理规则将自定义元数据映射到eVar、prop或上下文数据变量
sessionStart元数据在整个会话中持续存在；更新需要新会话
每个adStart和chapterStart事件都可以携带不同的自定义元数据