iOS 上的 Universal Links 和 Android 上的 App Links 允许用户通过链接直接进入您的应用,而无需经过浏览器。这对于提升用户体验并保持从网页到应用的上下文连续性特别有用。在本指南中,我们将介绍如何使用 Capacitor 为 Next.js 应用设置这些深度链接。如需归因和延迟深度链接, @capgo/capacitor-appsflyer 可以将安装活动路由到正确的应用内屏幕。
设置深度链接不需要大量的 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,我们可以使用 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,请按以下步骤操作:
- 如果你没有 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>
上传 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 中集成 Universal Links 与 Capacitor
如果你正在使用 如何在 Next.js 中使用 Capacitor 集成 Universal Links 要规划原生插件工作,请将其与 Capgo 插件目录 查看 Capgo 插件目录中的产品工作流, Capgo 提供的 Capacitor 插件 查看由 Capgo 提供的 Capacitor 插件中的实现细节, 添加或更新插件 查看添加或更新插件中的实现细节, Ionic Enterprise 插件替代方案 查看 Ionic Enterprise 插件替代方案中的产品工作流,以及 Capgo Native Build 查看 Capgo Native Builds 中的产品工作流。