iOS问题记录 - iOS 17通过NSUserDefaults设置UserAgent无效（续）

男娘i 2024-05-24 21:41 99阅读 0赞

#### 文章目录 ####

*  前言
 *  开发环境
 *  问题描述
 *  问题分析
 *   *  1. 准备源码
     *  2. 定位源码
     *  3. 对比源码
     *  4. 分析总结
 *  解决方案
 *  补充内容
 *   *  1. UserAgent的组成
     *  2. UserAgent的设置优先级
 *  最后

--------------------

## 前言 ##

在[上篇文章][Link 1]中对该问题做了一些判断和猜测，并给出了解决方案。不过，美中不足的是没有进一步验证猜测，所以在这里进一步分析该问题作为上篇文章的补充。

## 开发环境 ##

*  Xcode: 15.1
 *  iOS: 17.2

## 问题描述 ##

项目运行在iOS 17.2设备时，应用内网页无法成功获取设置后的`UserAgent`。

项目中设置`UserAgent`的关键源码：

[self.webView evaluateJavaScript:@"navigator.userAgent" completionHandler:^(id result, NSError *error) {
        
        NSString *userAgent = [NSString stringWithFormat:@"%@", result];
        NSString *newUserAgent = [userAgent stringByAppendingString:@" App/1.0.0"];
        [[NSUserDefaults standardUserDefaults] registerDefaults:@{
        @"UserAgent": newUserAgent}];
    }];

## 问题分析 ##

进一步分析的前提是有源码可以分析，好在`WKWebView`类属于`WebKit.framework`，这算是系统框架里面少有的开源框架。

### 1. 准备源码 ###

找到GitHub上面的开源项目[WebKit][]，通过以下命令克隆项目到本地：

git clone https://github.com/WebKit/WebKit.git WebKit

这项目有点大，最终占了约14GB的硬盘空间。因为后面可能需要搜索历史提交记录，所以我完整克隆了项目，如果你没有这个需求，可以按需浅克隆。

源码准备好了，现在可以直接用Xcode打开`WebKit`项目。那接下来该怎么定位导致该问题的关键源码呢？

### 2. 定位源码 ###

一般常用的切入点有两个，各有各的优缺点：

1.  从`WKWebView`类开始分析源码。耗时比较长且容易找错方向，但只要不断分析，定位到关键源码不是问题，而且能让你对该项目有更多的认识
2.  用`UserAgent`作为关键词搜索相关的历史提交记录。运气好时能快速定位源码，运气不好时容易迷失方向

如果从`WKWebView`类开始分析源码，目前只知道早先可以通过`NSUserDefaults`设置`UserAgent`，所以要先确定导致该问题的改动大概是在什么时候提交的，然后再将源码切换到早于这个时候的提交，这样才有可能找到通过`NSUserDefaults`设置`UserAgent`的相关源码，再和最新的源码对比就能定位到改动的源码。

根据上篇文章的测试，极可能是在iOS 16.4发布（[2023年3月27日发布][2023_3_27]）后，iOS 17发布（[2023年9月18日发布][2023_9_18]）前改动的，所以先将源码切换到早于这个时间范围的提交应该是可行的。

不过呢，我喜欢先用`UserAgent`作为关键词搜索相关的历史提交记录，运气好的话能省很多事。在项目路径下执行命令：

git log --since=2023-03-27 --until=2023-09-18 --grep=UserAgent --pretty=format:'%C(auto)%h - %s (%ad)' --date=iso

*  `--since`和`--until`：指定提交时间范围
 *  `--grep`：指定提交说明需要包含的字符串
 *  `--pretty`: 自定义输出格式。`%C(auto)`会自动为输出添加颜色，`%h`是简写哈希值，`%s`是提交说明，`%ad`是作者提交日期
 *  `--date`: 指定日期显示格式

除了用命令搜索，还可以用其他一些可视化软件（例如`Sourcetree`等），体验会更好点。运气不错，很快就定位到了：

![screenshot1][]

