Appy

Deep linking

Cos’è Associated Domains?

In breve

Associated Domains è una capability e un entitlement di Apple che elenca i domini web a cui un’app è collegata. Ogni voce abbina un servizio a un dominio, per esempio applinks:example.com. Insieme al file apple-app-site-association su quel dominio, abilita Universal Links, credenziali web condivise, Handoff e App Clip.

Cosa contiene l’entitlement

L’entitlement è un elenco di stringhe nella forma service:domain. Apple definisce quattro servizi. applinks è per gli Universal Links. webcredentials permette all’app di usare le password salvate per il sito web. activitycontinuation è per Handoff. appclips lega un App Clip a un dominio.

Il dominio si scrive nudo: niente https://, niente percorso, niente barra finale e, secondo la technote di Apple, nemmeno il numero di porta. Ogni sottodominio è una voce a sé. Per tutti i servizi tranne appclips, il prefisso *. vale per tutti i sottodomini, come in applinks:*.example.com.

Come si abbina al file sul dominio

L’entitlement è una metà di un controllo a doppio senso. L’app rivendica un dominio, e il dominio conferma elencando l’ID dell’app nel suo file apple-app-site-association (AASA). Se manca una delle due metà, il servizio resta spento e iOS non segnala nulla all’utente.

Quando l’app viene installata, il sistema scarica il file per ogni dominio elencato. Da iOS 14 quella richiesta va a una CDN gestita da Apple invece che al tuo server. La documentazione di Apple dice che la CDN richiede il file entro 24 ore e che i dispositivi cercano aggiornamenti circa una volta alla settimana.

Come si imposta e come si testa

In Xcode apri la scheda Signing & Capabilities del target, aggiungi la capability Associated Domains e inserisci una riga per dominio. Così la funzione viene attivata anche per l’App ID. Un App Clip ha bisogno della stessa voce sia sul target dell’app sia sul target dell’App Clip.

Per un server che non è raggiungibile da internet, aggiungi ?mode=developer alla voce. I dispositivi in modalità sviluppatore scaricano allora il file direttamente, e possono usarlo solo le build firmate con un profilo di sviluppo. Una seconda modalità, managed, serve i dispositivi registrati in un sistema di mobile device management. Togli il suffisso prima di pubblicare: una build di release deve passare dalla CDN come il telefono di chiunque altro. La technote di Apple descrive anche un controllo rapido sul dispositivo: con Associated Domains Development attivato nelle impostazioni Sviluppatore, una schermata Diagnostics dice se un certo indirizzo è valido per un’app installata.

EsempioVoci dell’entitlement
applinks:example.com, webcredentials:example.com

Provalo qui

Genera il file per la tua app

Inserisci Team ID e bundle ID, oppure nome del pacchetto e impronta di firma. Ottieni il file apple-app-site-association o assetlinks.json pronto da caricare sul tuo server.

App

Aggiungi ogni app che deve aprire i link di questo dominio. Ognuna diventa una voce di appIDs.

  1. App 1

    10 caratteri, nel tuo account Apple Developer sotto Membership details.

    Dal target della tua app in Xcode, per esempio com.example.app.

Percorsi che aprono l’app

Le regole vengono lette dall’alto in basso e vince la prima che corrisponde, quindi metti le esclusioni sopra le regole più ampie. * corrisponde a qualsiasi numero di caratteri, ? a uno solo.

  1. Regola 1

    coppie nome=valore unite da &

Altri servizi

Il tuo file

apple-app-site-association

Esempio. Inserisci i tuoi dati per sostituirlo.

{
  "applinks": {
    "details": [
      {
        "appIDs": [
          "ABCDE12345.com.example.app"
        ],
        "components": [
          {
            "/": "/*"
          }
        ]
      }
    ]
  }
}

Generato nel tuo browser. Non viene inviato nulla.

Dove pubblicarlo

Dove va il file

  1. Caricalo su https://tuo-dominio/.well-known/apple-app-site-association, senza estensione .json.
  2. Servilo in HTTPS con un certificato valido e un 200 diretto, senza redirect.
  3. Invia l’intestazione Content-Type: application/json.
  4. Ripeti su ogni host dei tuoi link: example.com e www.example.com richiedono ciascuno il file e una voce applinks:.
  5. La CDN di Apple recupera il nuovo file entro 24 ore. Nel frattempo prova con ?mode=developer.
Controlla un dominio con il validatore

Preferisci non ospitare file da solo? Gli smart link sono gratis e con Enterprise Appy serve entrambi i file sul dominio di link della tua app.

Crea un link gratis
Per approfondireGuida completa agli Universal Links per iOS e AndroidDove si colloca la voce Associated Domains in una configurazione completa di Universal Links e App Links, passo per passo.

Domande frequenti

Che differenza c’è tra Associated Domains e Universal Links?

Associated Domains è il meccanismo. Gli Universal Links sono una delle funzioni costruite sopra. L’entitlement può abilitare anche credenziali web condivise, Handoff e App Clip. Per gli Universal Links, in particolare, aggiungi una voce applinks: ed elenchi l’app sotto applinks nel file sul tuo dominio.

Posso usare un carattere jolly in Associated Domains?

Sì. Metti *. davanti al dominio per coprire tutti i suoi sottodomini, per esempio applinks:*.example.com, e ospita il file sul dominio principale. Il carattere jolly non è ammesso per il servizio appclips, e non copre il dominio principale, che ha bisogno di una voce propria.

Perché la mia voce in Associated Domains non funziona?

Controlla i tre sospetti soliti. La voce contiene uno scheme, un percorso o una porta. Il dominio nella voce e l’host che serve il file sono diversi, per esempio example.com contro www.example.com. Oppure il file passa da un redirect o è bloccato, e la CDN di Apple non ne ottiene mai una copia.

  • Universal Links

    Gli Universal Links (link universali) sono i link https di Apple che aprono direttamente un’app iOS installata invece del sito web, disponibili da iOS 9. Richiedono l’entitlement Associated Domains nell’app, per esempio applinks:example.com, e un file apple-app-site-association sul dominio. Senza l’app, lo stesso link apre semplicemente il sito web.

  • apple-app-site-association (AASA)

    Il file apple-app-site-association, o AASA, è un file JSON pubblicato sul tuo dominio all’indirizzo /.well-known/apple-app-site-association. Dice a iOS quali app possono aprire i link di quel dominio, ognuna identificata da Team ID e bundle ID, e per quali percorsi. Senza questo file gli Universal Links non funzionano.

  • App Clip

    Un App Clip è una versione leggera di un’app iOS che si può usare senza installare l’app completa. Parte da un’invocazione, come un App Clip Code, un QR code, un tag NFC, un link in Messaggi o un banner in Safari, svolge un solo compito preciso e può poi proporre l’app completa.

Tutto il glossario

Un solo link per App Store, Google Play e web

Crea uno smart link con il suo QR code: ogni telefono arriva allo store giusto, ogni computer al tuo sito. Gratis fino a 4 link, senza pubblicità.