跳到主要内容
版本：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-password、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 Developer Portal 中配置 App Id、Capabilities 和 Profiles）。

Apple App Site Association 文件​

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

前往 设置 > 开发者 > 通用链接 -> 诊断。输入 URL（例如 https://my-app.com），将显示类似以下的验证结果：

诊断

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

其他验证工具​

Apple 提供了一个工具来验证关联。注意：它在正确的配置上似乎也会失败。

Branch 提供了一个工具，用于验证链接、content-type 和 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 匹配）并使用 https 的 androidScheme：
"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 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 请求的响应以 content-type 为 application/json 返回
  • 你的 apple-app-site-association 文件没有使用文件扩展名
  • apple-app-site-association 文件上传到了名为 .well-known 的文件夹
  • apple-app-site-association 没有使用重定向
  • 你已保存了至少一组凭据（如果没有提供过用户名或密码，它无法自动填充）
注意

apple-app-site-association 文件由 Apple 通过其 CDN 检查，该 CDN 会缓存长达一周。这意味着如果初次检查时配置有误，即使你纠正了问题，它也可能无法工作。这也意味着，如果你将正确的配置更改为有误的文件，你的应用可能仍然看起来正常，因为设备已缓存了你域名与应用之间的关联。

我需要 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 关于关联域名的文档显示了一个包含名为 appIDs（和 components）属性的 JSON 示例，该属性是一个数组，而本指南包含的则是 appID（和 paths）属性。截至本文撰写时（2022 年 8 月）并在 iOS 15.6 上测试，本文档是正确的，而 Apple 的 JSON 示例文档似乎有误。这可能是 iOS 或文档中的错误。Apple 在此处确实有一些可用的示例文档。

Contents

编辑此页