feat(agentforce): use site key for filtering by brunobasto · Pull Request #51 · Automattic/vip-agentforce

brunobasto · 2026-03-25T19:02:26Z

Description

This PR updates the plugin-side Agentforce filtering contract to use a stable opaque site_key instead of sending raw site/blog identifiers in prechat.

The plugin now sends site_key as the hidden prechat field and includes the same token in ingestion records so downstream search can filter directly on that value.

It also adjusts the CMP runtime so hidden prechat fields are resolved when the widget is actually ready. In assets/src/js/cmp-manager.js, the prechatFields lookup now happens inside the onEmbeddedMessagingReady handler instead of before the handler is registered. That avoids bailing out too early when consent/bootstrap data is populated slightly later in the page lifecycle.

Pre-review checklist

Please make sure the items below have been covered before requesting a review:

This change works and has been tested locally or in Codespaces (or has an appropriate fallback).
This change has relevant unit tests (if applicable).
This change has relevant documentation additions / updates (if applicable).
I've created a changelog description that aligns with the provided examples.

Pre-deploy checklist

VIP staff: Ensure any alerts added/updated conform to internal standards (see internal documentation).

Steps to Test

Check out this PR in repos/vip-agentforce.
Build local assets:

npm run build:dev

Start the local environment:

vip dev-env start

Configure local env.php / VIP_AGENTFORCE_CONFIGS so the plugin has a valid Agentforce embed config and a site_key value.
In wp-admin, set Consent Type to Custom.
Open the local site:

https://vip-agentforce.vipdev.lndo.site/?vip_agentforce_debug=true

In the browser console, load the widget:

window.AgentforceCMP.loadSDK();

Verify the widget still initializes correctly.
Verify the hidden prechat field now uses site_key instead of site_id_blog_id.
Verify the same site_key is present in the plugin-side ingestion record shape.
Run the relevant automated checks:

composer lint

Copilot

Pull request overview

This PR updates the Agentforce plugin’s filtering contract to use a stable opaque site_key token (instead of raw site/blog IDs) in hidden prechat fields, and propagates that same token into ingestion records for downstream filtering. It also adjusts the CMP runtime timing so hidden prechat fields are resolved when Embedded Messaging is actually ready.

Changes:

Replace prechat hidden field payload with site_key sourced from plugin config, and add a get_site_key() helper.
Extend ingestion post record schema + default transformer to include site_key.
Move CMP prechat field lookup into the onEmbeddedMessagingReady handler to avoid early bailout due to late-populated bootstrap/consent data.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
vip-agentforce.php	Minor whitespace-only adjustment.
utils/class-configs.php	Adds `get_site_key()` and updates hidden prechat fields to use `site_key`.
modules/ingestion/class-ingestion-post-record.php	Adds `site_key` to ingestion record schema and serialization.
modules/ingestion/class-default-transformer.php	Populates `site_key` on generated ingestion records.
assets/src/js/cmp-manager.js	Resolves `prechatFields` at Embedded Messaging ready time.
tests/phpunit/test-ingestion.php	Updates expected ingestion record payload shape to include `site_key`.
tests/phpunit/test-ingestion-post-record.php	Updates record fixtures/expectations for `site_key`.
tests/phpunit/test-default-transformer.php	Updates record fixture to include `site_key`.
tests/phpunit/test-cmp.php	Updates localization/prechat field tests to assert `site_key` behavior.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-25T20:01:00Z

utils/class-configs.php

