From 6b49a8b4cc17d314c4dec10beadc4c9db25d8071 Mon Sep 17 00:00:00 2001
From: Gary Jones <gary.jones@automattic.com>
Date: Sun, 21 Dec 2025 12:42:28 +0000
Subject: [PATCH] docs: add contextual help for DFP and AdSense provider fields
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Users unfamiliar with Google Ad Manager (formerly DFP) or AdSense often
struggle to understand what values are required for fields like Tag ID,
DFP ID, Tag Name, and Publisher ID. This is a common support request.

The new "Provider Fields" help tab explains each field with examples and
guidance on where to find the values in the respective ad platforms.
This complements the existing help tabs for Overview, Configuration,
and Conditionals.

Fixes #123

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 src/UI/class-contextual-help.php | 50 +++++++++++++++++++++++++++++++-
 1 file changed, 49 insertions(+), 1 deletion(-)

diff --git a/src/UI/class-contextual-help.php b/src/UI/class-contextual-help.php
index f8f1c30..d6cac64 100644
--- a/src/UI/class-contextual-help.php
+++ b/src/UI/class-contextual-help.php
@@ -110,6 +110,47 @@ public function render( WP_Screen $screen ): void {
 		<?php
 		$conditionals = ob_get_clean();
 
+		ob_start();
+		?>
+		<p><?php esc_html_e( 'When using the DFP Async (DoubleClick for Publishers / Google Ad Manager) provider, you need to configure the following fields:', 'ad-code-manager' ); ?></p>
+		<dl>
+			<dt><?php esc_html_e( 'Tag', 'ad-code-manager' ); ?></dt>
+			<dd><?php esc_html_e( 'The ad size/placement type (e.g., 728x90, 300x250). This determines which ad tag definition is used for this ad code.', 'ad-code-manager' ); ?></dd>
+
+			<dt><?php esc_html_e( 'Tag ID', 'ad-code-manager' ); ?></dt>
+			<dd><?php esc_html_e( 'A unique identifier for this specific ad unit placement. This is used as the HTML div ID where the ad will be rendered. Each Tag ID must be unique across all ad codes to prevent conflicts. Example: "homepage-leaderboard" or "sidebar-mpu-1".', 'ad-code-manager' ); ?></dd>
+
+			<dt><?php esc_html_e( 'DFP ID', 'ad-code-manager' ); ?></dt>
+			<dd>
+				<?php esc_html_e( 'Your Google Ad Manager (formerly DFP) Network Code. This is a numeric identifier for your Ad Manager account.', 'ad-code-manager' ); ?>
+				<br>
+				<?php echo wp_kses_post( __( 'Find it in Google Ad Manager: <i>Admin &gt; Global Settings &gt; Network Code</i>.', 'ad-code-manager' ) ); ?>
+				<br>
+				<?php esc_html_e( 'Example: 12345678', 'ad-code-manager' ); ?>
+			</dd>
+
+			<dt><?php esc_html_e( 'Tag Name', 'ad-code-manager' ); ?></dt>
+			<dd>
+				<?php esc_html_e( 'The ad unit name/path as configured in Google Ad Manager. This is the hierarchical path to your ad unit.', 'ad-code-manager' ); ?>
+				<br>
+				<?php esc_html_e( 'Example: "MySite/Homepage/Leaderboard" or just "Leaderboard" for top-level units.', 'ad-code-manager' ); ?>
+			</dd>
+		</dl>
+		<h4><?php esc_html_e( 'Google AdSense Provider', 'ad-code-manager' ); ?></h4>
+		<p><?php esc_html_e( 'When using the Google AdSense provider:', 'ad-code-manager' ); ?></p>
+		<dl>
+			<dt><?php esc_html_e( 'Publisher ID', 'ad-code-manager' ); ?></dt>
+			<dd>
+				<?php esc_html_e( 'Your AdSense Publisher ID. This starts with "ca-pub-" followed by a 16-digit number.', 'ad-code-manager' ); ?>
+				<br>
+				<?php esc_html_e( 'Example: ca-pub-1234567890123456', 'ad-code-manager' ); ?>
+				<br>
+				<?php echo wp_kses_post( __( 'Find it in your AdSense account: <i>Account &gt; Account Information &gt; Publisher ID</i>.', 'ad-code-manager' ) ); ?>
+			</dd>
+		</dl>
+		<?php
+		$provider_fields = ob_get_clean();
+
 		get_current_screen()->add_help_tab(
 			array(
 				'id'      => 'acm-overview',
@@ -127,9 +168,16 @@ public function render( WP_Screen $screen ): void {
 		get_current_screen()->add_help_tab(
 			array(
 				'id'      => 'acm-conditionals',
-				'title'   => 'Conditionals',
+				'title'   => __( 'Conditionals', 'ad-code-manager' ),
 				'content' => $conditionals,
 			)
 		);
+		get_current_screen()->add_help_tab(
+			array(
+				'id'      => 'acm-provider-fields',
+				'title'   => __( 'Provider Fields', 'ad-code-manager' ),
+				'content' => $provider_fields,
+			)
+		);
 	}
 }