自动填充凭据

Android、iOS 和 Web 都有内置的密码管理器，可以自动检测用户名和密码字段，并安全地存储和调用这些凭据。

为了使 Apple 和 Google 能够自动填充和保存凭据，必须在您的网站和应用之间配置双向关联。在本指南中，我们将按照深度链接中使用的相同步骤进行操作，但我们将添加Capacitor 配置步骤以及使用 autocomplete 属性。

编写应用代码

您的应用需要一个用于用户名和密码的 ion-input，必须使用 autocomplete 属性。下面是一个示例：

Angular

<form>
  <ion-list>
    <ion-item>
      <ion-label>电子邮件地址</ion-label>
      <ion-input appAutofill type="email" name="email" autocomplete="email" [(ngModel)]="email" required email></ion-input>
    </ion-item>
    <ion-item>
      <ion-label>密码</ion-label>
      <ion-input appAutofill type="password" name="password" autocomplete="current-password" required [(ngModel)]="password"></ion-input>
    </ion-item>
  </ion-list>
  <ion-button type="submit">提交</ion-button>
</form>

由于一个与 ion-input 自动填充字段相关的 webkit bug，您需要通过将此指令复制到您的代码中来解决这个问题。

这个示例应用使用了本指南中的技术，允许在 iOS、Android 和 Web 上自动填充凭据。

Javascript

<form>
  <ion-list>
    <ion-item>
      <ion-label>电子邮件地址</ion-label>
      <ion-input type="email" name="email" autocomplete="email" required email></ion-input>
    </ion-item>
    <ion-item>
      <ion-label>密码</ion-label>
      <ion-input id="pwd" type="password" name="password" autocomplete="current-password" required></ion-input>
    </ion-item>
  </ion-list>
  <ion-button type="submit">提交</ion-button>
</form>

由于一个与 ion-input 自动填充字段相关的 webkit bug，您需要以下解决代码：

    document.getElementById('pwd').children[0].addEventListener('change', (e) => {
      this.password = (e.target as any).value;
    });

备注

autocomplete 属性允许自动填充凭据类型，如 username、current-pasword、new-password。它也可以在不使用此附加配置的情况下用于电话号码、一次性代码、信用卡信息等。

设置 Capacitor 服务器主机名

默认情况下，Capacitor 将使用 localhost 域（iOS 上为 capacitor://localhost，Android 上为 http://localhost）提供服务。由于您希望密码管理器为您的应用建议存储的凭据，您需要将配置从 localhost 更改为 my-app.com（与您的应用关联的域）。

您可以在 capacitor.config.ts 或 capacitor.config.json 文件中执行此操作：

const config: CapacitorConfig = {
...
  server: {
    hostname: 'my-app.com',
    androidScheme: 'https',
  }
};

iOS 配置

XCode 中的配置

在 XCode 中打开您的项目并导航到 Signing & Capabilities。

• 点击 + 并添加 Associated Domains 功能。
• 在 Domains 部分点击 + 并提供条目 applinks:my-app.com，其中 my-app.com 是您拥有的域名称，并将为其创建 App Association File。
• 确保启用了 Automatically manage signing（否则，您需要在 Apple Developer Portal 中配置 App ID、Capabilities 和 Profiles）。

Apple App Site Association 文件

创建名为 apple-app-site-association 的站点关联文件，类似下面的文件，将 TEAMID.BUNDLEID 替换为您自己的 Apple Team ID 和 App Bundle ID（例如：8L65AZE66A.com.company.myapp）。

{
  "applinks": {
    "details": [
      {
        "appID": "TEAMID.BUNDLEID",
        "paths": ["*"]
      }
    ]
  }
}

注意：尽管这是一个 JSON 文件，但不要保存它时使用文件扩展名。

将文件上传到您网站的 .well-known 文件夹（必须通过 HTTPS 托管）。 URL 应遵循以下格式：https://my-app.com/.well-known/apple-app-site-association

验证

验证您的应用站点关联文件是否正确可以在您的 iOS 设备上完成。

转到 Settings > Developer > Universal Links -> Diagnostics。输入 url（例如 https://my-app.com），验证结果将显示如下：

绿色勾号表示验证配置，而黄色警告表示存在问题。

其他验证工具

Apple 提供了一个工具，应该可以验证关联。注意：它似乎在良好的配置上也会失败。

