> ## Documentation Index > Fetch the complete documentation index at: https://adcp-docs-ja.pier1.co.jp/llms.txt > Use this file to discover all available pages before exploring further. # provide_performance_feedback パフォーマンスの成果をパブリッシャーと共有し、データドリブンな最適化や配信改善を可能にします。 **応答時間**: 約 5 秒（データ取り込み） **リクエストスキーマ**: [`https://adcontextprotocol.org/schemas/v3/media-buy/provide-performance-feedback-request.json`](https://adcontextprotocol.org/schemas/v3/media-buy/provide-performance-feedback-request.json) **レスポンススキーマ**: [`https://adcontextprotocol.org/schemas/v3/media-buy/provide-performance-feedback-response.json`](https://adcontextprotocol.org/schemas/v3/media-buy/provide-performance-feedback-response.json) ## リクエストパラメーター | Parameter | Type | Required | Description | | -------------------- | -------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `media_buy_id` | string | Yes | セラー側のメディアバイ ID | | `measurement_period` | object | Yes | パフォーマンス測定期間 | | `performance_index` | number | Yes | 正規化されたスコア（0.0 = 価値なし、1.0 = 想定どおり、>1.0 = 想定超え） | | `package_id` | string | No | メディアバイ内の特定パッケージ（パッケージ単位のフィードバックの場合） | | `creative_id` | string | No | 特定クリエイティブ（クリエイティブ単位のフィードバックの場合） | | `metric_type` | string | **非推奨** | レガシーの自由形式メトリクス列挙（メトリクス・検証・アトリビューションを一つのリストに混在）。新規実装は代わりに `metric` を使用すべき（SHOULD）。スキーマレベルでは必須ではなくなり、1 マイナーの後方互換のため保持され、次のメジャーで削除される。マッピングは [metric-type 移行テーブル](https://adcontextprotocol.org/schemas/v3/enums/metric-type.json) を参照。 | | `metric` | object | No | このフィードバック行が対象とするメトリクス。`committed_metrics` と対称な `(scope, metric_id, qualifier)` の行形状を使用。非推奨の `metric_type` より優先。標準メトリクス: `{ scope: "standard", metric_id: "viewable_rate", qualifier: { viewability_standard: "mrc" } }`。ベンダーメトリクス: `{ scope: "vendor", vendor: { domain: "nielsen.com" }, metric_id: "brand_lift" }`。**総体的なフィードバックの場合は完全に省略** ——特定のメトリクスなしにキャンペーンの不振を示すトレーダーは、`performance_index` とレスポンスの説明でシグナルを伝えるため `metric` 行は不要。メトリクス固有のフィードバックでは、消費側がルーティングできるよう `metric` を設定すべき（SHOULD）。 | | `vendor` | [BrandRef](/docs/reference/glossary#b) | No | このフィードバックを生成したベンダー。`feedback_source` が `third_party_measurement` または `verification_partner` で、かつ単一の証明ベンダーが存在する場合は設定すべき（SHOULD）。ブレンドされた出力（MMM の混合、ベンダーをまたぐマルチタッチアトリビューション、クリーンルームが測定ソースでないクリーンルーム出力）では省略する。`buyer_attribution` と `platform_analytics` では任意。**ネストされた `metric.vendor` フィールドとは別物** ——このトップレベルの `vendor` はフィードバックの*ソース*（それを生成する当事者）を識別し、`metric.vendor`（ベンダースコープの `metric` エントリに存在する場合）は*メトリクスを定義するベンダー*を識別する。多くの場合は同じだが、異なることもある。 | | `feedback_source` | string | No | パフォーマンスデータのソース（デフォルト: "buyer\_attribution"） | ## レスポンス（メッセージ） レスポンスには人間が読めるメッセージが含まれ、次を行います。 * フィードバックの受領を確認 * 提供されたパフォーマンス水準の要約 * フィードバックの最適化への活用方法を説明 * 次のアクションや推奨事項を提示 メッセージの戻し方はプロトコルごとに異なります。 * **MCP**: JSON レスポンスの `message` フィールドとして返却 * **A2A**: アーティファクト内のテキストパートとして返却 ## レスポンス（ペイロード） ```json theme={null} { "success": "boolean", "message": "string" } ``` ### フィールド説明 * **success**: パフォーマンスフィードバックの受領に成功したか * **message**: フィードバック処理に関する任意のメッセージ ## プロトコル別の例 AdCP のペイロードはプロトコル間で同一です。リクエスト/レスポンスのラッパーのみが異なります。 ### MCP リクエスト ```json theme={null} { "tool": "provide_performance_feedback", "arguments": { "media_buy_id": "gam_1234567890", "measurement_period": { "start": "2024-01-15T00:00:00Z", "end": "2024-01-21T23:59:59Z" }, "performance_index": 1.35, "metric_type": "conversion_rate" } } ``` ### MCP レスポンス ```json theme={null} { "message": "Performance feedback received for campaign gam_1234567890. The 35% above-expected conversion rate will be used to optimize future delivery. Next optimization cycle runs tonight at midnight UTC.", "success": true } ``` ### A2A リクエスト #### 自然言語での呼び出し ```javascript theme={null} await a2a.send({ message: { parts: [{ kind: "text", text: "The campaign gam_1234567890 had a conversion rate 35% above expectations for the week of January 15-21. Please use this to optimize future delivery." }] } }); ``` #### スキルを明示して呼び出す ```javascript theme={null} await a2a.send({ message: { parts: [{ kind: "data", data: { skill: "provide_performance_feedback", parameters: { media_buy_id: "gam_1234567890", measurement_period: { start: "2024-01-15T00:00:00Z", end: "2024-01-21T23:59:59Z" }, performance_index: 1.35, metric_type: "conversion_rate" } } }] } }); ``` ### A2A レスポンス A2A では結果をアーティファクトとして返します。 ```json theme={null} { "artifacts": [{ "artifactId": "artifact-perf-feedback-abc789", "name": "performance_feedback_confirmation", "parts": [ { "kind": "text", "text": "Performance feedback received for campaign gam_1234567890. The 35% above-expected conversion rate will be used to optimize future delivery. Next optimization cycle runs tonight at midnight UTC." }, { "kind": "data", "data": { "success": true } } ] }] } ``` ### 主な違い * **MCP**: 引数付きのツール呼び出しを行い、フラットな JSON を返す * **A2A**: スキル呼び出しで入力を渡し、テキストとデータのパートを持つアーティファクトとして返す * **ペイロード**: A2A の `input` フィールドは MCP の `arguments` と同一構造 ## シナリオ ### 例 1: キャンペーンレベルのフィードバック #### リクエスト ```json theme={null} { "$schema": "/schemas/media-buy/provide-performance-feedback-request.json", "idempotency_key": "c7d8e9f0-a1b2-4345-c678-345678901234", "media_buy_id": "gam_1234567890", "measurement_period": { "start": "2024-01-01T00:00:00Z", "end": "2024-01-31T23:59:59Z" }, "performance_index": 0.85, "metric_type": "brand_lift", "feedback_source": "third_party_measurement" } ``` #### レスポンス - 想定未達 **Message**: "Performance feedback received for campaign gam\_1234567890. The 15% below-expected brand lift suggests targeting refinement is needed. Our optimization algorithms will reduce spend on underperforming segments starting with the next cycle." **Payload**: ```json theme={null} { "success": true, "message": "Performance feedback processed successfully. Optimization algorithms updated." } ``` ### 例 2: パッケージ単位のフィードバック #### リクエスト ```json theme={null} { "$schema": "/schemas/media-buy/provide-performance-feedback-request.json", "idempotency_key": "d8e9f0a1-b2c3-4456-d789-456789012345", "media_buy_id": "meta_9876543210", "package_id": "pkg_social_feed", "measurement_period": { "start": "2024-02-01T00:00:00Z", "end": "2024-02-07T23:59:59Z" }, "performance_index": 2.1, "metric_type": "click_through_rate", "feedback_source": "buyer_attribution" } ``` #### レスポンス - 卓越した成果 **Message**: "Outstanding performance feedback for package pkg\_social\_feed! The 110% above-expected click-through rate indicates this audience segment is highly engaged. We'll increase allocation to similar inventory and audiences." **Payload**: ```json theme={null} { "success": true, "message": "Exceptional performance noted. Increasing allocation to similar segments." } ``` ### 例 3: クリエイティブ単位のフィードバック #### リクエスト ```json theme={null} { "$schema": "/schemas/media-buy/provide-performance-feedback-request.json", "idempotency_key": "e9f0a1b2-c3d4-4567-e890-567890123456", "media_buy_id": "ttd_5555555555", "creative_id": "creative_video_123", "measurement_period": { "start": "2024-02-01T00:00:00Z", "end": "2024-02-07T23:59:59Z" }, "performance_index": 0.65, "metric_type": "completion_rate", "feedback_source": "verification_partner" } ``` #### レスポンス - 低調なクリエイティブ **Message**: "Creative creative\_video\_123 shows 35% below-expected completion rate. Consider creative refresh or A/B testing alternative versions." **Payload**: ```json theme={null} { "success": true, "message": "Creative performance feedback recorded. Consider creative optimization." } ``` ### 例 4: 複数のパフォーマンスメトリクス 同じメディアバイについて複数のメトリクスをレポートするには、メトリクスタイプごとに 1 リクエストを送ります: #### リクエスト - ビューアビリティのフィードバック ```json theme={null} { "$schema": "/schemas/media-buy/provide-performance-feedback-request.json", "idempotency_key": "f0a1b2c3-d4e5-4678-f901-678901234567", "media_buy_id": "ttd_5555555555", "measurement_period": { "start": "2024-02-01T00:00:00Z", "end": "2024-02-14T23:59:59Z" }, "metric_type": "viewability", "performance_index": 1.15, "feedback_source": "verification_partner" } ``` #### リクエスト - 完了率のフィードバック ```json theme={null} { "$schema": "/schemas/media-buy/provide-performance-feedback-request.json", "idempotency_key": "a1b2c3d4-e5f6-4789-a012-789012345678", "media_buy_id": "ttd_5555555555", "measurement_period": { "start": "2024-02-01T00:00:00Z", "end": "2024-02-14T23:59:59Z" }, "metric_type": "completion_rate", "performance_index": 0.92, "feedback_source": "verification_partner" } ``` #### リクエスト - ブランドセーフティのフィードバック ```json theme={null} { "$schema": "/schemas/media-buy/provide-performance-feedback-request.json", "idempotency_key": "b2c3d4e5-f6a7-4890-b123-890123456789", "media_buy_id": "ttd_5555555555", "measurement_period": { "start": "2024-02-01T00:00:00Z", "end": "2024-02-14T23:59:59Z" }, "metric_type": "brand_safety", "performance_index": 1.05, "feedback_source": "verification_partner" } ``` ## パフォーマンスインデックスのスケール パフォーマンスインデックスはビジネス成果を正規化して伝えるための指標です。 * **0.0**: 価値が確認できません * **0.5**: 想定を大幅に下回る（-50%） * **1.0**: 想定どおり（0% 乖離） * **1.5**: 想定比 50% 上振れ * **2.0+**: 非常に優れた成果（100% 以上の上振れ） ### よく使われる metric\_type * **overall\_performance**: 全体的な成功度（デフォルト） * **conversion\_rate**: ポストクリック/ポストビューのコンバージョン * **brand\_lift**: ブランド認知・好意度向上 * **click\_through\_rate**: クリエイティブへのエンゲージメント * **completion\_rate**: 動画・音声の完了率 * **viewability**: ビューアブルインプレッション率 * **brand\_safety**: ブランドセーフティの準拠状況 * **cost\_efficiency**: 目標成果あたりのコスト ### feedback\_source の例 * **buyer\_attribution**: バイヤー自身の計測・アトリビューション * **third\_party\_measurement**: 第三者の計測パートナー * **platform\_analytics**: パブリッシャープラットフォームの分析 * **verification\_partner**: 検証ベンダー ## パブリッシャーがフィードバックを活用する方法 パブリッシャーはパフォーマンスインデックスを以下に活用します。 1. **ターゲティング最適化**: 高パフォーマンスのセグメント・オーディエンスへ配信をシフト 2. **インベントリ改善**: 価値の高い掲載面を特定し優先度を上げる 3. **価格調整**: 実績に基づいて CPM を更新 4. **アルゴリズム強化**: 実際の成果データで機械学習モデルを学習 5. **商品開発**: パフォーマンス傾向をもとにプロダクト定義を洗練 ## 利用上の注意 * パフォーマンスフィードバックは任意だが、最適化に大きく寄与します * フィードバックはキャンペーンまたはパッケージ単位で提供可能 * 同一期間に複数のインデックスを共有できる（バッチ送信は将来対応予定） * 効果はパブリッシャーのアルゴリズム成熟度に依存 * 処理は非同期で行われる。レスポンスでステータスを確認可能 * 過去のフィードバックは将来の配信パフォーマンス向上に役立つ ## プライバシーとデータ共有 * フィードバックの共有は任意で、バイヤーが制御します * 集計されたパフォーマンス傾向はプラットフォーム全体の改善に利用される場合があります * 個別キャンペーンの詳細はバイヤーとパブリッシャーの関係に限定されます * パブリッシャーは AdCP ドキュメントで明確なデータ利用ポリシーを提示すべき ## 実装ガイド ### パフォーマンスインデックスの計算 ```python theme={null} def calculate_performance_index(actual_metric, expected_metric): """ Calculate normalized performance index Args: actual_metric: Measured performance value expected_metric: Baseline or expected performance value Returns: Performance index (0.0 = no value, 1.0 = expected, >1.0 = above expected) """ if expected_metric == 0: return 0.0 return actual_metric / expected_metric # Examples: # CTR: 0.15% actual vs 0.12% expected = 1.25 performance index (25% above) # Conversions: 45 actual vs 60 expected = 0.75 performance index (25% below) # Brand lift: 8% actual vs 5% expected = 1.6 performance index (60% above) ``` ### metric\_type の決定 キャンペーン目標に基づいて metric\_type を選択します。 ```python theme={null} METRIC_TYPE_MAPPING = { 'awareness': 'brand_lift', 'consideration': 'brand_lift', 'traffic': 'click_through_rate', 'conversions': 'conversion_rate', 'sales': 'conversion_rate', 'engagement': 'completion_rate', 'reach': 'overall_performance' } def get_metric_type(campaign_objective): return METRIC_TYPE_MAPPING.get(campaign_objective, 'overall_performance') ``` ## 関連ドキュメント * [`get_media_buy_delivery`](/docs/media-buy/task-reference/get_media_buy_delivery) - 配信メトリクスを取得 * [Optimization & Reporting](/docs/media-buy/media-buys/optimization-reporting) - パフォーマンスフィードバックの考え方 * [Targeting](/docs/media-buy/advanced-topics/targeting) - 最適化に向けたターゲティングの理解