Universal Links in Next.js mit Capacitor integrieren

Universal Links auf iOS und App Links auf Android ermöglichen es, Nutzer direkt über einen Link in deine App zu leiten, ohne den Browser zu nutzen. Das verbessert die User Experience erheblich und bewahrt den Kontext beim Wechsel von der Website zur App. In diesem Guide zeigen wir dir, wie du diese Deep Links für eine Next.js App mit Capacitor einrichtest. Für Attribution und Deferred Deep Links @capgo/capacitor-appsflyer kann Install-Kampagnen direkt an den richtigen In-App-Screen routen.

Die Einrichtung von Deep Links erfordert nicht viel code, aber ein wenig Konfiguration ist nötig. Am Ende dieses Guides kannst du auf einen Link wie diesen klicken: https://www.capgo.app/details/22 und die App öffnet direkt die richtige Seite, falls sie installiert ist.

Next.js Deep Link Setup

Zuerst erstellen wir eine neue Next.js App und eine Detailseite zum Testen:

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

Ensure your Bundle ID is correctly set in the capacitor.config.json Datei, da sie für das Setup entscheidend ist:

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

Für das Routing nutzt Next.js file-based routing. Durch das Erstellen einer Datei unter pages/details/[id].jshaben wir unsere Wildcard-Route bereits eingerichtet.

Unter pages/details/[id].jskönnen wir die ID über den integrierten Next.js Router aus der URL auslesen:

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

Jetzt kümmern wir uns um das appUrlOpen Capacitor Event. Dieses Event wird ausgelöst, wenn die App über ein Custom URL Scheme geöffnet wird. Füge einen Listener in der pages/_app.js Datei:

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

Dieser code lauscht auf das appUrlOpen Event und navigiert zur passenden Route in deiner Next.js App.

iOS Konfiguration

Für iOS benötigst du eine App ID mit aktiviertem Associated Domains. Erstelle eine apple-app-site-association Datei mit folgendem Inhalt und ersetze YOURTEAMID und com.your.bundleid durch deine tatsächliche Team ID und Bundle ID:

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "YOURTEAMID.com.your.bundleid",
        "paths": ["*"]
      }
    ]
  }
}

Lade diese Datei in den .well-known Verzeichnis auf deiner Domain, erreichbar unter https://www.capgo.app/.well-known/apple-app-site-association.

Füge in Xcode die Domain im Format folgender Entitlements deiner App hinzu: applinks:capgo.app.

Android-Konfiguration

Für Android App Links folge diesen Schritten:

Erstelle eine Keystore-Datei, falls du noch keine hast.
Rufe den SHA256-Fingerprint aus dem Keystore ab.
Erstelle eine assetlinks.json Datei mit deinem Package-Namen und dem SHA256-Fingerprint.
Lade diese Datei in das .well-known Verzeichnis auf deiner Domain hoch.

In deinem AndroidManifest.xml, füge einen intent-filter zum activity -Element hinzu, das Deep Links verarbeitet:

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

Nach dem Upload der assetlinks.json -Datei kannst du diese mit Googles Digital Asset Links Tool verifizieren. Wenn alles korrekt eingerichtet ist, erscheint ein grünes Häkchen.

Um deine App zu builden und zu signieren, verwende die folgenden Befehle:

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

Dadurch wird die signierte App auf deinem verbundenen Android-Gerät installiert.

Capacitor Konfiguration für Native Project Settings

Um Native Project Settings zu automatisieren, solltest du das Capacitor configure Package in Betracht ziehen. Installiere es in deinem Projekt:

npm install @capacitor/configure

Erstelle ein capacitor.config.yaml Datei im Root-Verzeichnis deines Projekts:

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

Führe das Configure-Tool mit dieser Config aus:

npx cap-config run capacitor.config.yaml

Dadurch werden die in der YAML-Datei angegebenen Einstellungen auf deine nativen Projekte angewendet.

Fazit

Die Einrichtung von Deep Links mit Capacitor für eine Next.js-App erfordert die Konfiguration deiner Domain- und Projekteinstellungen für iOS und Android. Der Prozess verlangt Sorgfalt, ist aber im Vergleich zu älteren Methoden deutlich einfacher und braucht keine zusätzlichen Plugins. Stelle sicher, dass deine Domain-Verifizierungsdateien korrekt ausgeliefert werden, und prüfe sie mit den Tools der jeweiligen Plattform. Nach der Einrichtung öffnet sich deine App nahtlos aus Web-Links – ein reibungsloser Übergang für deine Nutzer von der Website in die App.

Weiterlesen: So integrierst du Universal Links in Next.js mit Capacitor

Wenn du es nutzt Universal Links in Next.js mit Capacitor integrieren Um die Arbeit an nativen Plugins zu planen, verbinde sie mit Capgo Plugin-Verzeichnis für den Produkt-Workflow im Capgo Plugin-Verzeichnis, Capacitor Plugins von Capgo für das Implementierungsdetail in Capacitor Plugins von Capgo, Plugins hinzufügen oder aktualisieren für die Implementierungsdetails unter „Plugins hinzufügen oder aktualisieren“, Ionic Enterprise Plugin-Alternativen für den Produkt-Workflow in Ionic Enterprise Plugin-Alternativen und Capgo Native Builds für den Produkt-Workflow in Capgo Native Builds.