Branch 提供了一个工具，可以验证链接、内容类型和 JSON 结构。但是，它会在无效的 JSON 模式上显示误报。

保存凭据

要使用本机 iOS 密码管理器控制用户名和密码凭据的保存，您需要使用 capacitor-ios-autofill-save-password 插件：

npm install capacitor-ios-autofill-save-password

如果您的代码针对 iOS，则需要在成功登录后保存凭据（其他平台不需要此操作）：

if (Capacitor.getPlatform() === 'ios') {
    await SavePassword.promptDialog({
        username: '[输入的用户名]',
        password: '[输入的密码]'
    });
}

当调用上述代码时，如果保存新凭据或当您的密码与设备上保存的密码不同时，您将看到以下对话框。如果您保存的凭据没有更改，您将不会看到此对话框。

自动填充的实际效果

配置正确后，您的应用将显示以下附件栏，显示域名和用户名。点击它将自动填充表单中的凭据。

如果您只看到钥匙图标和"密码"文本，那么您可能需要保存第一组凭据，或者您的应用可能配置错误。

Android 配置

按照 Android 深度链接指南 创建站点关联文件和相关的 AndroidManifest.xml 更改，并另外验证：

• 您的域使用 HTTPS 和有效的可信证书提供服务
• 您的 capacitor.config.ts 将 hostname 属性设置为您的域（匹配 AndroidManifest.xml 中的 android:host）并且正在使用 androidScheme 的 https：

"server": {
    "androidScheme": "https",
    "hostname": "my-app.com"
}

Web 配置

如果您针对 Web，请遵循深度链接指南。

如果您在设备上安装了应用，当您在 iOS Safari 中访问网站时，您将在顶部看到一个横幅，提供打开应用的选项。如果您想避免这种行为，请考虑为您的应用使用单独的子域。

iOS 故障排除

有很多方法可能会错误配置应用，导致无法在 iOS 上保存或调用凭据。

密码的自动填充选项不出现。我应该检查什么？

• Capacitor 服务器主机名必须与您网站的域名匹配
• XCode 中的 Bundle Identifier 必须与 apple-app-site-association 文件中的 Bundle Identifier 匹配
• apple-app-site-association 文件中前缀 AppID 的 Team Identifier 必须与您的 Apple Developer Account 中的 Team Identifier 匹配
• XCode 中的 Associated Domains 具有 applinks: 前缀
• XCode 中的 Associated Domains 必须与您网站的域名匹配
• apple-app-site-association 文件通过 https 和可信证书提供服务，而不是 http 或自签名证书
• url https://my-app.com/.well-known/apple-app-site-association 可以在浏览器中显示
• 对 apple-app-site-association 的请求的响应以 application/json 的 content-type 返回
• apple-app-site-association 文件没有使用文件扩展名
• apple-app-site-association 文件已上传到名为 .well-known 的文件夹
• 没有为 apple-app-site-association 使用重定向
• 您至少保存了一组凭据（如果您从未提供用户名或密码，则无法自动填充）

注意

Apple 通过其 CDN 检查 apple-app-site-association 文件，该文件将缓存长达一周。这意味着，如果在初始检查时配置错误，即使您更正了问题，它也可能无法工作。这也意味着，如果您将良好的配置更改为错误配置的文件，您的应用似乎仍然可以正常工作，因为设备已将您的域与应用的关联缓存。

我需要 AutoFill Credential Provider 功能吗？

不需要，此功能不是必需的。

我需要在 Associated Domains 中使用 webcredentials:domain 吗？

不需要，您只需要在 Associated Domains 中使用 applinks:domain。

我需要在 apple-app-site-association 中使用 webcredentials 吗？

不需要，您只需要 applinks 和 appID 属性。

Apple 验证工具报告 Error cannot parse app site association

Apple 的工具将报告错误，即使您的应用可以自动填充和保存凭据。使用 Branch 提供的替代工具 来验证您的 Apple App Site Association 文件。

Apple 文档与这些说明不同

Apple 关于关联域的文档显示了一个 JSON 示例，其中包含一个名为 appIDs（和 components）的属性，它是一个数组，而这些说明包括属性 appID（和 paths）。在本文（2022 年 8 月）和使用 iOS 15.6 进行测试时，此文档是正确的，Apple 的 JSON 示例文档似乎是不正确的。这可能是 iOS 或文档中的错误。Apple 在这里提供了一些工作示例。