这里补充一点，由于`--date`参数我没找到更好的显示选项，所以图中显示的时间是`UTC-0700`时区的，换算成北京时间（`UTC+0800`）需要加上15小时。

根据提交说明里面的[链接][Link 2]，找到这个：

> We should remove the code in UserAgentIOS.mm that reads an override UA from the NSUserDefault \[com.apple.WebFoundation UserAgent\].  
> It is incompatible with the modern need to compose the UA from various bits of information these days (e.g. desktop vs. mobile). Clients should use the API to set the application name or UA instead.  
> I have stumbled upon one client (com.fark.hey), and there are likely others, so it should be a linked-on-or-after change.

简单概括就是：从`NSUserDefault`读取`UA`并覆盖的做法和现今的需求不符，需要删除这部分代码。

现在基本可以确定就是这个提交改动导致了当前的问题。用Xcode打开项目对比`UserAgentIOS.mm`文件提交，继续往后分析看看改了啥：

![screenshot2][]

源码改动位置位于`standardUserAgentWithApplicationName`函数。

### 3. 对比源码 ###

**注意，以下关于源码的解释说明源于个人理解，仅供参考。**

`6a68b0c65d6c`提交之前：

if (auto override = dynamic_cf_cast<CFStringRef>(adoptCF(CFPreferencesCopyAppValue(CFSTR("UserAgent"), CFSTR("com.apple.WebFoundation")))))
        return override.get();

这段源码的作用就是从偏好配置中获取`UserAgent`的值，并尝试将其动态转换为`CFStringRef`类型，如果转换成功（值不为空）便直接返回。

`6a68b0c65d6c`提交改动：

if (!linkedOnOrAfterSDKWithBehavior(SDKAlignedBehavior::DoesNotOverrideUAFromNSUserDefault)) {
        
        if (auto override = dynamic_cf_cast<CFStringRef>(adoptCF(CFPreferencesCopyAppValue(CFSTR("UserAgent"), CFSTR("com.apple.WebFoundation"))))) {
        
            static BOOL hasLoggedDeprecationWarning = NO;
            if (!hasLoggedDeprecationWarning) {
        
                NSLog(@"Reading an override UA from the NSUserDefault [com.apple.WebFoundation UserAgent]. This is incompatible with the modern need to compose the UA and clients should use the API to set the application name or UA instead.");
                hasLoggedDeprecationWarning = YES;
            }
            return override.get();
        }
    }

相比改动前的源码，主要增加了`linkedOnOrAfterSDKWithBehavior`函数调用和过时警告日志输出。

先说说过时警告日志输出，这个逻辑很简单，因为`hasLoggedDeprecationWarning`是静态变量，所以只会在首次运行时输出一次。

再说说`linkedOnOrAfterSDKWithBehavior`函数，这个函数的作用是检查某个特定行为在当前应用程序链接的SDK版本上是否支持。函数入参`DoesNotOverrideUAFromNSUserDefault`这个特定行为，顾名思义，这行为就是不要从`NSUserDefault`覆盖`UA`。

那应用程序链接的SDK版本是什么呢？

开发iOS App时都会基于某个版本的iOS SDK开发，通常是基于Xcode内置的iOS SDK（位于`/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs`），这个版本就是链接的SDK版本。也就是说，如果你是用Xcode 15.1构建的应用程序，那么链接的SDK版本就是17.2；如果你是用Xcode 14.3.1构建的应用程序，那么链接的SDK版本就是16.4。更多关于Xcode内置的SDK版本信息，请看[官方文档][Link 3]。

继续查看`linkedOnOrAfterSDKWithBehavior`的定义（位于`WebKit项目/Source/WTF/wtf/cocoa/RuntimeApplicationChecksCocoa.cpp`）：

bool linkedOnOrAfterSDKWithBehavior(SDKAlignedBehavior behavior)
    {
        
        return sdkAlignedBehaviors().get(static_cast<size_t>(behavior));
    }

这里还看不出什么，继续往后面找，可以在`computeSDKAlignedBehaviors`函数中找到根据链接SDK版本禁用特定行为的源码（以下省略部分源码）：

