Inizia: accedi all'API Gemini tramite il framework Foundation Models di Apple

Anteprima: l'utilizzo di Firebase AI Logic per accedere a Gemini API tramite il framework Foundation Models di Apple è attualmente in anteprima pubblica, il che significa che non è soggetto a SLA (accordo sul livello del servizio) o a norme sul ritiro e potrebbe cambiare in modi incompatibili con le versioni precedenti.
Inoltre, questa integrazione si basa su API beta, pertanto le app che la utilizzano non possono essere inviate all'App Store finché la versione successiva di Xcode non raggiunge la disponibilità generale e non supporta gli invii di produzione.

Alla WWDC 2026, Apple ha aperto il framework Foundation Models agli adattatori di modelli di terze parti, il che significa che puoi accedere a modelli ospitati sul cloud (come Gemini) tramite il framework Foundation Models utilizzando la stessa API che useresti per accedere ai modelli sul dispositivo.

Nella tua app, puoi scambiare l'istanza del modello per indirizzare le richieste all'inferenza sul dispositivo o sul cloud in base al tuo caso d'uso:

• I modelli on-device offrono massima privacy, zero costi e supporto offline.
• I modelli Gemini ospitati sul cloud offrono finestre contestuali di grandi dimensioni, funzionalità avanzate e maggiore capacità di ragionamento.

Puoi accedere ai modelli Gemini ospitati sul cloud tramite il framework Foundation Models di Apple utilizzando l'SDK Firebase per le piattaforme Apple, in particolare la libreria Firebase AI Logic. Questa guida ti mostra come iniziare.

Per proteggere l'accesso ai modelli Gemini, questa guida mostra anche come configurare Firebase App Check, che è fondamentale anche durante lo sviluppo.

Prerequisiti

• Installa l'ultima versione beta di Xcode 27.

• Un simulatore di piattaforma Apple o un dispositivo fisico, entrambi con la versione beta del sistema operativo corrispondente (ad esempio iOS 27 beta).

• Un nuovo progetto Xcode di un'app per piattaforme Apple che utilizza un'interfaccia SwiftUI.

Nota: per questa release iniziale, sono supportate le seguenti piattaforme Apple: iOS e macOS.

Modelli Gemini supportati

L'integrazione con il framework Foundation Models di Apple supporta i seguenti modelli Gemini.

• Modelli per uso generico

  • gemini-3.1-pro-preview
  • gemini-3.8-flash (e le versioni precedenti gemini-3.7-flash, gemini-3.6-flash e gemini-3.5-flash)
  • gemini-3.5-flash-lite (e la precedente gemini-3.1-flash-lite)

• Modelli di generazione di immagini

  • gemini-3-pro-image (noto anche come "Nano Banana Pro")
  • gemini-3.1-flash-image (ovvero "Nano Banana 2")
  • gemini-3.1-flash-lite-image (ovvero "Nano Banana 2 Lite")

I modelli Gemini Live API non sono supportati. Tieni presente che i modelli Gemini 2.5 sono tecnicamente supportati, ma non sono consigliati per i nuovi progetti e richiedono una configurazione speciale non trattata in queste guide.

Passaggio 1: crea un progetto Firebase

Ti consigliamo di iniziare con un nuovo progetto Firebase per esplorare questa integrazione.

1. Accedi alla Firebase console.

2. Fai clic su Crea un nuovo progetto Firebase.

3. Segui le istruzioni sullo schermo. Non è necessario attivare Google Analytics.

Passaggio 2: collega l'app a Firebase

Per connettere la tua app a Firebase, devi registrarla con il tuo progetto Firebase e aggiungere un file di configurazione al tuo codebase.

1. Al centro della pagina di panoramica del progetto, fai clic sull'icona iOS+ per avviare il flusso di lavoro della configurazione.

2. Registra l'app:

   1. Inserisci l'ID pacchetto della tua app. Assicurati che corrisponda all'ID pacchetto del progetto che stai creando in Xcode.

   2. Fai clic su Registra app.

3. Aggiungi il file di configurazione di Firebase. Questo file contiene le impostazioni per la connessione dell'SDK Firebase al tuo progetto Firebase.

   1. Fai clic su Scarica GoogleService-Info.plist per ottenere il file di configurazione.

   2. Sposta GoogleService-Info.plist nella root del progetto Xcode e aggiungilo a tutti i target.

   3. Fai clic su Avanti nella console Firebase.

