Utilizza Remote Config in ambienti server

Firebase Remote Config supporta la configurazione lato server utilizzando gli SDK Firebase Admin per Node.js (v12.1.0+), Python (v6.7.0+), Java (v9.7.0+) e Go (v4.17.0+).

Questa funzionalità ti consente di gestire in modo dinamico il comportamento e la configurazione delle applicazioni lato server utilizzando Remote Config. Sono incluse le implementazioni serverless come Cloud Functions for Firebase e i servizi containerizzati su Cloud Run.

A differenza degli SDK client Firebase, che recuperano una configurazione specifica del client derivata dal template Remote Config, l'SDK Remote Config lato server scarica o recupera un template Remote Config completo da Firebase. Il tuo server può quindi valutare il template con ogni richiesta in arrivo e utilizzare la propria logica per fornire una risposta personalizzata con una latenza molto bassa. Puoi utilizzare le condizioni per controllare e personalizzare le risposte in base a percentuali casuali e attributi del client definiti negli indicatori personalizzati.

Con Remote Config lato server, puoi:

  • Definisci i parametri di configurazione per le applicazioni in esecuzione o accessibili tramite il tuo server, consentendo casi d'uso come la configurazione remota dei parametri e dei prompt del modello di AI e altre integrazioni, per garantire la sicurezza delle tue chiavi API.
  • Regola dinamicamente i parametri in risposta ai cambiamenti nell'ambiente o ad altre modifiche dell'applicazione, come l'aggiornamento dei parametri LLM e degli endpoint del modello.
  • Controlla i costi aggiornando da remoto le API chiamate dal tuo server.
  • Genera configurazioni personalizzate on-the-fly per i client che accedono al tuo server.
  • Registra i client che hanno ricevuto un valore parametro e utilizzalo in Cloud Functions for Firebase come parte di un sistema di verifica dei diritti.

Puoi eseguire il deployment di Remote Config lato server su Cloud Run, Cloud Functions for Firebase o ambienti server in hosting autonomo.

Prima di iniziare

Segui le istruzioni riportate in Aggiungi l'SDK Firebase Admin al tuo server per creare un progetto Firebase, configurare un service account e aggiungere l'SDK Firebase Admin al tuo server. Assicurati di utilizzare una versione supportata dell'SDK Admin per la tua piattaforma:

  • Node.js: SDK Firebase Admin Node.js v12.1.0 o versioni successive
  • Python: SDK Firebase Admin Python v6.7.0 e versioni successive
  • Java: SDK Firebase Admin per Java v9.7.0 o versioni successive
  • Go: SDK Firebase Admin Go v4.17.0 o versioni successive

Passaggio 1: inizializza l'SDK Firebase Admin e autorizza le richieste API

Quando inizializzi l'SDK Admin senza parametri, l'SDK utilizza le Credenziali predefinite dell'applicazione Google e legge le opzioni dalla variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS. Inizializza l'SDK e configura Remote Config per la tua piattaforma:

Node.js

Importa initializeApp e getRemoteConfig, quindi inizializza l'istanza dell'applicazione Firebase:

import { initializeApp } from "firebase-admin/app";
import { getRemoteConfig } from "firebase-admin/remote-config";

// Initialize Firebase
const firebaseApp = initializeApp();

Python

