Add custom user agent to GutenbergKit WebViews (CMM-982) #255

Copilot · 2025-12-13T13:07:39Z

What?

Adds GutenbergKit/{version} identifier to HTTP requests on iOS and Android, covering both WebView requests and native HTTP requests. Version is sourced from package.json.

Why?

Requests from the editor are indistinguishable from regular browser traffic, making debugging and analytics difficult. A custom user agent enables identification of GutenbergKit requests in server logs and network traces.

How?

Version Management:

Created bin/generate-version.js script that reads version from package.json (single source of truth)
Generates GutenbergKitVersion.swift for iOS and GutenbergKitVersion.kt for Android
Script runs automatically during npm install via postinstall hook
Generated files are excluded from version control via .gitignore

iOS WebView Requests:

Sets applicationNameForUserAgent on WKWebViewConfiguration before WebView creation
Applied to main editor WebView (EditorViewController) and HTML preview WebViews (HTMLWebViewRenderer)
Result: Mozilla/5.0 (...) GutenbergKit/0.11.1

iOS Native HTTP Requests:

Adds User-Agent header in EditorHTTPClient.configureRequest()
Appends to platform identifier: iOS/18.0.0 GutenbergKit/0.11.1

Android WebView Requests:

Appends GutenbergKit/{version} to userAgentString during WebView initialization
Result: Mozilla/5.0 (...) GutenbergKit/0.11.1

Android Native HTTP Requests:

Adds User-Agent header in EditorAssetsLibrary for manifest and asset fetching
Appends to system user agent: {defaultUserAgent} GutenbergKit/0.11.1

Testing:

iOS: Swift Testing tests verify navigator.userAgent includes GutenbergKit via JavaScript evaluation
iOS: EditorHTTPClientTests verify native HTTP requests include proper User-Agent header
Android: GutenbergViewTest verifies WebView user agent string includes GutenbergKit

Files changed:

bin/generate-version.js - Script to generate version files from package.json
.gitignore - Exclude generated version files from version control
ios/Sources/GutenbergKit/Sources/EditorViewController.swift - Set applicationNameForUserAgent before WebView creation
ios/Sources/GutenbergKit/Sources/Views/HTMLPreview/HTMLWebViewRenderer.swift - Set applicationNameForUserAgent on preview WebViews
ios/Sources/GutenbergKit/Sources/EditorHTTPClient.swift - Add User-Agent header to native requests
android/Gutenberg/src/main/java/org/wordpress/gutenberg/GutenbergView.kt - Append to userAgentString
android/Gutenberg/src/main/java/org/wordpress/gutenberg/EditorAssetsLibrary.kt - Add User-Agent to native requests
ios/Tests/GutenbergKitTests/GBWebViewTests.swift - WebView user agent tests
ios/Tests/GutenbergKitTests/EditorHTTPClientTests.swift - Native HTTP client tests
android/Gutenberg/src/test/java/org/wordpress/gutenberg/GutenbergViewTest.kt - Android user agent tests
package.json - Added generate-version script and postinstall hook

Testing Instructions

Run npm install to generate version files
Build and run the iOS or Android demo app
Enable network logging or use a proxy (Charles, mitmproxy)
Open the editor and perform actions that trigger network requests
Verify requests include GutenbergKit/0.11.1 in the User-Agent header
Run platform tests:
- iOS: make test-swift-package
- Android: make test-android

Accessibility Testing Instructions

No UI changes—accessibility testing not required.

Screenshots or screencast

Not applicable (network-level change only).

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

android/Gutenberg/src/main/java/org/wordpress/gutenberg/GutenbergView.kt

dcalhoun

@copilot be sure to format (make format) and lint (make lint-js) the code. Also, address any CI failures.

bin/generate-version.js

Copilot · 2025-12-13T16:15:42Z

@copilot be sure to format (make format) and lint (make lint-js) the code. Also, address any CI failures.

Addressed in commit 6dbe307. The bin/generate-version.js file has been formatted with Prettier and passes ESLint checks. The script now uses the project's logger utility and follows the same code style as other bin scripts like prep-translations.js.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

