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

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

Al WWDC 2026, Apple ha aperto il framework Foundation Models agli adattatori di modelli di terze parti, il che significa che puoi accedere ai modelli ospitati nel cloud (come Gemini) tramite il framework Foundation Models utilizzando la stessa API che useresti per accedere ai modelli on-device.

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

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

Puoi accedere ai modelli Geminiospitati nel 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 Gemini modelli, questa guida ti 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 Gemini modelli.

• Modelli di uso generico

  • gemini-3.1-pro-preview
  • gemini-3.5-flash
  • gemini-3.1-flash-lite

• Modelli di generazione di immagini

  • gemini-3-pro-image-preview (noto anche come "Nano Banana Pro")
  • gemini-3.1-flash-image-preview (noto anche come "Nano Banana 2")
  • gemini-2.5-flash-image (noto anche come "Nano Banana")

I modelli Gemini Live API e i modelli Imagen 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 devi attivare Google Analytics.

Passaggio 2: connetti la tua app a Firebase

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

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

2. Registra l'app:

   1. Inserisci l'ID pacchetto dell'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 dell'SDK Firebase per la connessione al tuo progetto Firebase.

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

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

   3. Fai clic su Avanti nella Firebase console.

4. Il flusso di lavoro nella console fornisce generiche istruzioni 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 (File > 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 Add Package (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 dell'app aggiungendo il seguente codice 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 l'app è configurata per utilizzare Firebase, devi attivare il Firebase AI Logic servizio 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.

3. Ti consigliamo di scegliere il provider API Gemini Developer per iniziare rapidamente senza costi.

Passaggio 4b: configura Firebase App Check nel tuo progetto Firebase

L'utilizzo di Firebase App Check per proteggere le API associate a Firebase AI Logic è fondamentale, anche durante la fase iniziale di sviluppo.

Quando è applicato, Firebase App Check consente solo le richieste in entrata che sono dalla tua app effettiva e da un dispositivo non manomesso. Firebase App Check supporta molti provider di attestazione, tra cui App Attest di Apple.

I passaggi seguenti riguardano una configurazione di base predefinita per App Check. Scopri di più su opzioni di configurazione aggiuntive per App Check (ad esempio, la regolazione del TTL dei token e l'attivazione dei token a utilizzo limitato).

Ecco come registrare il provider App Attest nella console Firebase:

1. Nella console Firebase, vai a Sicurezza > App Check.

2. Fai clic su Inizia.

3. Nella scheda App, registra la tua app per utilizzare App Check con il provider App Attest.

4. Nella scheda API, seleziona Firebase AI Logic e fai clic su Applica.

Prima di distribuire l'app, configura la funzionalità App Attest in Xcode

Nota: se intendi iniziare con il provider di debug App Check (sezione successiva), questi passaggi non sono necessari finché non distribuisci l'app. Per il momento, puoi andare alla sezione successiva.

1. In Xcode, aggiungi la funzionalità App Attest alla tua app.

2. Nel file .entitlements del progetto Xcode, imposta l' ambiente App Attest su production.

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

Per lo sviluppo locale, configura il provider di debug di App Check. La configurazione di questo provider ignora l'attestazione durante lo sviluppo, in modo che tu possa verificare la logica dell'app senza modificare la configurazione di sicurezza di produzione impostata in precedenza.

1. Nel progetto Xcode, importa FirebaseAppCheck e inizializza App Check con la factory 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. Il token viene generato all'avvio dell'app, quindi dovrebbe essere uno dei primi log visualizzati. che saranno simili a quanto segue:

      <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. Fornisci il token di debug a App Check nella Firebase console:

   1. Nella Firebase console, vai a Sicurezza > App Check > App.

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

   3. Fai clic su Aggiungi token di debug, inserisci un nome (ad esempio, My Simulator), incolla il token e poi fai clic su Salva.

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

Avviso: mantieni privato il token di debug. Questo token di debug consente a chiunque di accedere alle tue risorse Firebase AI Logic (e ai modelli Gemini) senza un dispositivo valido, quindi devi mantenerlo privato. Non eseguirne il commit in un repository pubblico. Se un token di debug registrato viene compromesso, revocalo immediatamente nella console Firebase

.

Passaggio 5: inizializza il servizio AI Logic nella tua app

Fai clic sul provider Gemini API per visualizzare contenuti specifici del provider e codice in questa pagina. API Gemini Developer API Gemini in Vertex AI

Ora che Firebase e App Check sono configurati, puoi inizializzare il Firebase AI Logic servizio 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.5-flash")

Passaggio 6: invia una richiesta a un modello Gemini

Ora che 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.5-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)

Gemini modelli 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.

Visualizza 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 visualizzare la risposta in streaming, 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.5-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 risposte, inclusa l'impostazione di un livello di pensiero ("ragionamento").
• Scopri come fornire strumenti al modello, inclusa la base per informazioni aggiornate.
• Scopri di più su Firebase App Check e su come protegge le tue risorse.

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