iOS 通用链接

编辑

学习如何配置 iOS 通用链接以通过标准 Web URL 打开您的 Expo 应用。

要为您的应用配置 iOS 通用链接，您需要设置双向关联以验证您的网站和本地应用。

观看：使用 Expo Router 设置 iOS 通用链接

设置双向关联

要在网站和应用之间建立双向关联，您需要执行以下步骤：

网站验证：这需要在 /.well-known 目录中创建一个 apple-app-site-association (AASA) 文件，并将其托管在目标网站上。该文件用于验证从给定链接打开的应用是否是正确的应用。
本地应用验证：这需要某种形式的代码签名，引用目标网站域（URL）。

创建 AASA 文件

在 /.well-known 目录中为网站验证创建一个 apple-app-site-association 文件。该文件指定您的 Apple 开发者团队 ID、包标识符和支持路径的列表，以重定向到本地应用。

您可以在项目中运行实验性 CLI 命令 npx setup-safari，自动将包标识符注册到您的 Apple 账户，分配权利给该 ID，并在商店中创建 iTunes 应用条目。本地设置将被打印，您可以跳过大部分后续步骤。这是开始使用 iOS 通用链接的最简单方法。

如果您使用 Expo Router 构建网站（或任何其他现代 React 框架，如 Remix、Next.js 等），请在 public/.well-known/apple-app-site-association 中创建 AASA 文件。对于旧版 Expo webpack 项目，请在 web/.well-known/apple-app-site-association 中创建文件。

public/.well-known/apple-app-site-association

{
  // 本部分启用通用链接
  "applinks": {
    "apps": [],
    "details": [
      {
        // 语法: "<APPLE_TEAM_ID>.<BUNDLE_ID>"
        "appID": "QQ57RJ5UTD.com.example.myapp",
        // 所有应该支持重定向的路径。
        "paths": ["/records/*"]
      }
    ]
  },
  // 本部分启用 Apple Handoff
  "activitycontinuation": {
    "apps": ["<APPLE_TEAM_ID>.<BUNDLE_ID>"]
  },
  // 本部分启用共享 Web 凭据
  "webcredentials": {
    "apps": ["<APPLE_TEAM_ID>.<BUNDLE_ID>"]
  }
}

在上述示例中：

对 https://www.myapp.io/records/* 的任何链接（与记录 ID 的通配符匹配）应直接由在 iOS 设备上具有匹配包标识符的应用打开。这是 Apple 团队 ID 和包标识符的组合。
* 通配符不匹配域名或路径分隔符（句点和斜杠）。
activitycontinuation 和 webcredentials 对象是可选的，但建议使用。

请参阅 Apple 的文档获取 AASA 格式的更多详细信息。Branch 提供了一个 AASA 验证器，可以帮助您确认 AASA 是否已正确部署并具有有效格式。

支持 `details` 格式

details 格式在 iOS 13 中得到支持，允许您指定：

appIDs 而不是 appID：使多个应用与相同配置关联更容易
components 数组：允许您指定片段、排除特定路径，并添加注释

来自 Apple 文档的示例 AASA JSON

public/.well-known/apple-app-site-association

{
  "applinks": {
    "details": [
      {
        "appIDs": ["ABCDE12345.com.example.app", "ABCDE12345.com.example.app2"],
        "components": [
          {
            "#": "no_universal_links",
            "exclude": true,
            "comment": "Matches any URL whose fragment equals no_universal_links and instructs the system not to open it as a universal link"
          },
          {
            "/": "/buy/*",
            "comment": "Matches any URL whose path starts with /buy/"
          },
          {
            "/": "/help/website/*",
            "exclude": true,
            "comment": "Matches any URL whose path starts with /help/website/ and instructs the system not to open it as a universal link"
          },
          {
            "/": "/help/*",
            "?": {
              "articleNumber": "????"
            },
            "comment": "Matches any URL whose path starts with /help/ and which has a query item with name 'articleNumber' and a value of exactly 4 characters"
          }
        ]
      }
    ]
  }
}

为了支持所有 iOS 版本，您可以在 details 键中同时提供以上两种格式，但我们建议将较新 iOS 版本的配置放在前面。

托管 AASA 文件

使用您的域名通过 Web 服务器托管 apple-app-site-association 文件。该文件必须通过 HTTPS 连接提供。验证您的浏览器可以访问该文件。

在您设置好 AASA 文件后，将网站部署到支持 HTTPS 的服务器（大多数现代 Web 主机）。

