How to Integrate Universal Links in Next.js with Capacitor

Universal links on iOS and App Links on Android allow users to be taken directly into your app from a link, bypassing the browser. This is particularly useful for improving user experience and maintaining the context from a web page to an app. In this guide, we’ll walk through the process of setting up these deep links for a Next.js app using Capacitor. For attribution and deferred deep links, @capgo/capacitor-appsflyer 可以将安装营销活动路由到正确的应用程序屏幕。

Setting up deep links doesn’t require a lot of code, but it does involve some configuration. By the end of this guide, you’ll be able to click a link like 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

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

iOS 配置

对于 iOS，您需要一个具有关联域名功能的应用 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.

在 Xcode 中，使用以下格式将域名添加到您的应用程序的特权中 applinks:capgo.app.

Android 配置

为 Android 应用程序链接，遵循以下步骤

如果您没有一个，请生成一个密钥库文件
从密钥库中获取 SHA256 指纹
创建一个 资产链接 JSON 文件 文件中包含您的包名和 SHA256 指纹
将该文件上传到您的域名上的 .well-known 在您的

directory on your domain, making it accessible at 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__ 配置包 Capacitor configure package创建一个

npm install @capacitor/configure

__CAPGO_KEEP_0__ Configure for Native Project Settings 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

使用此配置运行配置工具:

npx cap-config run capacitor.config.yaml

此操作会将 YAML 文件中指定的设置应用到您的原生项目中。

结论

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

Keep going from How to Integrate Universal Links in Next.js with Capacitor

如果您正在使用 How to Integrate Universal Links in Next.js with Capacitor 来规划原生插件工作，连接它到 Capgo 插件目录为 Capgo 插件目录中的产品工作流程 Capacitor 由 Capgo 提供为 Capacitor 的实现细节在 Capgo 插件中添加或更新插件为 __CAPGO_KEEP_0__ 的实现细节在添加或更新插件中 Ionic 企业插件替代品为 Ionic 企业插件替代品的产品工作流程 Capgo 原生构建为 Capgo 原生构建的产品工作流程