3.0 から 3.1 への移行
3.1 はリリース済みです。 新しい 3.1 統合は、エージェントが
supported_versions でそれをアドバタイズすることを確認した後に "3.1" をピン留めすべきです。既存の 3.0 統合は移行中 "3.0" にピン留めしたままでかまいません。"3.0" に留まれます。SDK、バイヤー、セラー、クリエイティブエージェント、シグナルエージェント、ブランドエージェント、またはコンプライアンスワークフローが 3.1 を主張または消費する準備をするとき、このガイドを使ってください。
機能の物語については What’s New in AdCP 3.1 から始めてください。完全なリリース記録については リリースノート を参照。
アップグレードチェックリスト
バージョンピン留め
3.0 統合はメジャーバージョンのみで交渉しました。3.1 はリリース精度ネゴシエーションを追加します:- 安定 3.0 トラフィックには
"3.0"を使う。 - エージェントがアドバタイズした後、安定 3.1 トラフィックには
"3.1"を使う。 "3.0.19"のようなパッチ値や"3.1.0-rc.15"のような完全な semver プレリリースをワイヤー上で送らない。
VERSION_UNSUPPORTED で拒否し、error.data.supported_versions にサポートリリースリストを含めるべきです。バイヤーはマイナーリリースをまたいで黙ってダウンシフトすべきではありません。不一致をサーフェスするか、セラーが明示的にアドバタイズしたバージョンに対してリトライしてください。
監査すべきランタイム変更
すべてのタスクの冪等性
3.0 は変更リクエストにidempotency_key を要求しました。3.1 は信頼性モデルをすべてのタスクに拡張し、リトライ、リプレイ、下流の再照合が一様に動作するようにします。SDK ユーザーはこの動作を SDK リリースから拾います。手書きバイヤーは、書き込みと同様に読み取りタスクにも UUID v4 冪等性キーを生成すべきです。
レスポンスが replayed: true とマークされたとき、それを元の操作の歴史的な結果として扱ってください。行動する前に新しい状態が必要な場合、リプレイされたレスポンスを処理した後に該当リソースを再読み取りしてください。
エンベロープ許容
3.1 は、トランスポートアダプターが AdCP エンベロープルートを許容することに依存します。MCP と A2A クライアントは、まずトランスポート固有のラッパーをアンラップし、次にstatus、result、errors、adcp_version、replayed、context などの AdCP フィールドを読むべきです。未知のエンベロープメンバーは拒否を引き起こしてはなりません。
エラーデコード
標準エラーカタログは 3.1 で拡張されましたが、error.code はオープン文字列のままです。クライアントは次をすべきです:
- 未知のエラーコードを受け入れる。
- 存在するとき
error.recoveryを優先する。 error.recoveryが欠けているとき、未知のレガシーエラーに有界の transient フォールバックを適用する。AUTH_MISSINGとAUTH_INVALIDのあいだの auth 分割を扱う。CREDENTIAL_IN_ARGSを terminal として扱い、リトライ前に認証情報を適切なトランスポートチャネルに移す。
プロポーザルとアクションディスカバリーのクリーンアップ
3.1 はproposal_status をプロポーザルの真実の源泉にし、プロダクトとバイで構造化されたアクションディスカバリーを使います。セラーは GA 前の requires_proposal アクションモードを発すべきではありません。キャッシュされたプレリリースアクションメタデータを持つバイヤーは、それを無効化し、プロダクト、プロポーザル、バイのサーフェスを再読み取りすべきです。
ブランド検証署名
verify_brand_claim または verify_brand_claims を実装するブランドエージェントは、署名されたレスポンス証拠を返さなければなりません。ブランドごとのレスポンス署名鍵を公開し、署名をタスク、解決されたブランドテナント、応答エージェント URL、呼び出し元/リクエストハッシュ、有効期間にバインドしてください。
シグナルターゲティング
シグナルアイデンティティはSignalRef に向かって移動し、プロダクトスコープの included_signals、signal_targeting_options、バイ時の signal_targeting_groups を伴います。所有シグナルディスカバリーとマーケットプレイスアクティベーションは別個のケイパビリティです。バイヤーは、エージェントがマーケットプレイスまたはアクティベーションサポートを宣言するときのみ activate_signal を呼ぶべきです。
クリエイティブフォーマットとトランスフォーマー
クリエイティブエージェントは正準なformat_kind 値を公開し、list_transformers を通じてビルドユニットを発見すべきです。フォーマット添付の入力/出力/価格宣言は、トランスフォーマースコープの設定と価格を優先して非推奨です。ホストされた音声/動画スロットは、固定 duration には duration_ms_exact を、有界または片側範囲には duration_ms_range を使うべきです。
レポートと課金
3.1 は配信と使用量の確定マーカー、リーチウィンドウセマンティクス、viewability.viewed_seconds、AdCP 外のクリエイティブ課金のための BILLING_OUT_OF_BAND エラーを追加します。バイヤーは、該当する確定フィールドが確定と言うまで配信数を確定として扱うのを避けるべきです。
ロールベースの移行
プレリリースアーティファクト
3.1 プレリリースアーティファクトは、検証中にそれらをピン留めした採用者のために利用可能なままですが、新しい統合は安定した"3.1" ワイヤー値を使うべきです。プレリリースに対して構築した場合、requires_proposal のようなプレリリースのみのフィールドを無効化し、現在のプロダクト/プロポーザル/アクションメタデータを再読み取りし、安定リリースを主張する前に 3.1 ストーリーボードバンドルを再実行してください。