Come integrare i Universal Links in Next.js con Capacitor

I Universal Links su iOS e gli App Links su Android permettono agli utenti di aprire direttamente la tua app da un link, bypassando il browser. È particolarmente utile per migliorare la user experience e mantenere il contesto da una pagina web all'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 aprire l'app sulla pagina corretta se è già installata.

Configurazione Deep Link con Next.js

Per prima cosa, 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

Ensure your bundle ID sia configurato correttamente nel file capacitor.config.json , poiché è fondamentale per il setup:

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

Per il routing, Next.js utilizza un sistema basato sui file, quindi creando un file in pages/details/[id].js, abbiamo già impostato 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' appUrlOpen con Capacitor. Questo evento viene attivato quando l'app viene aperta tramite uno scheme URL personalizzato. Aggiungi un listener nel 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

Questo code ascolta l'evento appUrlOpen e naviga verso la rotta corretta all'interno della tua app Next.js.

Configurazione iOS

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

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

Carica questo file su .well-known directory sul tuo dominio, rendendola 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 Android App Links, segui questi passaggi:

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

Nel tuo AndroidManifest.xml, aggiungi un intent-filter all' activity elemento 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 con lo strumento Digital Asset Links di Google. Se tutto è configurato correttamente, vedrai una spunta verde.

Per buildare e firmare la tua app, usa questi 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 Configurazione per le impostazioni del progetto Native

Per automatizzare le impostazioni del progetto native, considera l'uso del Capacitor pacchetto di configurazione. Installalo nel tuo progetto:

npm install @capacitor/configure

Crea un capacitor.config.yaml file nella root del 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

Esegui lo strumento di configurazione con questa config:

npx cap-config run capacitor.config.yaml

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

Conclusione

Configurare i deep link con Capacitor per un'app Next.js richiede la configurazione del dominio e delle impostazioni di progetto sia per iOS che per Android. Sebbene il processo richieda attenzione ai dettagli, è più snello rispetto ai vecchi metodi e non richiede plugin aggiuntivi. Assicurati che i file di verifica del dominio siano serviti correttamente e controllali con gli strumenti delle rispettive piattaforme. Una volta configurato, la tua app si aprirà senza interruzioni dai link web, garantendo un passaggio fluido per gli utenti dal web all'app.

Continua da Come integrare gli Universal Links in Next.js con Capacitor

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 Capgo per il workflow del prodotto nella Directory dei plugin Capgo, Plugin Capacitor di Capgo per i dettagli di implementazione in Capacitor Plugins di Capgo, Aggiungere o aggiornare i plugin per i dettagli di implementazione in Aggiungere o aggiornare i plugin, Alternative ai plugin Ionic Enterprise per il workflow del prodotto in Alternative ai plugin Ionic Enterprise, e Capgo Native Build per il workflow del prodotto in Capgo Native Builds.