Salta al contenuto principale
Deep Linking

Come integrare gli Universal Links in Next.js con Capacitor

Scopri passo dopo passo come configurare gli universal links per la tua app Next.js con Capacitor su iOS e Android.

Come integrare Universal Links in Next.js con Capacitor Capgo illustrazione del blog

I Universal Links su iOS e gli App Links su Android permettono agli utenti di accedere direttamente alla tua app tramite un link, bypassando il browser. Questo è particolarmente utile per migliorare la user experience e mantenere il contesto da una pagina web a un'app. In questa guida vedremo come configurare questi deep link per un'app Next.js usando Capacitor. Per l'attribuzione e i deferred deep link, @capgo/capacitor-appsflyer può indirizzare le campagne di installazione verso la schermata corretta dell'app.

Configurare i deep link non richiede molto code, ma comporta un po' di configurazione. Alla fine di questa guida, potrai cliccare su un link come https://www.capgo.app/details/22 e far sì che l'app si apra sulla pagina corretta se è installata.

Prima di tutto, creeremo una nuova app Next.js e una pagina di dettaglio per i test:

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

Assicurati che bundle ID sia impostato correttamente nel capacitor.config.json file, fondamentale per la configurazione:

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

Per il routing, Next.js usa il file-based routing, quindi creando un file in pages/details/[id].js, abbiamo già configurato la nostra wildcard route.

In pages/details/[id].js, possiamo recuperare l'ID dall'URL usando il router integrato di Next.js:

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

Ora, gestiamo l'evento appUrlOpen con Capacitor. Questo evento viene attivato quando l'app viene aperta tramite uno schema URL personalizzato. Aggiungi un listener in pages/_app.js dell'app:

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

Questo code ascolta l'evento appUrlOpen e naviga alla route appropriata all'interno della tua app Next.js.

Configurazione iOS

Per iOS, avrai bisogno di un app ID con Associated Domains abilitato. Crea un apple-app-site-association file con il seguente contenuto, sostituendo YOURTEAMID e com.your.bundleid con il tuo team ID e bundle ID effettivi:

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

Carica questo file nella .well-known directory sul tuo dominio, rendendolo accessibile a https://www.capgo.app/.well-known/apple-app-site-association.

In Xcode, aggiungi il dominio agli entitlements della tua app usando il formato applinks:capgo.app.

Configurazione Android

Per gli App Links di Android, segui questi passaggi:

  1. Genera un file keystore se non ne hai uno.
  2. Ottieni l'impronta SHA256 dal keystore.
  3. Crea un assetlinks.json file con il nome del tuo package e l'impronta SHA256.
  4. Carica questo file nella .well-known directory sul tuo dominio.

Nel tuo AndroidManifest.xml, aggiungi un intent-filter all'elemento activity che gestisce i deep link:

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

Dopo aver caricato il assetlinks.json file, puoi verificarlo usando lo strumento Digital Asset Links di Google. Se tutto è configurato correttamente, vedrai un segno di spunta verde.

Per compilare e firmare la tua app, usa i seguenti comandi:

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

Questo installerà l'app firmata sul tuo dispositivo Android connesso.

Capacitor Configurare le impostazioni del progetto nativo

Per automatizzare le impostazioni del progetto nativo, valuta l'uso del pacchetto Capacitor configure. Installalo nel tuo progetto:

npm install @capacitor/configure

Crea un capacitor.config.yaml file nella radice del tuo progetto:

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

Run the configure tool with this config:

npx cap-config run capacitor.config.yaml

Questo applicherà le impostazioni specificate nel file YAML ai tuoi progetti nativi.

Conclusione

La configurazione dei deep link con Capacitor per un'app Next.js richiede di impostare il dominio e le impostazioni del progetto sia per iOS che per Android. Sebbene il processo richieda attenzione ai dettagli, è più snello rispetto ai metodi precedenti e non richiede plugin aggiuntivi. Assicurati che i file di verifica del dominio vengano serviti correttamente e controllali con gli strumenti della rispettiva piattaforma. Una volta configurato, la tua app si aprirà senza interruzioni dai link web, offrendo ai tuoi utenti una transizione fluida da web a app.

Se stai usando Come integrare gli Universal Links in Next.js con Capacitor per pianificare il lavoro sui plugin nativi, collegalo a Directory dei plugin di Capgo per il workflow del prodotto nella Capgo Plugin Directory, Plugin Capacitor di Capgo per i dettagli di implementazione in Capacitor Plugins di Capgo, Aggiunta o aggiornamento dei plugin per i dettagli sull'implementazione in Adding or Updating Plugins, Alternative ai plugin Ionic Enterprise per il workflow del prodotto in Ionic Enterprise Plugin Alternatives, e Capgo Native Build per il workflow di prodotto in Capgo Native Builds.

Live updates per le app Capacitor

Quando un bug nel web-layer è live, rilascia la fix tramite Capgo invece di aspettare giorni l'approvazione degli store. Gli utenti ricevono l'update in background, mentre le modifiche native restano nel normale processo di review.

Ultimi articoli dal blog

Capgo ti offre gli insight migliori che ti servono per creare un'app mobile davvero professionale.