本地应用配置

在部署您的 apple-app-site-association（AASA）文件后，通过将 ios.associatedDomains 添加到您的 app config 来配置您的应用以使用关联域。确保遵循 Apple 指定的格式并不在 URL 中包括协议（https）。这是一个常见错误，会导致通用链接无法正常工作。

例如，如果一个关联网站是 https://expo.dev/，则 applinks 为：

app.json

{
  "expo": {
    "ios": {
      "associatedDomains": ["applinks:expo.dev"]
    }
  }
}

使用 EAS Build 构建您的 iOS 应用，确保权利自动注册到 Apple。

手动本地配置

如果您不使用 EAS 或连续本地生成 (npx expo prebuild)，则必须手动配置您的包标识符的关联域功能。

如果通过 Apple 开发者控制台启用，则确保在您的 ios/[app]/[app].entitlements 文件中添加以下权利：

<key>com.apple.developer.associated-domains</key>
<array>
  <string>applinks:expo.dev</string>
</array>

本地应用验证

在您的 iOS 设备上安装应用以触发验证过程。移动设备上指向您网站的链接应打开您的应用。如果没有，请重新检查先前步骤，以确保您的 AASA 有效、AASA 中指定的路径，以及您在 Apple 开发者控制台中正确配置了应用 ID。

一旦您的应用打开，请参阅处理链接到您的应用获取有关如何处理传入链接并向用户显示他们请求的内容的更多信息。

iOS 在首次安装应用或从 App Store 安装更新时下载您的 AASA。之后，操作系统不会频繁刷新。如果您想更改生产应用中 AASA 的路径，则需要通过 App Store 发布完整更新，以便所有用户的应用重新获取您的 AASA 并识别新路径。

Apple 智能横幅

如果用户未安装您的应用，他们将被引导至网站。您可以使用 Apple 智能横幅在页面顶部显示一个横幅，提示用户安装应用。只有当用户在移动设备上并且没有安装应用时，横幅才会显示。

要启用横幅，请将以下元标记添加到网站的 <head> 中，将 <ITUNES_ID> 替换为您应用的 iTunes ID：

<meta name="apple-itunes-app" content="app-id=<ITUNES_ID>" />

如果您在设置横幅时遇到问题，请运行以下命令以自动生成您的项目的元标记：

Terminal

- npx setup-safari

将元标记添加到您的静态渲染网站

如果您正在使用 Expo Router 构建静态渲染网站，请将 HTML 标记添加到您的 app/+html.js 文件的 <head> 组件中。

app/+html.tsx

import { type PropsWithChildren } from 'react';

export default function Root({ children }: PropsWithChildren) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta httpEquiv="X-UA-Compatible" content="IE=edge" />
        <meta name="apple-itunes-app" content="app-id=<ITUNES_ID>" />
        {/* 其他头部元素... */}
      </head>
      <body>{children}</body>
    </html>
  );
}

调试

Expo CLI 使您可以在不部署网站的情况下测试 iOS 通用链接。利用 --tunnel 功能，您可以将开发服务器转发到公开可用的 HTTPS URL。

设置环境变量 EXPO_TUNNEL_SUBDOMAIN=my-custom-domain，其中 my-custom-domain 是您在开发过程中使用的唯一字符串。这确保您的隧道 URL 在开发服务器重启时保持一致。

将 associatedDomains 添加到您的应用配置中，如上述描述中所示。将域值替换为 Ngrok URL：my-custom-domain.ngrok.io。

使用 --tunnel 标志启动您的开发服务器：

Terminal

- npx expo start --tunnel

在您的设备上编译开发构建：

Terminal

- npx expo run:ios

现在，您可以在设备的 Web 浏览器中输入自定义域链接以打开您的应用。

故障排除

以下是一些帮助您在实现 iOS 通用链接时进行故障排除的常见提示：

阅读 Apple 官方文档以了解调试通用链接
确保您的 apple-app-site-association 文件有效，使用验证工具进行检查。
未压缩的 apple-app-site-association 文件不能大于 128kb。
确保您的网站通过 HTTPS 提供。
如果您更新了 Web 文件，请重新构建本地应用以触发供应商端（Apple）的服务器更新。

iOS 通用链接

设置双向关联

创建 AASA 文件

支持 details 格式

托管 AASA 文件

本地应用配置

本地应用验证

Apple 智能横幅

将元标记添加到您的静态渲染网站

调试

故障排除

支持 `details` 格式