From 68575373a3222ffc6ba941cf0c9de5f356e01187 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Fri, 13 Nov 2026 21:41:37 +0000 Subject: [PATCH] feat(schema): add Instagram, Facebook, Snapchat and X distribution identifier types A creator's social channels go in collection.distribution[].identifiers, but only YouTube, TikTok, Twitch and Substack had their own identifier types. Instagram, Facebook, Snapchat and X fit only platform_channel_id, which can't be used in bare identifier contexts such as exclude filters. Adds eight values, a stable ID plus a handle alias for each platform, and normalizes the handles the way youtube_channel_handle already is. Refs #8992. Co-Authored-By: Claude Opus 5.5 --- .changeset/social-distribution-identifiers.md | 13 +++++++ .../collections-and-installments.mdx | 2 +- .../collection-identifier-normalization.ts | 24 +++++++++++-- ...ollection-identifier-normalization.test.ts | 36 +++++++++++++++++++ .../enums/distribution-identifier-type.json | 18 +++++++++- tests/check-platform-agnostic.cjs | 6 ++++ tests/x-added-in-3-3-sweep.test.cjs | 1 + 7 files changed, 95 insertions(+), 5 deletions(-) create mode 100644 .changeset/social-distribution-identifiers.md create mode 100644 server/tests/unit/services/collection-identifier-normalization.test.ts diff --git a/.changeset/social-distribution-identifiers.md b/.changeset/social-distribution-identifiers.md new file mode 100644 index 00000000000..27d644246c3 --- /dev/null +++ b/.changeset/social-distribution-identifiers.md @@ -0,0 +1,13 @@ +--- +"adcontextprotocol": minor +--- + +Add Instagram, Facebook, Snapchat and X to `distribution-identifier-type` (adcp#8992), so a creator's social channels can be listed in `collection.distribution[].identifiers` and matched across sellers without falling back to `platform_channel_id`. + +Eight values, following the YouTube pattern: a stable ID is the canonical identifier, and a handle is a discovery alias that should resolve to it. +- `instagram_account_id` and `instagram_handle` +- `facebook_page_id` and `facebook_page_handle` +- `snapchat_profile_id` and `snapchat_handle` +- `x_user_id` and `x_handle` + +Registries compare handles case-insensitively, as `@` plus the lowercased name, as they already do for `youtube_channel_handle`. The enum description notes the values were added in AdCP 3.3. Adding enum values is additive: every identifier list that accepts these values already accepted `platform_channel_id`, so nothing that validated before stops validating. diff --git a/docs/media-buy/product-discovery/collections-and-installments.mdx b/docs/media-buy/product-discovery/collections-and-installments.mdx index caffb7bf78d..8573b1b5ae7 100644 --- a/docs/media-buy/product-discovery/collections-and-installments.mdx +++ b/docs/media-buy/product-discovery/collections-and-installments.mdx @@ -1229,7 +1229,7 @@ Collections SHOULD include at least one platform-independent identifier when ava -Available podcast types: `apple_podcast_id`, `spotify_collection_id`, `rss_url`, `podcast_guid`, `amazon_music_id`, `iheart_id`, `podcast_index_id`. Available video/CTV types: `youtube_channel_id`, `youtube_channel_handle`, `youtube_channel_url`, `youtube_playlist_id`, `amazon_title_id`, `platform_channel_id`, `roku_channel_id`, `pluto_channel_id`, `tubi_id`, `peacock_id`, `tiktok_id`, `twitch_channel`. Other: `domain`, `substack_id`. For YouTube channels, `youtube_channel_id` is the preferred canonical identifier; handles and URLs are aliases for discovery and matching when the channel ID is not yet resolved. +Available podcast types: `apple_podcast_id`, `spotify_collection_id`, `rss_url`, `podcast_guid`, `amazon_music_id`, `iheart_id`, `podcast_index_id`. Available video/CTV types: `youtube_channel_id`, `youtube_channel_handle`, `youtube_channel_url`, `youtube_playlist_id`, `amazon_title_id`, `platform_channel_id`, `roku_channel_id`, `pluto_channel_id`, `tubi_id`, `peacock_id`, `tiktok_id`, `twitch_channel`. Available social types: `instagram_account_id`, `instagram_handle`, `facebook_page_id`, `facebook_page_handle`, `snapchat_profile_id`, `snapchat_handle`, `x_user_id`, `x_handle`. Other: `domain`, `substack_id`. For YouTube channels, `youtube_channel_id` is the preferred canonical identifier; handles and URLs are aliases for discovery and matching when the channel ID is not yet resolved. The social types follow the same rule: the account, Page, profile or user ID is canonical, and the handle is a discovery alias. Registries compare handles case-insensitively, as `@` plus the lowercased name. ## Creator and show cards (experimental) diff --git a/server/src/services/collection-identifier-normalization.ts b/server/src/services/collection-identifier-normalization.ts index fb7684c2faf..33969a16e6a 100644 --- a/server/src/services/collection-identifier-normalization.ts +++ b/server/src/services/collection-identifier-normalization.ts @@ -29,6 +29,14 @@ export const DISTRIBUTION_IDENTIFIER_TYPE_VALUES = [ 'peacock_id', 'tiktok_id', 'twitch_channel', + 'instagram_account_id', + 'instagram_handle', + 'facebook_page_id', + 'facebook_page_handle', + 'snapchat_profile_id', + 'snapchat_handle', + 'x_user_id', + 'x_handle', 'imdb_id', 'gracenote_id', 'eidr_id', @@ -52,7 +60,17 @@ export function isValidCollectionPublisherDomain(value: string): boolean { return DOMAIN_PATTERN.test(value); } -function normalizeYouTubeHandle(raw: string): string { +// Platform handles are case-insensitive, so they compare as `@` plus the +// lowercased name, whether or not the caller sent the `@`. +const HANDLE_IDENTIFIER_TYPES = new Set([ + 'youtube_channel_handle', + 'instagram_handle', + 'facebook_page_handle', + 'snapchat_handle', + 'x_handle', +]); + +function normalizeHandle(raw: string): string { const trimmed = raw.trim(); const withoutAt = trimmed.startsWith('@') ? trimmed.slice(1) : trimmed; return `@${withoutAt.toLowerCase()}`; @@ -100,8 +118,8 @@ export function normalizeCollectionDistributionIdentifier( const norm = normalizeIdentifier(type, value); return { type: norm.type, value: norm.value }; } - if (type === 'youtube_channel_handle') { - return { type, value: normalizeYouTubeHandle(value) }; + if (HANDLE_IDENTIFIER_TYPES.has(type)) { + return { type, value: normalizeHandle(value) }; } if (type === 'youtube_channel_url') { return { type, value: normalizeYouTubeChannelUrl(value) }; diff --git a/server/tests/unit/services/collection-identifier-normalization.test.ts b/server/tests/unit/services/collection-identifier-normalization.test.ts new file mode 100644 index 00000000000..81ebef15291 --- /dev/null +++ b/server/tests/unit/services/collection-identifier-normalization.test.ts @@ -0,0 +1,36 @@ +import { describe, it, expect } from 'vitest'; +import { + isValidDistributionIdentifierType, + normalizeCollectionDistributionIdentifier, +} from '../../../src/services/collection-identifier-normalization.js'; + +describe('social distribution identifier types', () => { + it.each([ + 'instagram_account_id', + 'instagram_handle', + 'facebook_page_id', + 'facebook_page_handle', + 'snapchat_profile_id', + 'snapchat_handle', + 'x_user_id', + 'x_handle', + ])('accepts %s', (type) => { + expect(isValidDistributionIdentifierType(type)).toBe(true); + }); + + it.each(['instagram_handle', 'facebook_page_handle', 'snapchat_handle', 'x_handle', 'youtube_channel_handle'])( + 'normalizes %s to @ plus the lowercased name', + (type) => { + expect(normalizeCollectionDistributionIdentifier(type, ' JuniperVale ')).toEqual({ type, value: '@junipervale' }); + expect(normalizeCollectionDistributionIdentifier(type, '@JuniperVale')).toEqual({ type, value: '@junipervale' }); + }, + ); + + it('keeps stable IDs as sent, trimmed', () => { + expect(normalizeCollectionDistributionIdentifier('instagram_account_id', ' 17841400000000000 ')).toEqual({ + type: 'instagram_account_id', + value: '17841400000000000', + }); + expect(normalizeCollectionDistributionIdentifier('x_user_id', '783214')).toEqual({ type: 'x_user_id', value: '783214' }); + }); +}); diff --git a/static/schemas/source/enums/distribution-identifier-type.json b/static/schemas/source/enums/distribution-identifier-type.json index ae495fe93b5..9c6880911dc 100644 --- a/static/schemas/source/enums/distribution-identifier-type.json +++ b/static/schemas/source/enums/distribution-identifier-type.json @@ -2,7 +2,7 @@ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "/schemas/enums/distribution-identifier-type.json", "title": "Distribution Identifier Type", - "description": "Platform-specific identifier types for collection distribution. Maps a collection to its presence on specific platforms, enabling cross-seller matching.", + "description": "Platform-specific identifier types for collection distribution. Maps a collection to its presence on specific platforms, enabling cross-seller matching. The `instagram_account_id`, `instagram_handle`, `facebook_page_id`, `facebook_page_handle`, `snapchat_profile_id`, `snapchat_handle`, `x_user_id` and `x_handle` values were added in AdCP 3.3.", "type": "string", "enum": [ "apple_podcast_id", @@ -24,6 +24,14 @@ "peacock_id", "tiktok_id", "twitch_channel", + "instagram_account_id", + "instagram_handle", + "facebook_page_id", + "facebook_page_handle", + "snapchat_profile_id", + "snapchat_handle", + "x_user_id", + "x_handle", "imdb_id", "gracenote_id", "eidr_id", @@ -50,6 +58,14 @@ "peacock_id": "Peacock content ID", "tiktok_id": "TikTok account ID", "twitch_channel": "Twitch channel name", + "instagram_account_id": "Instagram account ID: the stable numeric user ID the platform's APIs return. Preferred canonical identifier for Instagram accounts; handles are discovery aliases that should resolve to this when possible.", + "instagram_handle": "Instagram username such as @example. Useful as a discovery alias; the account ID is preferred for canonical matching.", + "facebook_page_id": "Facebook Page ID. Preferred canonical identifier for Facebook Pages; handles are discovery aliases that should resolve to this when possible.", + "facebook_page_handle": "Facebook Page username (vanity name) such as @example. Useful as a discovery alias; the Page ID is preferred for canonical matching.", + "snapchat_profile_id": "Snapchat Public Profile ID. Preferred canonical identifier for Snapchat Public Profiles; handles are discovery aliases that should resolve to this when possible.", + "snapchat_handle": "Snapchat username such as @example. Useful as a discovery alias; the profile ID is preferred for canonical matching.", + "x_user_id": "X (formerly Twitter) numeric user ID. Preferred canonical identifier for X accounts; handles are discovery aliases that should resolve to this when possible.", + "x_handle": "X (formerly Twitter) username such as @example. Useful as a discovery alias; the user ID is preferred for canonical matching.", "imdb_id": "IMDb title ID — platform-independent cross-reference", "gracenote_id": "Gracenote TMS ID — industry standard for TV metadata", "eidr_id": "EIDR (Entertainment Identifier Registry) — ISO 10528 for audiovisual content", diff --git a/tests/check-platform-agnostic.cjs b/tests/check-platform-agnostic.cjs index 2d4f357c1ea..04fcb42b4d8 100644 --- a/tests/check-platform-agnostic.cjs +++ b/tests/check-platform-agnostic.cjs @@ -114,6 +114,12 @@ const ENUM_VALUE_ALLOWLIST = [ { value: 'amazon_music_id', pathContains: 'enums/distribution-identifier-type.json' }, { value: 'amazon_title_id', pathContains: 'enums/distribution-identifier-type.json' }, { value: 'roku_channel_id', pathContains: 'enums/distribution-identifier-type.json' }, + // Social platform account and Page identifiers are each platform's own ID + // namespace for a creator's channel, as roku_channel_id is for Roku (#8992). + { value: 'instagram_account_id', pathContains: 'enums/distribution-identifier-type.json' }, + { value: 'instagram_handle', pathContains: 'enums/distribution-identifier-type.json' }, + { value: 'facebook_page_id', pathContains: 'enums/distribution-identifier-type.json' }, + { value: 'facebook_page_handle', pathContains: 'enums/distribution-identifier-type.json' }, // enums/feed-format.json — widely-adopted open interchange formats. { value: 'google_merchant_center', pathContains: 'enums/feed-format.json' }, diff --git a/tests/x-added-in-3-3-sweep.test.cjs b/tests/x-added-in-3-3-sweep.test.cjs index 34da4a3b11c..52d179a9ecb 100644 --- a/tests/x-added-in-3-3-sweep.test.cjs +++ b/tests/x-added-in-3-3-sweep.test.cjs @@ -188,6 +188,7 @@ test('by_spot lifecycle fields carry x-added-in 3.3.0', () => { test('added enum values are noted in the enum description', () => { assert.match(load('enums/demographic-system.json').description, /`nmo` and `videoamp`.*3\.3/); + assert.match(load('enums/distribution-identifier-type.json').description, /`instagram_account_id`.*`x_handle` values were added in AdCP 3\.3/); const video = load('formats/canonical/video_hosted.json').properties; assert.match(video.video_codecs.description, /`mpeg2`, `avc_intra`, and `xavc`.*3\.3/); assert.match(video.containers.description, /`mxf`.*3\.3/);