跳到主要内容
版本：v6

自动填充凭证

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

为了让苹果和谷歌实现自动填充和保存凭证功能，需要配置应用与网站之间的双向关联。本指南将沿用深度链接的配置步骤，并额外添加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、功能和配置文件）

Apple应用站点关联文件​

创建名为apple-app-site-association的站点关联文件（无文件扩展名），将TEAMID.BUNDLEID替换为你的Apple团队ID和应用Bundle ID（例如：8L65AZE66A.com.company.myapp）：

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

将该文件上传至网站HTTPS服务的.well-known目录，访问地址格式应为：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匹配，且使用https方案：
"server": {
    "androidScheme": "https",
    "hostname": "my-app.com"
}

Web配置​

如果目标平台包括Web，请参考深度链接指南。

当在iOS Safari中访问网站时，若设备已安装应用，顶部会显示打开应用的横幅提示。如需避免此行为，可考虑为应用使用单独的子域名。

iOS Safari提示

iOS问题排查​

多种配置错误都可能导致iOS无法保存或调用凭证。

密码自动填充选项未显示，需要检查什么？​

  • Capacitor服务器主机名必须与网站域名一致
  • XCode中的Bundle标识符必须与apple-app-site-association文件中的Bundle标识符匹配
  • apple-app-site-association文件中AppID前缀的团队标识符必须与Apple开发者账户一致
  • XCode中关联域的前缀为applinks:
  • XCode中的关联域必须与网站域名一致
  • 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使用重定向
  • 至少需要保存过一组凭证（从未提供过用户名密码则无法自动填充）
注意

Apple通过CDN检查apple-app-site-association文件，缓存时间可能长达一周。这意味着如果初始检查时配置错误，即使后续修正问题也可能暂时无效。同样，有效配置修改为错误配置后，因设备缓存了域名与应用关联，可能暂时仍显示功能正常。

是否需要AutoFill Credential Provider功能？​

不需要添加此功能。

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

不需要，只需配置applinks:domain。

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

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

Apple验证工具报告"无法解析应用站点关联"错误​

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

Apple文档与本指南存在差异​

Apple关于关联域的文档展示的JSON示例包含名为appIDs的数组属性（及components），而本指南使用的是appID属性（及paths）。截至本文撰写时（2022年8月）和iOS 15.6测试，本指南的配置是正确的，Apple文档中的JSON示例可能有误。这可能是iOS的漏洞或文档错误。Apple开发者文档中有一些有效示例。

Contents

编辑此页