跳到主要内容
版本：v4

自动填充凭证

Android、iOS 和 Web 浏览器都内置了密码管理器，能够自动检测用户名和密码输入框，并安全地存储和调用这些凭证。

为了让 Apple 和 Google 能够自动填充和保存凭证，必须在你的网站和应用之间配置双向关联。在本指南中，我们将遵循与 深度链接 相同的步骤，但会增加 Capacitor 配置 和使用 autocomplete 属性的步骤。

编写应用代码​

你的应用需要为用户名和密码设置 ion-input，并且必须使用 autocomplete 属性。示例如下：

<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 漏洞，你需要一个变通方案，将 这个指令 复制到你的代码中。

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

备注

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。

XCode 能力设置

  • 点击 +，添加 Associated Domains 能力。
  • 在 Domains 部分点击 +，并填写 applinks:my-app.com，其中 my-app.com 是你拥有并将为其创建应用关联文件的域名。
  • 确保 Automatically manage signing 已启用（否则你需要在 Apple 开发者门户 中配置 App Id、Capabilities 和 Profiles）。

Apple 应用站点关联文件​

创建一个名为 apple-app-site-association 的站点关联文件，内容如下，将 TEAMID.BUNDLEID 替换为你自己的 Apple 团队 ID 和应用包 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 设备上验证你的应用站点关联文件是否正确。

前往 设置 > 开发者 > 通用链接 -> 诊断工具。输入 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 Safari

iOS 故障排除​

应用配置不当会导致无法在 iOS 上保存或调用凭据，以下是常见排查点。

密码自动填充选项未显示。我应该检查什么？​

  • Capacitor 服务器主机名必须与您的网站域名匹配
  • XCode 中的 Bundle Identifier 必须与 apple-app-site-association 文件中的 Bundle Identifier 匹配
  • 在 apple-app-site-association 文件中，作为 AppID 前缀的 Team Identifier 必须与您 Apple 开发者账户中的 Team Identifier 匹配
  • XCode 中的关联域名必须以 applinks: 为前缀
  • XCode 中的关联域名必须与您的网站域名匹配
  • apple-app-site-association 文件必须通过具有受信任证书的 https 提供，而非 http 或自签名证书
  • 在浏览器中可以访问 https://my-app.com/.well-known/apple-app-site-association 这个 URL
  • 请求 apple-app-site-association 文件时，返回的响应其 content-type 应为 application/json
  • 不要为 apple-app-site-association 文件添加任何文件扩展名
  • apple-app-site-association 文件已上传到名为 .well-known 的文件夹中
  • 没有为 apple-app-site-association 设置重定向
  • 您已至少保存了一组凭据（如果从未提供过用户名或密码，则无法进行自动填充）
注意

apple-app-site-association 文件由 Apple 通过其 CDN 进行验证，验证结果最长会被缓存一周。这意味着，如果该文件在初次验证时配置有误，即使您后来修正了问题，它也可能不会立即生效。同样，如果您将一个原本正确的配置文件改成了错误的配置，您的应用在一段时间内可能仍能正常工作，因为设备已将您的域名与应用关联关系缓存了起来。

我是否需要 AutoFill Credential Provider 功能？​

不需要，此功能并非必需。

在关联域名中是否需要 webcredentials:domain？​

不需要，您只需要在关联域名中包含 applinks:domain 即可。

在 apple-app-site-association 文件中是否需要 webcredentials？​

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

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

即使您的应用能够正常自动填充和保存凭据，Apple 的工具有时也会报告此错误。建议使用 Branch 提供的 替代工具 来验证您的 Apple 应用网站关联文件。

Apple 的文档与本文说明不一致​

Apple 关于 关联域名 的文档中展示的 JSON 示例包含一个名为 appIDs（以及 components）的属性，它是一个数组。而本文说明中包含的属性是 appID（以及 paths）。截至本文撰写时（2022年8月）及基于 iOS 15.6 的测试，本文档的描述是正确的，而 Apple 文档中的 JSON 示例似乎有误。这可能是 iOS 的一个漏洞，或者文档本身存在错误。Apple 在其 其他文档 中确实有一些可用的示例。

Contents

编辑此页