How to Integrate Universal Links in Next.js with Capacitor

在iOS上使用Universal Links，在Android上使用App Links，允许用户从链接直接进入您的应用程序，而不需要浏览器。这对于改善用户体验并在Web页面和应用程序之间保持上下文非常有用。在本指南中，我们将逐步介绍如何使用Capacitor为Next.js应用程序设置这些深度链接。

设置深度链接并不需要太多code，但确实需要一些配置。通过本指南的结束，您将能够点击类似 https://www.capgo.app/details/22 并且，如果您的应用程序已安装，则会打开到正确页面。

Next.js深度链接设置

首先，我们将创建一个新的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中，我们可以从 URL 中检索 ID 使用 Next.js 的内置路由器：

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 方案打开时触发。添加一个监听器在 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

This code 监听事件并导航到适当的路由中您的 Next.js 应用程序。 appUrlOpen 事件并导航到适当的路由中您的 Next.js 应用程序。

iOS 配置

对于 iOS，您需要一个具有 Associated Domains 启用的应用 ID。创建一个 apple-app-site-association 文件，替换 YOURTEAMID 和 com.your.bundleid 您的实际团队 ID 和包 ID：

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

将此文件上传到您的域上的 .well-known 目录，使其在 https://www.capgo.app/.well-known/apple-app-site-association.

中可访问： applinks:capgo.app.

在 Xcode 中，使用格式

For Android App Links, follow these steps:

如果您没有一个，请生成一个keystore文件。
从keystore中获取SHA256指纹。
创建一个 assetlinks.json 文件，包含您的包名和SHA256指纹。
将此文件上传到您的域名上的 .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>

上传文件后，您可以使用 Google 的数字资产链接工具验证它。如果设置正确，您将看到一个绿色的勾选标记。 assetlinks.json 使用以下命令来构建和签署您的应用：

这将在您的连接的 Android 设备上安装已签名的应用。

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

__CAPGO_KEEP_0__ 配置本机项目设置

Capacitor Configure for Native Project Settings

__CAPGO_KEEP_0__ configure 包 Capacitor configure package在您的项目根目录创建一个

npm install @capacitor/configure

文件： capacitor.config.yaml 使用此配置运行配置工具：

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

这将应用 YAML 文件中指定的设置到您的本机项目中。

npx cap-config run capacitor.config.yaml

After uploading the __CAPGO_KEEP_0__ file, you can verify it using Google’s Digital Asset Links tool. If everything is set up correctly, you’ll see a green checkmark.

Conclusion

在Capacitor中为Next.js应用设置深度链接涉及配置iOS和Android的域名和项目设置。虽然该过程需要细致的注意，但它比旧方法更流畅，且不需要额外的插件。确保您的域验证文件正确服务，并使用各自平台工具检查它们。设置完成后，应用程序将从Web链接中无缝打开，提供从Web到应用程序的Smooth用户体验。