跳到主要内容
版本：v5

自动填充凭证

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 bug，您需要通过复制此指令到代码中来解决。

这个示例应用使用了本指南中的技术，实现了在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-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设备上验证应用站点关联文件是否正确配置。

进入设置 > 开发者 > 通用链接 -> 诊断工具。输入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匹配），并使用https作为androidScheme：
"server": {
    "androidScheme": "https",
    "hostname": "my-app.com"
}

Web配置​

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

如果在设备上安装了您的应用，当在iOS Safari中访问您的网站时，顶部会显示横幅提供打开应用的选项。如果想避免此行为，可以考虑为应用使用单独的子域名。

iOS Safari

iOS故障排除​

有许多错误配置会导致应用无法在iOS上保存或调用凭证。

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

  • Capacitor服务器主机名必须与网站域名匹配
  • XCode中的包标识符必须与apple-app-site-association文件中的包标识符匹配
  • apple-app-site-association文件中AppID前缀的团队标识符必须与苹果开发者账户中的团队标识符匹配
  • 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文件没有使用文件扩展名
  • apple-app-site-association文件已上传到名为.well-known的目录
  • 没有为apple-app-site-association设置重定向
  • 至少保存过一组凭证（如果从未提供过用户名或密码则无法自动填充）
注意

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

是否需要AutoFill Credential Provider功能？​

不需要，此功能非必需。

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

不需要，只需在关联域中包含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

编辑此页