static SDKAlignedBehaviors computeSDKAlignedBehaviors()
    {
        
        SDKAlignedBehaviors behaviors;
        behaviors.setAll();
    
        auto disableBehavior = [&] (SDKAlignedBehavior behavior) {
        
            behaviors.clear(static_cast<size_t>(behavior));
        };
    
        ...
        
        if (linkedBefore(dyld_fall_2023_os_versions, DYLD_IOS_VERSION_17_0, DYLD_MACOSX_VERSION_14_0)) {
        
            disableBehavior(SDKAlignedBehavior::FullySuspendsBackgroundContent);
            disableBehavior(SDKAlignedBehavior::RunningBoardThrottling);
            disableBehavior(SDKAlignedBehavior::PopoverAttributeEnabled);
            disableBehavior(SDKAlignedBehavior::LiveRangeSelectionEnabledForAllApps);
            disableBehavior(SDKAlignedBehavior::DoesNotOverrideUAFromNSUserDefault);
        }
    
        ...
    
        return behaviors;
    }

`linkedBefore`函数的作用就是判断当前应用程序链接的SDK是否小于入参中的指定版本，如果小于则返回`true`。

**所以，现在可以明确知道当链接的SDK版本大等于iOS 17时，`DoesNotOverrideUAFromNSUserDefault`这个特定行为不会被禁用（是支持的），在这时判断条件`!linkedOnOrAfterSDKWithBehavior(SDKAlignedBehavior::DoesNotOverrideUAFromNSUserDefault)`将不成立，也就不会从`NSUserDefault`覆盖`UA`！**

分析到这，再总结一下基本结束了，但是总感觉少了些什么？在上篇文章中我的猜测是：

> 可能是`WKWebView`初始化时不再从`NSUserDefaults`获取默认值导致的问题

咦？前面都没分析`WKWebView`，没有完整串起来，是不是初始化时获取的都还不确定。所以，别急着总结，先翻翻`WKWebView`类源码（位于`WebKit项目/Source/WebKit/UIProcess/API/Cocoa/WKWebView.mm`）。

在`WKWebView`类的初始化方法中发现了关于`UserAgent`的设置：

- (void)_initializeWithConfiguration:(WKWebViewConfiguration *)configuration
    {
        
        ...
    
        _contentView = adoptNS([[WKContentView alloc] initWithFrame:self.bounds processPool:processPool configuration:pageConfiguration.copyRef() webView:self]);
        _page = [_contentView page];
        
        ...
    
        if (NSString *applicationNameForUserAgent = configuration.applicationNameForUserAgent)
            _page->setApplicationNameForUserAgent(applicationNameForUserAgent);
        
        ...
    }

不过，这是从`WKWebViewConfiguration`配置中获取`applicationNameForUserAgent`并设置。等等！这属性名称有点熟悉，这一看就是和前面源码改动位置所在的`standardUserAgentWithApplicationName`函数有关。找到`WKContentView`类中的`page`方法：

- (WebKit::WebPageProxy*)page
    {
        
        return _page.get();
    }

继续找到`WebPageProxy`中的`setApplicationNameForUserAgent`函数：

void WebPageProxy::setApplicationNameForUserAgent(const String& applicationName)
    {
        
        if (m_applicationNameForUserAgent == applicationName)
            return;
    
        m_applicationNameForUserAgent = applicationName;
        if (!m_customUserAgent.isEmpty())
            return;
    
        setUserAgent(standardUserAgent(m_applicationNameForUserAgent));
    }

`setUserAgent`函数的作用是完成设置，而`standardUserAgent`函数的具体实现是区分平台的。继续找到`WebPageProxyIOS.mm`文件（位于`WebKit项目/Source/WebKit/UIProcess/ios`），`standardUserAgent`函数的具体实现如下：

String WebPageProxy::standardUserAgent(const String& applicationNameForUserAgent)
    {
        
        return standardUserAgentWithApplicationName(applicationNameForUserAgent);
    }

