본문 바로가기
Deep Linking

Capacitor로 Next.js에 Universal Links를 연동하는 방법

iOS와 Android 플랫폼 모두에서 Capacitor로 Next.js 앱의 Universal Links를 설정하는 방법을 단계별로 알아보세요.

Capacitor Capgo를 사용하여 Next.js에 Universal Links를 통합하는 방법 blog illustration

iOS의 Universal links와 Android의 App Links를 사용하면 사용자가 브라우저를 거치지 않고 링크를 통해 앱으로 바로 이동할 수 있습니다. 이는 사용자 경험을 개선하고 웹 페이지의 컨텍스트를 앱으로 유지하는 데 매우 유용합니다. 이 가이드에서는 Capacitor를 사용하여 Next.js 앱에 이러한 딥 링크를 설정하는 과정을 살펴보겠습니다. 어트리뷰션 및 디퍼드 딥 링크(deferred deep links)의 경우, @capgo/capacitor-appsflyer 캠페인을 앱 내의 올바른 화면으로 라우팅할 수 있습니다.

딥 링크 설정에 많은 code가 필요하지는 않지만, 몇 가지 구성 작업이 필요합니다. 이 가이드를 마치면 다음과 같은 링크를 클릭했을 때 https://www.capgo.app/details/22 앱이 설치되어 있다면 올바른 페이지로 바로 열리게 됩니다.

먼저, 테스트를 위한 새로운 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].jsNext.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가 활성화된 App 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에서 다음 형식을 사용하여 앱의 entitlements에 도메인을 추가하세요: applinks:capgo.app.

Android 설정

Android App Links를 설정하려면 다음 단계를 따르세요:

  1. keystore 파일이 없다면 새로 생성하세요.
  2. keystore에서 SHA256 fingerprint를 추출하세요.
  3. 다음 파일을 생성합니다: assetlinks.json 패키지 이름과 SHA256 fingerprint가 포함된 파일입니다.
  4. 이 파일을 다음 위치에 업로드하세요: .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 Native 프로젝트 설정 구성

네이티브 프로젝트 설정을 자동화하려면 다음을 사용하는 것이 좋습니다: Capacitor configure 패키지프로젝트에 설치하세요:

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 파일에 지정된 설정이 네이티브 프로젝트에 적용됩니다.

마치며

Next.js 앱에 Capacitor를 사용하여 딥 링크를 설정하려면 iOS와 Android 모두에 대해 도메인 및 프로젝트 설정을 구성해야 합니다. 세심한 주의가 필요한 과정이지만, 기존 방식보다 간소화되었으며 추가 플러그인이 필요하지 않습니다. 도메인 검증 파일이 올바르게 서빙되는지 확인하고 각 플랫폼 도구로 검증하세요. 설정이 완료되면 웹 링크를 통해 앱이 매끄럽게 열리며, 사용자가 웹에서 앱으로 자연스럽게 전환될 수 있습니다.

사용 중이라면 Capacitor로 Next.js에 Universal Links를 연동하는 방법 네이티브 플러그인 작업을 계획하려면, 이를 다음 항목과 연결하세요: Capgo 플러그인 디렉토리 Capgo Plugin Directory의 제품 워크플로우에 맞춰, Capgo의 Capacitor 플러그인 Capgo의 Capacitor 플러그인 구현 상세 내용에 대해서는, 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트의 구현 세부 사항은, Ionic Enterprise 플러그인 대안 Ionic Enterprise 플러그인 대안의 제품 워크플로우와, Capgo Native Build Capgo Native Builds의 제품 워크플로우를 위해.

Capacitor 앱용 Live updates

웹 레이어 버그가 라이브 상태라면, 앱 스토어 승인을 며칠씩 기다리지 말고 Capgo를 통해 수정 사항을 배포하세요. 네이티브 변경 사항은 정상 리뷰 절차를 그대로 따르는 반면, 사용자는 백그라운드에서 업데이트를 받습니다.

블로그 최신 글

Capgo는 정말 프로페셔널한 모바일 앱을 만드는 데 필요한 최고의 인사이트를 제공합니다.