How to Integrate Universal Links in Next.js with Capacitor

iOS 和 Android 上的 Universal links 和 App Links 允许用户通过点击链接直接进入应用，绕过浏览器。这对于改善用户体验和保持从网页到应用的上下文非常有用。在本指南中，我们将介绍如何使用 Capacitor 为 Next.js 应用设置这些深度链接。对于 attribution 和延迟深度链接, @capgo/capacitor-appsflyer 可以将安装推广活动路由到正确的应用内屏幕。

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

Next.js 深度链接设置

首先，我们将创建一个新的 Next.js 应用和一个用于测试的 details 页面：

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
}

For routing, Next.js uses file-based routing, so by creating a file at pages/details/[id].js, we’ve already set up our wildcard route.

In pages/details/[id].js, we can retrieve the ID from the URL using Next.js’s built-in router:

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

Now, let’s handle the appUrlOpen event with Capacitor. This event is triggered when the app is opened via a custom URL scheme. Add a listener in the pages/_app.js file:

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 listens for the appUrlOpen event and navigates to the appropriate route within your Next.js app.

iOS Configuration

For iOS, you’ll need an app ID with Associated Domains enabled. Create an 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 App Links，请遵循以下步骤

如果你没有一个，请生成一个keystore文件
从keystore中获取SHA256指纹
创建一个 assetlinks.json 使用您的包名和SHA256指纹的文件。
将此文件上传到您的域名上的目录。 .well-known 在您的

中添加一个 AndroidManifest.xml到处理深度链接的元素： intent-filter 上传文件后，您可以使用Google的数字资产链接工具进行验证。如果设置正确，您将看到一个绿色的勾选标记。 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>

此命令将在您的连接的Android设备上安装已签名的应用。 assetlinks.json __CAPGO_KEEP_0__ 配置原生项目设置

__CAPGO_KEEP_0__

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

To automate native project settings, consider using the 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

使用这个配置运行configure工具:

npx cap-config run capacitor.config.yaml

这会将YAML文件中指定的设置应用到你的native项目。

结论

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

继续阅读《如何在Next.js中集成universal links withCapacitor》

如果你正在使用《如何在Next.js中集成universal links with__CAPGO_KEEP_0__》 Capacitor 为native插件工作做好规划，连接它与 Capgo 插件目录产品工作流程在 Capgo 插件目录中 Capacitor 插件由 Capgo 产品工作流程在 Capacitor 插件由 Capgo 中添加或更新插件添加或更新插件的实现细节 Ionic企业插件替代方案产品工作流程在 Ionic企业插件替代方案中，以及 Capgo 原生构建产品工作流程在 Capgo 原生构建中。