Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions .changeset/social-distribution-identifiers.md
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
Expand Up @@ -1229,7 +1229,7 @@ Collections SHOULD include at least one platform-independent identifier when ava

</CodeGroup>

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)

Expand Down
24 changes: 21 additions & 3 deletions server/src/services/collection-identifier-normalization.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand All @@ -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<string>([
'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()}`;
Expand Down Expand Up @@ -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) };
Expand Down
Original file line number Diff line number Diff line change
@@ -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' });
});
});
18 changes: 17 additions & 1 deletion static/schemas/source/enums/distribution-identifier-type.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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",
Expand All @@ -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",
Expand Down
6 changes: 6 additions & 0 deletions tests/check-platform-agnostic.cjs
Original file line number Diff line number Diff line change
Expand Up @@ -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' },
Expand Down
1 change: 1 addition & 0 deletions tests/x-added-in-3-3-sweep.test.cjs
Original file line number Diff line number Diff line change
Expand Up @@ -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/);
Expand Down
Loading