4. Il flusso di lavoro nella console fornisce istruzioni generiche per aggiungere l'SDK Firebase alla tua app, quindi vai al passaggio successivo di questa guida per istruzioni specifiche per Firebase AI Logic.

Passaggio 3: aggiungi le librerie Firebase e inizializza Firebase nella tua app

1. Utilizza Swift Package Manager per aggiungere le librerie Firebase richieste:

   1. In Xcode, con il progetto dell'app aperto, seleziona File > Add Packages (Aggiungi pacchetti).

   2. Inserisci l'URL del repository dell'SDK Firebase per Apple:

      https://github.com/firebase/firebase-ios-sdk
      

   3. Seleziona la regola di dipendenza come Branch e inserisci wwdc26-preview.

   4. Fai clic su Aggiungi pacchetto. Xcode risolverà e scaricherà le dipendenze.

   5. Quando richiesto, aggiungi le librerie FirebaseAILogic e FirebaseAppCheck al target dell'app.

2. Inizializza Firebase all'avvio della tua app aggiungendo il codice seguente al punto di ingresso principale dell'app:

   import SwiftUI
   import FirebaseCore
   
   @main
   struct YourApp: App {
     init() {
       FirebaseApp.configure()
     }
   
     var body: some Scene {
       WindowGroup {
         NavigationView {
           ContentView()
         }
       }
     }
   }
   

Passaggio 4: attiva e proteggi i servizi Firebase

Ora che la tua app è configurata per utilizzare Firebase, devi abilitare il servizio Firebase AI Logic e proteggere l'accesso alle API associate utilizzando Firebase App Check.

Passaggio 4a: configura Firebase AI Logic nel tuo progetto Firebase

1. Nella console Firebase, vai a Servizi AI > AI Logic.

2. Fai clic su Inizia per avviare il flusso di lavoro di configurazione guidata.

3. Quando ti viene chiesto di scegliere un "provider dell'API Gemini", ti consigliamo di selezionare l'API Gemini Developer, che ti consente di iniziare rapidamente senza costi.

   In un secondo momento, puoi sempre configurare Agent Platform Gemini API (formerly Vertex AI) (e il relativo requisito di fatturazione).

4. Continua il flusso di lavoro per configurare le API richieste e i servizi associati per Firebase AI Logic.

   A partire dall'inizio di luglio 2026, questa fase del flusso di lavoro applicherà Firebase App Check automaticamente per AI Logic, che è un servizio critico per proteggere Gemini API quando vi si accede direttamente dalla tua app. Per iniziare (vedi i passaggi più avanti in questa guida), dovrai configurare il provider di debug di App Check per lo sviluppo locale quando viene applicato App Check.

   Nota: per rilasciare la funzionalità AI della tua app agli utenti finali, devi registrare la tua app con un App Check fornitore di attestazioni di produzione in modo che possano utilizzare la funzionalità quando App Check viene applicato.

Passaggio 4b: configura il provider di debug App Check per lo sviluppo locale

Per lo sviluppo locale, devi configurare il App Check provider di debug per bypassare l'attestazione mantenendo comunque l'applicazione di App Check.

1. Nel progetto Xcode, importa FirebaseAppCheck e inizializza App Check con la fabbrica del provider di debug prima di configurare Firebase.

   import SwiftUI
   import FirebaseCore
   import FirebaseAppCheck
   
   @main
   struct YourApp: App {
     init() {
       let providerFactory = AppCheckDebugProviderFactory()
       AppCheck.setAppCheckProviderFactory(providerFactory)
       FirebaseApp.configure()
     }
   
     var body: some Scene {
       WindowGroup {
         NavigationView {
           ContentView()
         }
       }
     }
   }
   

2. Ottieni il token di debug:

   1. Avvia l'app nel simulatore o sul dispositivo di test.

   2. Apri la console Xcode e cerca il token di debug App Check. Ad esempio:

      <Warning> [AppCheckCore][I-GAC004001] App Check debug token: '123a4567-b89c-12d3-e456-789012345678'.
      

   3. Copia il token (ad esempio, 123a4567-b89c-12d3-e456-789012345678).