@@ -57,6 +57,7 @@ public static function get_embedding_script(): string {
 	 * Get the config
 	 * @return array{
 	 *     salesforce_instance_url?: string,


The get_config() return-shape phpdoc was updated, but it still doesn’t document the new site_key config value that is now read by get_site_key(). This makes the public config contract incomplete/misleading for maintainers—please add site_key?: string to the documented array shape (or otherwise document it consistently).

Suggested change

* salesforce_instance_url?: string,

* salesforce_instance_url?: string,

* site_key?: string,

Copilot · 2026-03-25T20:01:00Z

utils/class-configs.php

-			'site_id_blog_id' => $site_id . '_' . $blog_id,
-		);
+		if ( '' !== $site_key ) {
+			$fields['site_key'] = $site_key;


get_prechat_fields() now returns an empty array when site_key is missing/empty, which means CMP localization will omit prechatFields entirely and the widget will never set any hidden prechat fields. If site_key is required for filtering, consider surfacing a warning (e.g., via Logger) and/or providing an explicit fallback/exception so misconfiguration doesn’t fail silently.

Suggested change

$fields['site_key'] = $site_key;

$fields['site_key'] = $site_key;

} else {

// Warn when site_key is missing so misconfiguration doesn't fail silently.

error_log( 'VIP Agentforce: get_prechat_fields() called with an empty site_key; prechat fields will be empty and the widget may not set hidden prechat fields as expected.' );

Copilot · 2026-03-25T20:01:00Z

modules/ingestion/class-ingestion-post-record.php

 	 * @return array{
 	 *     site_id: string,
 	 *     blog_id: string,
+	 *     site_key?: string,


The to_array() return-shape docblock marks site_key as optional (site_key?: string), but the method always includes a site_key key (defaulting to an empty string). Update the phpdoc to site_key: string to match the actual serialized schema.

Suggested change

* site_key?: string,

* site_key: string,

Copilot · 2026-03-25T20:01:01Z

assets/src/js/cmp-manager.js

 const setupPrechatFields = () => {
-	const prechatFields = getPrechatFields();
-	if (!prechatFields || Object.keys(prechatFields).length === 0) {
-		return;
-	}
-
 	window.addEventListener('onEmbeddedMessagingReady', () => {
+		const prechatFields = getPrechatFields();
+		if (!prechatFields || Object.keys(prechatFields).length === 0) {
+			return;
+		}


setupPrechatFields() now always registers an onEmbeddedMessagingReady listener, even when prechatFields are absent. If the SDK is unloaded and reloaded, this can accumulate multiple listeners and cause repeated setHiddenPrechatFields calls. Consider registering the listener with { once: true }, or tracking/removing the handler on unload to prevent duplicates.

Copilot · 2026-03-25T20:01:01Z

modules/ingestion/class-default-transformer.php

@@ -48,6 +49,7 @@ public static function transform( ?Ingestion_Post_Record $record, \WP_Post $post
 			[
 				'site_id'                 => $site_id,
 				'blog_id'                 => $blog_id,
+				'site_key'                => $site_key,
 				'post_id'                 => $post_id,


Default_Transformer now populates site_key from Configs::get_site_key(), but the existing transformer tests don’t assert that this value is propagated into the record. Please add/extend a unit test to prime configs with a non-empty site_key and verify the resulting record includes it.

brunobasto added 6 commits March 25, 2026 16:01

feat(agentforce): use site key for filtering

7e77dec

fix(agentforce): default missing site key in ingestion records

dff588d

test(agentforce): allow optional site key in ingestion fixtures

a2e863c

test(agentforce): include site key in cmp fixtures

dd40e0c

style(agentforce): align cmp test fixtures

6da1230

refactor(agentforce): remove unused config helpers

e91c93c

brunobasto marked this pull request as ready for review March 25, 2026 19:57

brunobasto requested review from a team and Copilot March 25, 2026 19:57

brunobasto added the Needs Review label Mar 25, 2026

Copilot started reviewing on behalf of brunobasto March 25, 2026 19:57 View session

Copilot AI reviewed Mar 25, 2026

View reviewed changes

feat(agentforce): compose blog-aware site key

1c223e1

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(agentforce): use site key for filtering#51

feat(agentforce): use site key for filtering#51
brunobasto wants to merge 7 commits intotrunkfrom
feat/site-key-filtering

brunobasto commented Mar 25, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 25, 2026

Uh oh!

Copilot AI Mar 25, 2026

Uh oh!

Copilot AI Mar 25, 2026

Uh oh!

Copilot AI Mar 25, 2026

Uh oh!

Copilot AI Mar 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	* salesforce_instance_url?: string,
	* salesforce_instance_url?: string,
	* site_key?: string,

-			$fields['site_key'] = $site_key;
+			$fields['site_key'] = $site_key;
+		} else {
+			// Warn when site_key is missing so misconfiguration doesn't fail silently.
+			error_log( 'VIP Agentforce: get_prechat_fields() called with an empty site_key; prechat fields will be empty and the widget may not set hidden prechat fields as expected.' );

Conversation

brunobasto commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Pre-review checklist

Pre-deploy checklist

Steps to Test

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

brunobasto commented Mar 25, 2026 •

edited

Loading