跳到主要内容
版本：v4

自动填充凭证功能

Android、iOS 和网页平台都内置了密码管理器，可自动识别用户名和密码输入字段，并安全地存储和调用这些凭证。

要使苹果和谷歌能自动填充和保存凭证，必须在您的网站和应用之间建立双向关联。本指南将遵循与深度链接相同的步骤，但会额外说明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和网页平台的凭证自动填充功能。

备注

autocomplete属性支持自动填充多种凭证类型，如username、current-pasword、new-password。该属性还可用于电话号码、一次性验证码、信用卡信息等场景，无需额外配置，详见MDN文档。

设置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、功能描述和配置文件）

苹果应用站点关联文件​

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

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

诊断结果

绿色对勾表示配置验证通过，黄色警示则说明存在问题。

其他验证工具​

苹果提供了一款验证工具，但有时会对有效配置误报失败。

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"
}

网页配置​

如果您的目标是网页平台，请遵循深度链接指南。

当设备上安装了您的应用后，在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中Associated Domains的前缀为applinks:
  • XCode中的Associated Domains必须与网站域名一致
  • apple-app-site-association文件必须通过https提供可信证书，不能使用http或自签名证书
  • 能在浏览器中访问https://my-app.com/.well-known/apple-app-site-association
  • 请求apple-app-site-association时返回的content-type应为application/json
  • apple-app-site-association文件不能有扩展名
  • 文件必须上传至名为.well-known的文件夹
  • 不能对apple-app-site-association使用重定向
  • 至少保存过一组凭证（如果从未提供过用户名或密码，则无法自动填充）
注意

苹果通过其CDN检查apple-app-site-association文件，缓存时间最长一周。这意味着如果初始检查时配置错误，即使修正问题后可能仍无法立即生效。同样，如果将正确配置改为错误配置，设备可能仍能正常工作，因为它缓存了域名与应用关联。

是否需要AutoFill Credential Provider功能？​

不需要，此功能非必需。

Associated Domains中是否需要webcredentials:domain？​

不需要，只需在Associated Domains中包含applinks:domain。

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

不需要，只需包含applinks和appID属性。

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

即使您的应用能正常自动填充和保存凭证，苹果工具也可能报错。可使用Branch提供的替代工具验证苹果应用站点关联文件。

苹果文档与本指南不同​

苹果关于关联域名的文档显示JSON示例中包含名为appIDs（和components）的数组属性，而本指南使用appID（和paths）属性。截至本文撰写时（2022年8月）和iOS 15.6测试，本指南的写法是正确的，苹果文档中的JSON示例似乎有误。这可能是iOS的bug或文档错误。苹果在此处提供了一些可行示例示例。

Contents

编辑此页