这里调用的`standardUserAgentWithApplicationName`函数在iOS平台上的具体实现就是前面`UserAgentIOS.mm`文件中的同名函数，现在一切就都串起来了，猜测是对的！

### 4. 分析总结 ###

`WebKit.framework`是一个系统动态框架，已经内置在系统中，应用运行时加载。

*  对于iOS 17以下的系统，`WebKit.framework`中还没有增加`DoesNotOverrideUAFromNSUserDefault`特定行为判断，不管是Xcode 15及以上还是15以下版本构建的应用，都还可以通过`NSUserDefaults`设置`UserAgent`。
 *  对于iOS 17及以上的系统，如果是Xcode 15及以上版本构建的应用，由于链接的SDK版本已经支持`DoesNotOverrideUAFromNSUserDefault`特定行为，所以通过`NSUserDefaults`设置`UserAgent`会失效；如果是Xcode 15以下版本构建的应用，由于链接的SDK版本低于iOS 17，`DoesNotOverrideUAFromNSUserDefault`特定行为会被禁用，所以还可以通过`NSUserDefaults`设置`UserAgent`，同时会输出过时警告日志。

<table> 
 <thead> 
  <tr> 
   <th></th> 
   <th>Xcode 15以下版本构建</th> 
   <th>Xcode 15及以上版本构建</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><strong>iOS 17以下版本</strong></td> 
   <td>✅</td> 
   <td>✅</td> 
  </tr> 
  <tr> 
   <td><strong>iOS 17及以上版本</strong></td> 
   <td>✅ + ⚠️</td> 
   <td>❌</td> 
  </tr> 
 </tbody> 
</table>

✅：通过`NSUserDefaults`设置`UserAgent`有效  
❌：通过`NSUserDefaults`设置`UserAgent`无效  
⚠️：有过时警告日志输出

## 解决方案 ##

请看[上篇文章][Link 1]中的解决方案。

如果你只需要设置一次，还可以参考后面补充内容里面的方法。

## 补充内容 ##

### 1. UserAgent的组成 ###

iOS 17.2模拟器获取的`UserAgent`：

![screenshot3][]

