跳转至正文
深度链接

如何在 Next.js 中使用 Capacitor 集成 Universal Links

逐步了解如何在 iOS 和 Android 平台上,使用 Capacitor 为 Next.js 应用配置通用链接。

如何在 Next.js 中集成 Universal Links 与 Capacitor Capgo 博客插图

iOS 上的 Universal Links 和 Android 上的 App Links 允许用户通过链接直接进入您的应用,而无需经过浏览器。这对于提升用户体验并保持从网页到应用的上下文连续性特别有用。在本指南中,我们将介绍如何使用 Capacitor 为 Next.js 应用设置这些深度链接。如需归因和延迟深度链接, @capgo/capacitor-appsflyer 可以将安装活动路由到正确的应用内屏幕。

设置深度链接不需要大量的 code,但确实涉及一些配置。读完本指南后,您将能够点击类似 https://www.capgo.app/details/22 的链接,如果应用已安装,它将打开到正确的页面。

首先,我们将创建一个新的 Next.js 应用和一个用于测试的详情页:

npx create-next-app@latest capgoLinks
cd capgoLinks
mkdir pages/details
touch pages/details/[id].js
npm run build
npx cap add ios
npx cap add android

确保您的 Bundle ID 在 capacitor.config.json 文件,这对配置至关重要:

{
  "appId": "com.capgo.deeplinks",
  "appName": "capgoLinks",
  "webDir": "out",
  "bundledWebRuntime": false
}

在路由方面,Next.js 使用基于文件的路由,因此只需在 pages/details/[id].js创建文件,我们就已经设置好了通配符路由。

在 pages/details/[id].js,我们可以使用 Next.js 内置的路由器从 URL 中获取 ID:

import { useRouter } from 'next/router'

function DetailsPage() {
  const router = useRouter()
  const { id } = router.query

  return (
    <div>
      <p>My ID: {id}</p>
    </div>
  )
}

export default DetailsPage

现在,让我们处理 appUrlOpen 事件,使用 Capacitor。当应用通过自定义 URL scheme 打开时,会触发此事件。请在 pages/_app.js 文件:

import { useEffect } from 'react'
import { App } from '@capacitor/app'

function MyApp({ Component, pageProps }) {
  useEffect(() => {
    App.addListener('appUrlOpen', (event) => {
      const slug = event.url.split('.app').pop()
      if (slug)
        window.location.href = slug

    })
  }, [])

  return <Component {...pageProps} />
}

export default MyApp

此 code 监听 appUrlOpen 事件,并导航到 Next.js 应用中的相应路由。

iOS 配置

对于 iOS,你需要一个启用了 Associated Domains 的应用 ID。创建一个 apple-app-site-association 包含以下内容的文件, YOURTEAMID 以及 com.your.bundleid 替换为你的实际 Team ID 和 Bundle ID:

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "YOURTEAMID.com.your.bundleid",
        "paths": ["*"]
      }
    ]
  }
}

将此文件上传到 .well-known 你域名下的目录,使其可通过以下地址访问: https://www.capgo.app/.well-known/apple-app-site-association.

在 Xcode 中,按以下格式将域名添加到 App 的 entitlements: applinks:capgo.app.

Android 配置

对于 Android App Links,请按以下步骤操作:

  1. 如果你没有 keystore 文件,请生成一个。
  2. 从 keystore 中获取 SHA256 指纹。
  3. 创建一个 assetlinks.json 包含您的包名和 SHA256 指纹的文件。
  4. 将此文件上传到 .well-known 您域名下的目录。

在您的 AndroidManifest.xml中,添加一个 intent-filter 到 activity 元素来处理深度链接:

<activity ...>
  <intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="https" android:host="capgo.app" />
  </intent-filter>
</activity>

上传 assetlinks.json 文件后,您可以使用 Google 的 Digital Asset Links 工具进行验证。如果一切设置正确,您会看到一个绿色对勾。

要构建并签名您的应用,请使用以下命令:

cd android
./gradlew assembleRelease
cd ..
jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore my-release-key.keystore android/app/build/outputs/apk/release/app-release-unsigned.apk alias_name
zipalign -v 4 android/app/build/outputs/apk/release/app-release-unsigned.apk capgo.apk
adb install capgo.apk

这会将签名后的应用安装到您连接的 Android 设备上。

Capacitor 配置原生项目设置

若要自动化原生项目设置,建议使用 Capacitor configure 包。在你的项目中安装它:

npm install @capacitor/configure

创建一个 capacitor.config.yaml 位于项目根目录的 file:

vars:
  BUNDLE_ID: com.capgo.deeplinks
  PACKAGE_NAME: com.capgo.deeplinks
platforms:
  ios:
    targets:
      App:
        bundleId: $BUNDLE_ID
    entitlements:
      - com.apple.developer.associated-domains: ['applinks:capgo.app']
  android:
    packageName: $PACKAGE_NAME

使用此配置运行 configure 工具:

npx cap-config run capacitor.config.yaml

这将把 YAML 文件中指定的设置应用到你的原生项目。

总结

为 Next.js 应用设置 Capacitor 深度链接,需要为 iOS 和 Android 配置域名和项目设置。虽然该过程需要细致操作,但相比旧方法更为简化,且无需额外插件。请确保域名验证文件正确提供,并使用相应平台工具进行检查。设置完成后,应用将无缝从 Web 链接打开,为用户提供从 Web 到应用的流畅体验。

如果你正在使用 如何在 Next.js 中使用 Capacitor 集成 Universal Links 要规划原生插件工作,请将其与 Capgo 插件目录 查看 Capgo 插件目录中的产品工作流, Capgo 提供的 Capacitor 插件 查看由 Capgo 提供的 Capacitor 插件中的实现细节, 添加或更新插件 查看添加或更新插件中的实现细节, Ionic Enterprise 插件替代方案 查看 Ionic Enterprise 插件替代方案中的产品工作流,以及 Capgo Native Build 查看 Capgo Native Builds 中的产品工作流。

为 Capacitor 应用提供 Live Updates

当 Web 层出现线上 Bug 时,通过 Capgo 发布修复,而不用等 App Store 审核好几天。用户会在后台收到更新,原生变更则仍走正常审核流程。

博客最新动态

Capgo 为你提供打造真正专业的移动应用所需的最有价值的洞察。