Importa firebase_admin (insieme a asyncio e json per il caricamento asincrono dei modelli e l'analisi JSON), quindi inizializza l'applicazione:

import firebase_admin
import asyncio
import json

firebase_admin.initialize_app()

Java

Inizializza l'SDK Firebase Admin utilizzando FirebaseOptions e le credenziali del tuo service account:

// Initialize the Firebase Admin SDK
FirebaseOptions options = new FirebaseOptions.Builder()
    .setCredentials(GoogleCredentials.fromStream(serviceAccount))
    .build();
FirebaseApp.initializeApp(options);

Vai

Inizializza l'applicazione Firebase e crea un'istanza client RemoteConfig:

ctx := context.Background()

// Initialize Firebase
app, err := firebase.NewApp(ctx, nil)
if err != nil {
    log.Fatalln("Error initializing app:", err)
}

remoteConfig, err := app.RemoteConfig(ctx)
if err != nil {
    log.Fatalln("Error initializing remote config client:", err)
}

Passaggio 2: identifica i valori parametro predefiniti per l'applicazione server

Identifica le variabili nella tua app che vuoi aggiornare dinamicamente con Remote Config. Poi, valuta quali variabili devono essere impostate per impostazione predefinita nella tua applicazione e quali devono essere i relativi valori predefiniti. In questo modo, l'applicazione viene eseguita correttamente anche se la connessione al server di backend Remote Config viene interrotta.

Ad esempio, se stai scrivendo un'applicazione server che gestisce una funzione AI generativa, puoi impostare un nome del modello predefinito, un preambolo del prompt e una configurazione di AI generativa, come i seguenti:

Nome del parametro Descrizione Tipo Valore predefinito
model_name Nome API del modello Stringa gemini-3.8-flash
preamble_prompt Prompt da anteporre alla query dell'utente Stringa I'm a developer who wants to learn about Firebase and you are a helpful assistant who knows everything there is to know about Firebase!
generation_config Parametri da inviare al modello JSON {"stopSequences": ["I hope this helps"], "maxOutputTokens": 512}

Passaggio 3: configura l'applicazione server

Dopo aver determinato i parametri che vuoi utilizzare con Remote Config, configura l'applicazione in modo che imposti i valori predefiniti, recuperi il template Remote Config specifico per il server e ne valuti i valori.

  1. Accedi al modello di server Remote Config e caricalo.

    Node.js

    Inizializza il template del server utilizzando initServerTemplate() e chiama load() per recuperare il template dal backend:

    // Initialize server-side Remote Config
const rc = getRemoteConfig(firebaseApp);
const template = rc.initServerTemplate();

// Load Remote Config
await template.load();

    Se utilizzi Node.js all'interno di Cloud Functions for Firebase, puoi utilizzare la funzione asincrona getServerTemplate() per inizializzare e caricare il template in un unico passaggio:

    // Initialize server-side Remote Config
const rc = getRemoteConfig(firebaseApp);
const template = await rc.getServerTemplate();

    Python

    Inizializza il template del server utilizzando init_server_template() e chiama load() per recuperare il template dal backend:

    from firebase_admin import remote_config

# Initialize server-side Remote Config
template = remote_config.init_server_template()

# Load the template from the backend
asyncio.run(template.load())

    In alternativa, se utilizzi Python con Cloud Functions for Firebase, puoi utilizzare la funzione asincrona get_server_template() per inizializzare e caricare il template in un unico passaggio:

    # Initialize server-side Remote Config
template = await remote_config.get_server_template()

    Java

    Inizializza il client Remote Config lato server utilizzando FirebaseRemoteConfig.getInstance():

    // Initialize server-side Remote Config client
FirebaseRemoteConfig rc = FirebaseRemoteConfig.getInstance();

    In alternativa, se utilizzi Java con Cloud Functions for Firebase, puoi utilizzare getServerTemplate() per inizializzare e caricare il template in un unico passaggio:

    ServerTemplate template = rc.getServerTemplate();

    Vai

    Inizializza il template del server utilizzando InitServerTemplate() e chiama Load() per recuperare il template dal backend:

    // Initialize server-side Remote Config
defaultConfig := make(map[string]any)
templateDataJSON := ""
template, err := remoteConfig.InitServerTemplate(defaultConfig, templateDataJSON)
if err != nil {
    log.Fatalln("Error initializing server template:", err)
}

// Load Remote Config
err = template.Load(ctx)
if err != nil {
    log.Fatalln("Error fetching server template:", err)
}

    Un altro modo per inizializzare il modello è utilizzare la funzione GetServerTemplate per recuperare il modello lato server richiesto. Puoi convertire questo template in un formato JSON che può essere archiviato localmente e, successivamente, inizializzare questo template JSON utilizzando la funzione InitServerTemplate.

  2. Per assicurarti che l'applicazione venga eseguita correttamente anche se la connessione al server di backend Remote Config viene interrotta, aggiungi valori predefiniti per ogni parametro nell'app.

    Node.js

    Aggiungi un oggetto defaultConfig all'interno della funzione del modello initServerTemplate o getServerTemplate:

    const template = rc.initServerTemplate({
  defaultConfig: {
    model_name: "gemini-3.8-flash",
    generation_config: '{"stopSequences": [], "maxOutputTokens": 512}',
    preamble_prompt: "I'm a developer who wants to learn about Firebase and you are a helpful assistant who knows everything there is to know about Firebase!"
  },
});

// Load Remote Config
await template.load();

    Python

    Aggiungi un dizionario default_config all'interno della funzione del modello init_server_template o get_server_template:

    template = remote_config.init_server_template({
  'default_config': {
    'model_name': "gemini-3.8-flash",
    'generation_config': '{"stopSequences": [], "maxOutputTokens": 512}',
    'preamble_prompt': "I'm a developer who wants to learn about Firebase and you are a helpful assistant who knows everything there is to know about Firebase!"
  },
})

# Load Remote Config
asyncio.run(template.load())

    Un altro modo per inizializzare un modello è utilizzare la funzione get_server_template per recuperare il modello lato server richiesto. Puoi convertire questo modello in un formato JSON utilizzando la funzione template.to_json. Questo template JSON può essere archiviato localmente e puoi inizializzarlo in un secondo momento utilizzando la funzione init_server_template.

    Java

    Aggiungi un oggetto defaultConfig utilizzando KeysAndValues all'interno della funzione getServerTemplate:

    // Initialize default config using KeysAndValues
KeysAndValues defaultConfig = new KeysAndValues.Builder()
                                  .put("rc_param_1", "default value 1")
                                  .put("rc_param_2", "default value 2")
                                  .build();
ServerTemplate template = rc.getServerTemplate(defaultConfig);

    In alternativa, puoi passare un modello memorizzato nella cache predefinito durante l'inizializzazione di Remote Config, che può essere utilizzato anche quando la connessione al server Remote Config viene interrotta:

    String templateDataJSON = "{}"; // add your default template as JSON
ServerTemplate template = rc.serverTemplateBuilder()
                    .defaultConfig(defaultConfig)
                    .cachedTemplate(templateDataJSON)
                    .build();

    Vai

    Aggiungi una mappa defaultConfig all'interno della funzione del template InitServerTemplate o GetServerTemplate:

    // Initialize server-side Remote Config
defaultConfig := make(map[string]any)
defaultConfig["model_name"] = "gemini-3.8-flash"

// Assume the type generationConfig has been defined
defaultConfig["generation_config"] = &generationConfig{
    StopSequences:   []string{"I hope this helps"},
    MaxOutputTokens: 512,
}

defaultConfig["preamble_prompt"] = "I'm a developer who wants to learn about Firebase and you are a helpful assistant who knows everything there is to know about Firebase!"

templateDataJSON := ""
template, err := remoteConfig.InitServerTemplate(defaultConfig, templateDataJSON)
if err != nil {
    log.Fatalln("Error initializing server template:", err)
}

// Load Remote Config
err = template.Load(ctx)
if err != nil {
    log.Fatalln("Error fetching server template:", err)
}

  3. Dopo aver caricato il modello, valutalo per importare i parametri e i valori dal modello:

    Node.js

    Utilizza template.evaluate():

    // Add template parameters to config
const config = template.evaluate();

    Python

    Utilizza template.evaluate():

    # Add template parameters to config
config = template.evaluate()

    Java

    Utilizza template.evaluate():

    // Add template parameters to config
ServerConfig config = template.evaluate();

    Vai

    Utilizza template.Evaluate() con un contesto di valutazione vuoto quando non vengono applicate condizioni:

    // An empty evaluation context means no conditions are applied.
evaluationContext := make(map[string]any)
config, err := template.Evaluate(evaluationContext)
if err != nil {
    log.Fatalln("Error evaluating template:", err)
}

  4. Facoltativamente, se imposti condizioni nel template Remote Config, definisci e fornisci i valori di contesto che preferisci:

    • Se utilizzi condizioni di percentuale, aggiungi l'ID di randomizzazione (randomizationId, randomization_id o randomizationID) che vuoi utilizzare per valutare le condizioni all'interno della funzione di valutazione del template.
    • Se utilizzi gli indicatori personalizzati, definisci gli attributi e i relativi valori. Gli indicatori personalizzati sono disponibili con l'SDK Firebase Admin per Node.js v12.5.0 e versioni successive, l'SDK per Python v6.7.0 e versioni successive, l'SDK per Java v9.7.0 e versioni successive e l'SDK per Go v4.17.0 e versioni successive.

    Ad esempio, puoi impostare un ID installazione Firebase o un ID utente come ID di randomizzazione per assicurarti che ogni utente che contatta il tuo server venga aggiunto al gruppo randomizzato appropriato, version come indicatore personalizzato per scegliere come target versioni client specifiche e platform come indicatore personalizzato per scegliere come target le piattaforme client.

    Per saperne di più sulle condizioni, consulta Tipi di regole di condizione.

    Node.js

    Passa un oggetto di contesto di valutazione contenente randomizationId ed eventuali indicatori personalizzati a template.evaluate():

    // Add template parameters to `config`. Evaluates the
// template and returns the parameter value assigned to
// the group assigned to the {randomizationId} and version.
const config = template.evaluate({
  randomizationId: "2ac93c28-c459-4760-963d-a3974ec26c04",
  version: "1.0",
  platform: "Android"
});

    Python

    Passa un dizionario contenente randomization_id e tutti gli indicatori personalizzati a template.evaluate():

    # Add template parameters to `config`. Evaluates the
# template and returns the parameter value assigned to
# the group assigned to the {randomization_id} and version.
config = template.evaluate({
  'randomization_id': "2ac93c28-c459-4760-963d-a3974ec26c04",
  'version': "1.0",
  'platform': "Android"
})

    Java

    Crea un contesto KeysAndValues contenente randomizationId ed eventuali indicatori personalizzati e passalo a template.evaluate():

    // Add custom signals and randomizationId
KeysAndValues context = new KeysAndValues.Builder()
                                .put("custom_signal_key", "99")
                                .put("randomizationId", "2ac93c28")
                                .build();

// Evaluate the template with signals
ServerConfig config = template.evaluate(context);

    Vai

    Passa una mappa del contesto di valutazione contenente randomizationID ed eventuali indicatori personalizzati a template.Evaluate():

    // Add template parameters to `config`. Evaluates the
// template and returns the parameter value assigned to
// the group assigned to the {randomizationID}, version, and platform.
evaluationContext := make(map[string]any)
evaluationContext["randomizationID"] = "2ac93c28-c459-4760-963d-a3974ec26c04"
evaluationContext["version"] = "1.0"
evaluationContext["platform"] = "Android"

config, err := template.Evaluate(evaluationContext)
if err != nil {
    log.Fatalln("Error evaluating template:", err)
}

  5. Poi, estrai i valori dei parametri necessari dall'oggetto di configurazione valutato. Utilizza i metodi getter per eseguire il cast dei valori da Remote Config nel formato previsto.

    Ad esempio, se stai implementando Agent Platform sul tuo server e vuoi modificare il modello e i relativi parametri, puoi configurare i parametri per model_name e generation_config. Di seguito sono riportati i metodi getter supportati e un esempio di come accedere ai valori Remote Config per ogni piattaforma:

    Node.js

    Metodi getter supportati:

    • Booleano: getBoolean
    • Oggetto: getValue
    • Numero: getNumber
    • Stringa: getString

    // Replace defaults with values from Remote Config.
const generationConfig =
  JSON.parse(
    config.getString('generation_config'));

const is_ai_enabled = config.getBoolean('is_ai_enabled');

const model = config.getString('model_name');

// Generates a prompt comprised of the Remote Config
// parameter and prepends it to the user prompt
const prompt = `${config.getString('preamble_prompt')} ${req.query.prompt}`;

    Python

    Metodi getter supportati:

    • Booleano: get_bool
    • Numero intero: get_int
    • Fluttuazione: get_float
    • Stringa: get_string
    • Origine del valore: get_value_source

    # Replace defaults with values from Remote Config.
generation_config = json.loads(config.get_string('generation_config'))
is_ai_enabled = config.get_bool('is_ai_enabled')
model = config.get_string('model_name')

# Generates a prompt comprised of the Remote Config
# parameter and prepends it to the user prompt.
prompt = f"{config.get_string('preamble_prompt')}{req.args.get('prompt')}"

    Java

    Metodi getter supportati:

    • Booleano: getBoolean
    • Stringa: getString
    • Doppio: getDouble
    • Formato esteso: getLong
    • Origine del valore: getValueSource

    // Get the model name
String modelName = config.getString("model_name");
// Get the origin of value assigned to param
ValueSource modelNameSource = config.getValueSource("model_name");

    Il metodo getValueSource restituisce un ValueSource che indica se l'origine del valore del parametro è STATIC, REMOTE o DEFAULT.

    Vai

    Metodi getter supportati:

    • Booleano: GetBoolean
    • Numero intero: GetInt
    • Fluttuazione: GetFloat
    • Stringa: GetString
    • Origine del valore: GetValueSource

    // Replace defaults with values from Remote Config.

// Assume the type generationConfig has been defined
var genConfig generationConfig
err = json.Unmarshal([]byte(config.GetString("generation_config")), &genConfig)
if err != nil {
    log.Fatalln("Error unmarshaling generation config:", err)
}
model := config.GetString("model_name")

// Parameter created on the console
isAIEnabled := config.GetBoolean("is_ai_enabled")

// Generates a prompt comprised of the Remote Config
// parameter and prepends it to the user prompt (assume it is extracted from the request body)
userPrompt := "What is Remote Config?"
prompt := fmt.Sprintf("%s %s", config.GetString("preamble_prompt"), userPrompt)

  6. Se il tuo server è a lunga esecuzione, a differenza di un ambiente serverless, ricarica periodicamente il template (ad esempio, utilizzando setInterval in Node.js o java.util.Timer in Java) per verificare che stai recuperando il template più aggiornato dal server Remote Config.

Passaggio 4: imposta i valori dei parametri specifici del server in Remote Config

Poi, crea un modello Remote Config lato server e configura i parametri e i valori da utilizzare nella tua app.

Ecco come creare un modello Remote Config specifico per il server:

  1. Nella console Firebase, vai alla pagina DevOps e coinvolgimento > Remote Config > Parametri.

  2. Dal selettore Client/Server nella parte superiore della pagina, seleziona Server.

  3. Definisci i parametri Remote Config con gli stessi nomi e tipi di dati dei parametri definiti nella tua app e fornisci i valori. Questi valori eseguiranno l'override della configurazione predefinita (defaultConfig o default_config) impostata in Configura l'applicazione server quando recuperi e valuti il modello e assegni questi valori alle variabili.

  4. Facoltativamente, imposta le condizioni per applicare in modo permanente i valori a un campione casuale di istanze o indicatori personalizzati che definisci. Per saperne di più sulle condizioni, consulta Tipi di regole delle condizioni.

  5. Al termine dell'aggiunta dei parametri, fai clic su Pubblica modifiche.

  6. Rivedi le modifiche e fai di nuovo clic su Pubblica modifiche.

Passaggio 5: esegui il deployment con Cloud Functions for Firebase o Cloud Run

Se la tua applicazione server è leggera e basata su eventi, ti consigliamo di eseguire il deployment del codice utilizzando Cloud Functions for Firebase. Ad esempio, supponiamo che tu abbia un'app che include dialoghi tra personaggi basati su un'API di AI generativa (ad esempio Google AI o Agent Platform). In questo caso, puoi ospitare la logica di gestione dell'LLM in una funzione che l'app chiama on demand.

Se stai creando un'app web con rendering lato server, App Hosting supporta i framework web più diffusi.

In caso contrario, potresti prendere in considerazione Cloud Run. Per eseguire il deployment della tua app server con Cloud Run, segui la guida rapida per il tuo linguaggio:

Passaggi successivi