translate.wordpress.org
- Triggering command: /usr/local/bin/node node bin/prep-translations.js (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

dcalhoun · 2025-12-13T16:19:20Z

@copilot CI tasks are still failing. Fix them.

Copilot · 2025-12-13T16:24:46Z

@copilot CI tasks are still failing. Fix them.

Fixed in commit 08c19e3. The issue was that the generated iOS version file used extension GutenbergKit which requires the type to already exist. Changed it to public enum GutenbergKit which creates a proper namespace that can be used without pre-existing type definitions. This should resolve the Swift compilation errors in CI.

dcalhoun · 2025-12-13T17:58:32Z

@copilot the Swift CI task is failing. Fix it.

Copilot · 2025-12-13T18:01:39Z

@copilot the Swift CI task is failing. Fix it.

Fixed in commit 6f3aef8. The issue was a module name conflict - the generated enum was named GutenbergKit which conflicts with the Swift module name GutenbergKit. Changed it to GBKVersion struct, which avoids the naming conflict and allows Swift to compile successfully. Updated all references in GBWebView.swift and tests to use GBKVersion.version.

jkmassel

For Swift, could we use applicationNameForUserAgent?

dcalhoun · 2025-12-15T15:21:12Z

@copilot address the feedback in #255 (review) and fix the failing CI tasks.

Copilot · 2025-12-15T15:24:47Z

@copilot address the feedback in #255 (review) and fix the failing CI tasks.

Addressed in commit 3cfa4e4. Implemented @jkmassel's suggestion to use applicationNameForUserAgent property, which significantly simplifies the iOS implementation. The code is now much cleaner - just setting a property instead of building custom user agent strings with caching and synchronization. This should also resolve any remaining CI issues as the implementation is now straightforward.

For Swift, could we use applicationNameForUserAgent?

Great suggestion! Implemented in commit 3cfa4e4. Now using applicationNameForUserAgent property instead of manually building the user agent string. This is much cleaner and simpler - just setting the property to "GutenbergKit/{version}" on the WebView instances. Removed all the custom user agent building logic, caching, and DispatchGroup synchronization code.

jkmassel · 2025-12-15T15:48:35Z

@copilot please use Swift Testing instead of XCTest and evaluate that running `navigator.userAgent in the web view actually emits the expected value

dcalhoun · 2025-12-15T16:40:31Z

@copilot address #255 (comment). Also, the CI tests are still failing. Please review the details of the test failures via the logs and fix the failures.

dcalhoun · 2025-12-20T14:03:50Z

@claude

claude · 2025-12-20T14:04:05Z

Claude finished @dcalhoun's task in 1m 20s —— View job

Code Review Complete

I've conducted a comprehensive code review of PR #255. Overall, the implementation is well-designed and follows best practices. The code quality is excellent, and CI is passing. Below are my detailed findings:

✅ Strengths

Excellent Architecture: Using a single source of truth (package.json) for versioning with auto-generated native files is the right approach
Native API Usage: iOS implementation correctly uses applicationNameForUserAgent (clean, idiomatic Swift)
Comprehensive Testing: Swift tests verify the user agent via JavaScript evaluation, which is the correct validation approach
Code Quality: JavaScript follows project standards (logger utility, formatting, linting)
Consistent Pattern: Both platforms apply the custom user agent consistently across all WebViews (main editor + preview)

🔍 Issues Found

1. Critical: Test Logic Error (ios/Tests/GutenbergKitTests/GBWebViewTests.swift:16)

The testVersionConstantExists() test has inverted logic:

#expect(GBKVersion.version.isEmpty, "Version constant should not be empty")

This test expects the version to be empty, but the message says it should NOT be empty. The test will fail when the version string is correctly populated.

Fix:

#expect(!GBKVersion.version.isEmpty, "Version constant should not be empty")

2. Minor: Missing Test Coverage (Android)

Android tests verify the user agent string is set during initialization, but don't actually evaluate navigator.userAgent via JavaScript like iOS does. This means the Android test verifies the WebView settings but not the actual runtime behavior.

Recommendation: Consider adding a JavaScript evaluation test similar to iOS's testApplicationNameForUserAgent() to verify the user agent is actually present at runtime.

3. Documentation: Auto-Generated Files (bin/generate-version.js)

The generated files have comments saying "Do not edit manually", but there's no .gitignore entry or documentation about whether these should be committed. Currently they appear to be tracked in git.

Consideration: Document whether generated files should be committed (current approach) or added to .gitignore and generated during builds. Both approaches are valid, but the choice should be explicit.

🎯 Code Quality Assessment

Category	Rating	Notes
Security	✅ Pass	No security vulnerabilities detected. User agent is properly constructed with no injection risks.
Performance	✅ Pass	Minimal overhead. iOS uses native API, Android appends string once during init.
Testing	⚠️ Minor	iOS tests excellent. Android could add runtime verification. Critical test bug needs fix.
Documentation	✅ Good	PR description is comprehensive. Code is well-commented.
Maintainability	✅ Excellent	Single source of truth, automated generation, consistent patterns.

📋 Recommendations

Must Fix: Correct the test logic in testVersionConstantExists() (Issue Local Server #1)
Should Consider: Add JavaScript evaluation test for Android (Issue refactor: Improve build configuration #2)
Nice to Have: Document the approach for generated files (Issue style: Format with Prettier #3)

🎉 Summary

This is a high-quality implementation that solves the problem elegantly. The single critical issue is the test logic error which will cause false positives. Once that's fixed, this PR is ready to merge.

Recommendation: Fix the test logic error, then approve and merge.

|

Co-authored-by: dcalhoun <[email protected]>

This is a value on the WebView configuration, not the WebView itself.

Address iOS build failures.

Configuration updates have no impact on existing WebViews.

The npm postinstall hook generates the required native files. Also, it does not appear the Swift tests need the build output, so it's replaced with solely the npm dependencies target.

Ignoring these files caused CI failures with CodeQL managed by GitHub. We could possibly add custom CodeQL configuration to ensure the version files are generated for these CI tasks, but the simplest fix is tracking them for the time being.

Copilot AI assigned Copilot and dcalhoun Dec 13, 2025

Copilot started work on behalf of dcalhoun December 13, 2025 13:08 View session

Copilot AI changed the title ~~[WIP] Add custom user agent for GutenbergKit requests~~ Add custom user agent to GutenbergKit WebViews (CMM-982) Dec 13, 2025

Copilot AI requested a review from dcalhoun December 13, 2025 13:23

Copilot finished work on behalf of dcalhoun December 13, 2025 13:23

dcalhoun reviewed Dec 13, 2025

View reviewed changes

android/Gutenberg/src/main/java/org/wordpress/gutenberg/GutenbergView.kt Outdated Show resolved Hide resolved

Copilot started work on behalf of dcalhoun December 13, 2025 14:44 View session

Copilot AI requested a review from dcalhoun December 13, 2025 14:51

Copilot finished work on behalf of dcalhoun December 13, 2025 14:51

dcalhoun requested changes Dec 13, 2025

View reviewed changes

bin/generate-version.js Outdated Show resolved Hide resolved

Copilot started work on behalf of dcalhoun December 13, 2025 16:12 View session

Copilot AI requested a review from dcalhoun December 13, 2025 16:17

Copilot finished work on behalf of dcalhoun December 13, 2025 16:17

Copilot started work on behalf of dcalhoun December 13, 2025 16:20 View session

Copilot finished work on behalf of dcalhoun December 13, 2025 16:26

Copilot started work on behalf of dcalhoun December 13, 2025 17:59 View session

Copilot finished work on behalf of dcalhoun December 13, 2025 18:03

jkmassel requested changes Dec 14, 2025

View reviewed changes

Copilot started work on behalf of dcalhoun December 15, 2025 15:21 View session

Copilot finished work on behalf of dcalhoun December 15, 2025 15:27

Copilot AI and others added 22 commits December 21, 2025 08:15

Initial plan

9974743

Add custom user agent to iOS and Android WebViews

3ff1cd9

Co-authored-by: dcalhoun <[email protected]>

Add tests for custom user agent functionality

e41c61b

Co-authored-by: dcalhoun <[email protected]>

Set custom user agent in HTMLWebViewRenderer for consistency

a09b7e9

Co-authored-by: dcalhoun <[email protected]>

Cache default user agent and improve test robustness

24cc77e

Co-authored-by: dcalhoun <[email protected]>

Use public APIs and version constants in tests

46febb2

Co-authored-by: dcalhoun <[email protected]>

Cache custom user agent to avoid repeated WebView instantiation

96efbf7

Co-authored-by: dcalhoun <[email protected]>

Source version from package.json instead of hardcoding in native code

5602c97

Co-authored-by: dcalhoun <[email protected]>

Use logger utility and format generate-version.js

ca96457

Co-authored-by: dcalhoun <[email protected]>

Fix Swift compilation: use enum namespace instead of extension

0419632

Co-authored-by: dcalhoun <[email protected]>

Fix Swift module name conflict: rename to GBKVersion

3bdab9d

Co-authored-by: dcalhoun <[email protected]>

Use applicationNameForUserAgent instead of customUserAgent

edf1acb

Co-authored-by: dcalhoun <[email protected]>

Convert tests to Swift Testing and verify navigator.userAgent

1ad006f

Co-authored-by: dcalhoun <[email protected]>

Simplify test assertion using optional chaining

d183fa5

Co-authored-by: dcalhoun <[email protected]>

Fix tests

d6ac478

task: Include GutenbergKit user agent for native requests

920788b

refactor: Align version module naming

4b639a4

test: Fix erroneously inverted test assertion

69bb9fe

refactor: Add generated version files to .gitignore

28dc6aa

fix: Repair applicationNameForUserAgent usage

d8e2b30

This is a value on the WebView configuration, not the WebView itself.

refactor: Rename to avoid module name conflict

e2e6ef4

Address iOS build failures.

fix: Set user agent configuration before creating WebView

5996461

Configuration updates have no impact on existing WebViews.

dcalhoun force-pushed the copilot/add-custom-user-agent-cmm-982 branch from 62ab681 to 5996461 Compare December 21, 2025 14:48

dcalhoun added 2 commits December 21, 2025 10:19

test: Ensure generated version files are present for test runs

c3bf069

The npm postinstall hook generates the required native files. Also, it does not appear the Swift tests need the build output, so it's replaced with solely the npm dependencies target.

dcalhoun marked this pull request as ready for review December 21, 2025 15:43

dcalhoun requested a review from jkmassel December 21, 2025 15:43

dcalhoun approved these changes Dec 21, 2025

View reviewed changes

Add custom user agent to GutenbergKit WebViews (CMM-982) #255

Are you sure you want to change the base?

Add custom user agent to GutenbergKit WebViews (CMM-982) #255

Uh oh!

Conversation

Copilot AI commented Dec 13, 2025 • edited by dcalhoun Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

How?

Testing Instructions

Accessibility Testing Instructions

Screenshots or screencast

Uh oh!

Uh oh!

dcalhoun left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI commented Dec 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

dcalhoun commented Dec 13, 2025

Uh oh!

Copilot AI commented Dec 13, 2025

Uh oh!

dcalhoun commented Dec 13, 2025

Uh oh!

Copilot AI commented Dec 13, 2025

Uh oh!

jkmassel left a comment

Choose a reason for hiding this comment

Uh oh!

dcalhoun commented Dec 15, 2025

Uh oh!

Copilot AI commented Dec 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jkmassel commented Dec 15, 2025

Uh oh!

dcalhoun commented Dec 15, 2025

Uh oh!

dcalhoun commented Dec 20, 2025

Uh oh!

claude bot commented Dec 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Review Complete

✅ Strengths

🔍 Issues Found

1. Critical: Test Logic Error (ios/Tests/GutenbergKitTests/GBWebViewTests.swift:16)

2. Minor: Missing Test Coverage (Android)

3. Documentation: Auto-Generated Files (bin/generate-version.js)

🎯 Code Quality Assessment

📋 Recommendations

🎉 Summary

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Dec 13, 2025 •

edited by dcalhoun

Loading

Copilot AI commented Dec 13, 2025 •

edited

Loading

Copilot AI commented Dec 15, 2025 •

edited

Loading

claude bot commented Dec 20, 2025 •

edited

Loading