Mozilla/5.0 (iPhone; CPU iPhone OS 17_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148

以上`UserAgent`的组成大家应该基本看得懂，所以不再一一赘述。让我感到困惑的是`Mobile/15E148`中的`15E148`，一开始以为是当前的系统版本，尝试更换其他版本的系统获取，结果这个一直没变。

可以通过`Mozilla/5.0`或其他关键词在`WebKit`项目中全局搜索，找到以上`UserAgent`生成相关的源码（位于`UserAgentIOS.mm`文件的`standardUserAgentWithApplicationName`函数）：

String standardUserAgentWithApplicationName(const String& applicationName, const String& userAgentOSVersion, UserAgentType type)
    {
        
        auto separator = applicationName.isEmpty() ? "" : " ";
    
        if (type == UserAgentType::Desktop)
            return makeString("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko)", separator, applicationName);
    
    #if USE(STATIC_IPAD_USER_AGENT_VALUE)
        UNUSED_PARAM(userAgentOSVersion);
        UNUSED_PARAM(separator);
        return makeString("Mozilla/5.0 (iPad; CPU OS 16_3_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.3 Mobile/15E148 Safari/604.1");
    #else
        if (!linkedOnOrAfterSDKWithBehavior(SDKAlignedBehavior::DoesNotOverrideUAFromNSUserDefault)) {
        
            if (auto override = dynamic_cf_cast<CFStringRef>(adoptCF(CFPreferencesCopyAppValue(CFSTR("UserAgent"), CFSTR("com.apple.WebFoundation"))))) {
        
                static BOOL hasLoggedDeprecationWarning = NO;
                if (!hasLoggedDeprecationWarning) {
        
                    NSLog(@"Reading an override UA from the NSUserDefault [com.apple.WebFoundation UserAgent]. This is incompatible with the modern need to compose the UA and clients should use the API to set the application name or UA instead.");
                    hasLoggedDeprecationWarning = YES;
                }
                return override.get();
            }
        }
    
        auto osVersion = userAgentOSVersion.isEmpty() ? systemMarketingVersionForUserAgentString() : userAgentOSVersion;
        return makeString("Mozilla/5.0 (", deviceNameForUserAgent(), "; CPU ", osNameForUserAgent(), " ", osVersion, " like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko)", separator, applicationName);
    #endif
    }

在前面的问题分析中已经分析了该函数关于当前问题的源码，再剔除其他平台相关的源码，可见最后的`return`语句是`UserAgent`生成的关键。和前面获取的`UserAgent`一一对应：

*  `deviceNameForUserAgent()`对应`iPhone`，该函数在当前文件有定义
 *  `osNameForUserAgent()`对应`iPhone OS`，该函数在当前文件有定义
 *  `osVersion`对应`17_2`
 *  `applicationName`对应`Mobile/15E148`。当`applicationName`为空时，分隔符`separator`为空字符串

由于`applicationName`是函数入参，所以现在需要知道函数是在哪调用的。根据前面问题分析可知，`standardUserAgentWithApplicationName`函数是在`WKWebView`类初始化时调用的，`applicationName`入参的值来自`WKWebViewConfiguration`类中的`applicationNameForUserAgent`方法（位于`WebKit项目/Source/WebKit/UIProcess/API/Cocoa/WKWebViewConfiguration.mm`）：

std::optional<RetainPtr<NSString>> _applicationNameForUserAgent;
    
    ...
    
    static NSString *defaultApplicationNameForUserAgent()
    {
        
    #if PLATFORM(IOS_FAMILY)
        return @"Mobile/15E148";
    #else
        return nil;
    #endif
    }
    
    ...
    
    - (NSString *)applicationNameForUserAgent
    {
        
        return _applicationNameForUserAgent.value_or(defaultApplicationNameForUserAgent()).get();
    }

`value_or`是`C++`中`std::optional`类型的函数，该函数的作用就是如果`_applicationNameForUserAgent`为空则返回提供的默认值。

由此可见，`Mobile/15E148`竟然是硬编码的！如果在初始化`WKWebView`对象时，没有通过`WKWebViewConfiguration`对象设置`applicationNameForUserAgent`属性，那么将使用`Mobile/15E148`作为默认值返回。

那这个`15E148`有什么含义呢？在Xcode中选中`return @"Mobile/15E148";`这一行，然后右键选择\[**Show Last Change for Line**\]，查看关于这行源码的上次改动信息：

![screenshot4][]

> We noticed that we get the following default UA from a WKWebView on iOS using a sample app in the iPhone 6 simulator:
> 
> Mozilla/5.0 (iPhone; CPU iPhone OS 12\_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/16A342
> 
> The default WKWebView UA should have a frozen OS build number, as we do in Safari.
> 
> Mobile/16A342 -> Mobile/15E148.

上面这段话来自[192809 - WKWebView default UA doesn’t freeze the build number][192809 - WKWebView default UA doesn_t freeze the build number]页面。简单概括就是`WKWebView`的`UA`应该和`Safari`一样，固定一个系统构建版本号。

再具体看看源码改动对比：

![screenshot5][]

从改动对比可知，原先是通过`[UIDevice currentDevice].buildVersion`动态获取系统构建版本号，后续才固定为`15E148`这个版本号。这里有几个疑问：

1.  找不到`buildVersion`方法？

通常应用开发者只能通过`systemVersion`获取系统版本（例如17.2），`buildVersion`是私有API，更多详情可以参考`UIKitSPI.h`文件（`SPI`即`System Programming Interface`，系统级编程接口），如果找不到，可能是当前提交已经移除了相关源码，请切换到更早的提交。

1.  `15E148`具体是哪个系统版本的构建版本号？

官方文档中没找到系统构建版本号相关的列表，不过找到了这个网站[Xcode Releases][]。由于这是以Xcode版本为主的网站，所以iOS相关的版本数据也不是很全，例如在Xcode可以看到iOS 17.0.1的构建版本号是`21A342`：

![screenshot6][]

这个版本在该网站找不到，不过好在这个构建版本号是递增的，最终可以明确`15E148`对应的系统版本介于iOS 11.2（`15C107`）和iOS 11.3（`15E217`）之间。

1.  为什么要固定系统构建版本号？

我没有找到官方说明或解释，以下个人猜测仅供参考：

iOS 11和iPhone X同一年发布，iPhone X带来刘海屏的同时，iOS 11也带来了新的网页特性用于适配安全区域，再往后感觉也没有什么新的特性需要网页适配。那么，为了方便开发者根据版本对网页进行适配，将`UA`中的系统构建版本号固定为`15E148`倒也合理。

### 2. UserAgent的设置优先级 ###

`UserAgent`设置的三种方式：

*  `NSUserDefaults`方式：在`WKWebView`对象初始化前，通过`registerDefaults`方法设置，一次设置全局生效，已过时
 *  `applicationNameForUserAgent`方式：在`WKWebView`对象初始化时，通过`WKWebViewConfiguration`对象设置，后续再修改无效
 *  `customUserAgent`方式：在`WKWebView`对象初始化后，直接赋值设置，支持动态修改

如果三种方式同时设置，结合之前的分析，可知优先级如下：

**`customUserAgent`方式 > `NSUserDefaults`方式 > `applicationNameForUserAgent`方式**

现阶段`NSUserDefaults`方式已过时，如果你只需要设置一次，那么建议通过`applicationNameForUserAgent`方式设置。不过，这里需要注意一点，请不要像下面例子般直接赋值：

let webViewConfiguration = WKWebViewConfiguration()
    webViewConfiguration.applicationNameForUserAgent = "App/1.0.0"
    webView = WKWebView(frame: view.bounds, configuration: webViewConfiguration)

这样会出现默认值`Mobile/15E148`被替换的情况（原因请看前面的分析）：

Mozilla/5.0 (iPhone; CPU iPhone OS 17_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) App/1.0.0

`UA`中缺失`Mobile/15E148`会导致一些网页无法正常适配，特别是`Mobile`这部分，很多网页会根据这个判断是不是属于移动端。所以，可以参考下面的例子先获取默认值拼接成新的再设置：

let webViewConfiguration = WKWebViewConfiguration()
    webViewConfiguration.applicationNameForUserAgent = "\(webViewConfiguration.applicationNameForUserAgent ?? "") App/1.0.0"
    webView = WKWebView(frame: view.bounds, configuration: webViewConfiguration)

设置后效果：

Mozilla/5.0 (iPhone; CPU iPhone OS 17_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148 App/1.0.0

## 最后 ##

如果这篇文章对你有所帮助，点赞?收藏?支持一下吧，谢谢～

--------------------

本篇文章由[@crasowas][crasowas]发布于CSDN。

[Link 1]: https://blog.csdn.net/crasowas/article/details/135051649
[WebKit]: https://github.com/WebKit/WebKit
[2023_3_27]: https://support.apple.com/zh-cn/HT213676
[2023_9_18]: https://support.apple.com/zh-cn/HT213938
[screenshot1]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/24/5a15838bb17346b2af348f79f2143073.png
[Link 2]: https://bugs.webkit.org/show_bug.cgi?id=217927
[screenshot2]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/24/3779d37f1cd1474d85001cb9b6aa8527.png
[Link 3]: https://developer.apple.com/support/xcode
[screenshot3]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/24/02665d52f0b34ecdbf226283657881aa.png
[screenshot4]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/24/7ed39a518206477a852241db1f58ce3e.png
[192809 - WKWebView default UA doesn_t freeze the build number]: https://bugs.webkit.org/show_bug.cgi?id=192809
[screenshot5]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/24/03e362eadddf4bb785a7c97bb667ea21.png
[Xcode Releases]: https://xcodereleases.com
[screenshot6]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/24/6033f21ef5b54d8da2a240b9d7a22ea5.png
[crasowas]: https://blog.csdn.net/crasowas