How to Integrate Universal Links in Next.js with Capacitor

iOS에서 Universal links 및 Android에서 App Links를 사용하면 사용자가 링크를 클릭하여 앱으로 바로 이동할 수 있습니다. 이 기능은 브라우저를 피하고 웹 페이지에서 앱으로의 컨텍스트를 유지하는 데 특히 유용합니다. 이 가이드에서는 Capacitor를 사용하여 Next.js 앱에 이러한 깊은 링크를 설정하는 과정을 안내합니다.

깊은 링크를 설정하는 데는 code가 많이 필요하지 않지만, 몇 가지 설정이 필요합니다. 이 가이드를 마치면, 앱이 설치된 경우 링크를 클릭하여 올바른 페이지로 앱이 열리는 것을 확인할 수 있습니다. https://www.capgo.app/details/22 Next.js 깊은 링크 설정

첫 번째로, 새로운 Next.js 앱과 테스트를 위한 details 페이지를 생성합니다.

__CAPGO_KEEP_0__.config.json__ 파일에 올바르게 설정된

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 가 필요합니다. 이는 설정에 중요합니다. Next.js는 파일 기반 라우팅을 사용하므로, capacitor.config.json __CAPGO_KEEP_0__

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

__CAPGO_KEEP_0__ pages/details/[id].js__CAPGO_KEEP_0__

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 file with the following content, replacing YOURTEAMID and 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 서명 값을 얻으세요.
패키지 이름과 SHA256 서명 값을 포함한 assetlinks.json 파일을 생성하세요.
이 파일을 .well-known __CAPGO_KEEP_0__

__CAPGO_KEEP_0__ AndroidManifest.xml__CAPGO_KEEP_0__ intent-filter __CAPGO_KEEP_0__ activity __CAPGO_KEEP_0__

<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>

__CAPGO_KEEP_0__ 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

__CAPGO_KEEP_0__ Capacitor. 프로젝트에 설치하세요:

npm install @capacitor/configure

Create a 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 tool을 실행하세요:

npx cap-config run capacitor.config.yaml

이 YAML 파일에 지정된 설정을 Native 프로젝트에 적용합니다.

Conclusion

Capacitor를 사용하여 Next.js 앱에 대한 깊이 있는 링크를 설정하는 것은 iOS와 Android의 도메인 및 프로젝트 설정을 구성하는 것입니다. 프로세스는 주의가 필요하지만 이전 방법에 비해 더 간소화되어 추가 플러그인 없이도 처리할 수 있습니다. 도메인 인증 파일이 올바르게 제공되고 플랫폼별 도구로 확인되었는지 확인하세요. 설정이 완료되면 앱은 웹 링크에서 무난하게 열리며, 사용자가 웹에서 앱으로 전환하는 과정을 편리하게 제공합니다.