跳到主要内容
版本：v7

自动填充凭证功能

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 IDs、Capabilities和Profiles）

苹果应用站点关联文件​

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

进入设置 > 开发者 > 通用链接 -> 诊断工具。输入网址（如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中的Bundle Identifier必须与apple-app-site-association文件中的Bundle Identifier匹配
  • apple-app-site-association文件中AppID前缀的团队ID必须与Apple开发者账户中的团队ID一致
  • 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文件不能有扩展名
  • apple-app-site-association文件必须上传到.well-known目录
  • 不能对apple-app-site-association使用重定向
  • 必须至少保存过一组凭证（如果从未提供过用户名或密码，就无法自动填充）
注意

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

是否需要AutoFill Credential Provider功能？​

不需要此功能。

Associated Domains中是否需要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示例可能有误。苹果这里有一些有效示例。

Contents

编辑此页