3. Registra il token di debug con App Check:

   1. Nella console Firebase, vai alla scheda Sicurezza > App Check > App.

   2. Trova la tua app, fai clic sul menu extra (), quindi seleziona Gestisci token di debug.

   3. Segui le istruzioni sullo schermo per registrare il token di debug.

Per informazioni dettagliate sul provider di debug (incluso come ottenere un nuovo token di debug), consulta la documentazione ufficiale di App Check.

Ecco alcuni punti fondamentali sul provider di debug App Check:

• Mantieni privati il token di debug e la build di debug. Non eseguire il commit del token di debug in un repository pubblico e non includere il token di debug o la build di debug nelle build di produzione della tua app.
• Registra la tua app presso un fornitore di attestazione di produzione prima di rilasciarla agli utenti finali. Devi registrare la tua app con un provider di attestazioni App Check di produzione (ad esempio App Attest, Play Integrity o reCAPTCHA Enterprise). in modo che gli utenti finali possano utilizzare la funzionalità con App Check applicato.

Passaggio 5: inizializza il servizio AI Logic nella tua app

Fai clic sul tuo fornitore Gemini API per visualizzare i contenuti e il codice specifici del fornitore in questa pagina. API Gemini per gli sviluppatori API Gemini di Agent Platform

Con Firebase e App Check configurati, ora puoi inizializzare il servizio Firebase AI Logic nella tua app.

import FoundationModels
import FirebaseCore
import FirebaseAILogic

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())
// Initialize a `geminiLanguageModel` with a Gemini model that supports your use case.
let model = ai.geminiLanguageModel(name: "gemini-3.8-flash")

Passaggio 6: invia una richiesta a un modello Gemini

Con Firebase AI Logic configurato, protetto e inizializzato nella tua app, puoi inviare una richiesta a un modello Gemini.

L'esempio seguente mostra il tipo di richiesta più semplice: la generazione di testo da un prompt di solo testo:

import FoundationModels
import FirebaseCore
import FirebaseAILogic

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())
// Initialize a `geminiLanguageModel` with a Gemini model that supports your use case.
let model = ai.geminiLanguageModel(name: "gemini-3.8-flash")


// Create a session by injecting the model into Apple's `LanguageModelSession`.
let session = LanguageModelSession(model: model)

// Generate a text response to a prompt.
let response = try await session.respond(to: "Write a story about a magic backpack.")
print(response.content)

I modelli Gemini supportano anche altri tipi di richieste, come l'analisi di immagini e PDF , la generazione di output JSON strutturato e la generazione di immagini (utilizzando i modelli "Nano Banana"). Vedi esempi di questi tipi di richieste nella documentazione o nell'app di esempio.

Visualizzare in streaming la risposta

Puoi ottenere interazioni più rapide senza attendere l'intero risultato della generazione del modello e utilizzare invece lo streaming per gestire i risultati parziali. Per trasmettere in streaming la risposta, utilizza streamResponse(to:) anziché respond(to:).

import FoundationModels
import FirebaseCore
import FirebaseAILogic

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())
// Initialize a `geminiLanguageModel` with a Gemini model that supports your use case.
let model = ai.geminiLanguageModel(name: "gemini-3.8-flash")


// Create a session by injecting the model into Apple's `LanguageModelSession`.
let session = LanguageModelSession(model: model)

// Generate a streamed text response to a prompt.
// To stream the response, use `streamResponse(to:)` instead of `respond(to:)`
let stream = session.streamResponse(to: "Write a story about a magic backpack.")
var response = ""
for try await snapshot in stream {
  // The snapshot contains *all* content generated so far.
  response = snapshot.content
}

Passaggi successivi

• Esplora le funzionalità disponibili quando accedi a Gemini API tramite il framework Foundation Models di Apple.
• Scopri come configurare il modello per controllare le sue risposte, inclusa l'impostazione di un livello di pensiero ("ragionamento").
• Scopri come fornire strumenti al modello, incluso il grounding per informazioni aggiornate.
• Scopri di più su Firebase App Check e su come protegge le tue risorse.

Invia feedback sull'accesso a Gemini API tramite il framework Foundation Models di Apple